Odoo 19 JSON-2 API: Moderne Schnittstellen für E-Commerce-Integrationen
Für neue externe Integrationen ist unter Odoo 19 die JSON-2 API die aktuelle Schnittstellengeneration. XML-RPC und JSON-RPC existieren weiterhin, sind laut Odoo aber zur Ablösung vorgesehen. Wer heute darauf aufsetzt, plant eine spätere Migration der Integrationsschicht faktisch bereits mit ein.
Dieser Beitrag beschreibt die Schnittstelle so, wie ein Connector sie tatsächlich anspricht: Authentifizierung, Methoden, Fehlerobjekte, Idempotenz beim Massenimport und das Zusammenspiel mit den abweichenden Token-Modellen von Shopware und PlentyONE.
Protocol Shift: Warum JSON-2 der aktuelle Standard ist
Odoo hat die älteren Endpoints /xmlrpc, /xmlrpc/2 und /jsonrpc offiziell zur Entfernung vorgemerkt – laut Odoo für Odoo 22 (Herbst 2028) beziehungsweise für Odoo Online 21.1 (Winter 2027). Die JSON-2 API ist der benannte Nachfolger. Für Neuentwicklungen bedeutet das: Ein Aufsetzen auf XML-RPC wäre technisch zwar aktuell noch möglich, architektonisch aber bereits absehbar überholt.
Eine wichtige Einschränkung, die vor jeder Zielarchitektur-Entscheidung geklärt werden sollte: Die Verfügbarkeit der externen API hängt vom Betriebsmodell und der Edition ab. Bei Odoo Online (SaaS) ist der externe API-Zugriff laut Odoo ausschließlich in Custom-Plänen verfügbar – in den One-App-Free- und Standard-Plänen ist er nicht freigeschaltet. Bei selbst gehosteten Instanzen (On-Premise oder Odoo.sh) steht die JSON-2 API ab den Custom-Tarifen zur Verfügung, in der Community Edition grundsätzlich.
Für eine Shopware-Odoo-Integration folgt daraus eine klare Voraussetzung: Es braucht entweder die Community Edition oder einen Custom-Plan. Wer diese Frage erst nach der Architekturentscheidung klärt, riskiert, ein Betriebsmodell gewählt zu haben, das die geplante Integration technisch gar nicht zulässt.
Stateless Authentication
Die Authentifizierung erfolgt vollständig zustandslos über einen API-Key, der als Bearer Token im HTTP-Header übertragen wird. Ein API-Key lässt sich über die Odoo-Kontosicherheitseinstellungen anlegen; die programmatische Verwaltung ist standardmäßig auf Benutzer mit Administrationsrechten beschränkt.
Ein verifizierter Beispielaufruf gegen eine selbst gehostete Odoo-19-Instanz:
curl -X POST "${ODOO_URL}/json/2/res.partner/search_read" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ODOO_API_KEY}" \
-d '{"domain":[],"limit":1}'Neben Authorization und Content-Type sind zwei weitere Header in der Praxis relevant: X-Odoo-Database, erforderlich, wenn ein Server mehrere Datenbanken hostet und der dbfilter den Host-Header nicht auswertet; und User-Agent, von Odoo empfohlen, um in Migrationsprojekten mit mehreren parallelen Prozessen Migrationslast von regulärem Connector-Traffic serverseitig unterscheiden zu können.
Syntax, Methoden und Fehlerbehandlung
Die JSON-2 API stellt mehrere zentrale Methoden bereit:
| Methode | Funktion |
|---|---|
search_read | Suchen und gleichzeitiges Lesen, inklusive Pagination und komplexer Filter (Domains) |
read | gezieltes Auslesen spezifischer Datensätze anhand ihrer IDs |
write | Aktualisieren bestehender Datensätze |
unlink | dauerhaftes Löschen von Datensätzen |
load | Batch-Import-Methode aus dem CSV-Import-Mechanismus, für Massendaten deutlich performanter als einzelne create()-Aufrufe |
Ein praktischer Vorteil der JSON-2 API gegenüber älteren Schnittstellen: Sie liefert echte HTTP-Statuscodes (200 für Erfolg, 401 für fehlerhafte Authentifizierung, 429 für Rate Limits), was das Exception Handling im Connector deutlich vereinfacht. Im Fehlerfall liefert die API zusätzlich ein JSON-serialisiertes Fehlerobjekt mit den Feldern name (vollqualifizierter Name der Python-Exception), message, arguments, context und debug. Besonders name lässt sich auswerten, um fachliche Fehler wie Validierungsverstöße von technischen Fehlern wie Authentifizierungsproblemen zu unterscheiden – und die Retry-Entscheidung entsprechend zu steuern.
Ein Beispiel für diese Unterscheidung in der Praxis: Meldet die API einen Validierungsfehler, weil ein Pflichtfeld fehlt, ist ein automatischer Retry sinnlos – der Fehler wird beim nächsten Versuch identisch auftreten, solange die Daten nicht korrigiert werden. Meldet die API dagegen einen Authentifizierungsfehler, könnte dieser auf einen abgelaufenen oder ungültigen Token hindeuten, der sich durch eine erneute Anmeldung beheben lässt. Ein Connector, der beide Fälle gleich behandelt – etwa durch pauschales, wiederholtes Retry ohne Unterscheidung –, verschleiert echte Datenprobleme hinter scheinbaren technischen Störungen.
Die load-Methode: Performance und Idempotenz
Für Massenimporte im Rahmen einer ERP-Migration ist die load()-Methode der zentrale Baustein. Sie verarbeitet mehrere Datensätze innerhalb eines einzelnen Modellaufrufs und reduziert dadurch gegenüber vielen einzelnen create()-Aufrufen den API- und ORM-Overhead spürbar – der tatsächliche Performancegewinn hängt dabei von Modell, Feldern, Constraints und Datenmenge ab.
Der eigentliche Grund, warum load() für Migrationen die richtige Wahl ist, liegt aber nicht in der Performance, sondern in der Idempotenz: load() akzeptiert eine Spalte id, die nicht die numerische Datenbank-ID meint, sondern die externe ID (XML-ID) des Datensatzes – einen frei vergebbaren, systemübergreifend stabilen Bezeichner in der Form modul.bezeichner. Odoo führt diese externen IDs im Modell ir.model.data und pflegt dort die Zuordnung zur internen Datenbank-ID. Ein Datensatz mit bereits vorhandener externer ID wird dadurch bei wiederholtem Import aktualisiert statt dupliziert – die Grundlage für beliebig wiederholbare Testmigrationen.
Authentifizierung im Systemvergleich
Für eine Shopware-Odoo-Integration ist relevant, dass alle drei beteiligten Systeme zwar dasselbe Token-Format verwenden (Authorization: Bearer <Token>), sich aber in der Token-Beschaffung unterscheiden:
- Odoo 19 (JSON-2): Der API-Key wird unmittelbar als Bearer Token verwendet, ohne Token-Austausch. Der Key verfällt nicht von selbst; eine Refresh-Logik ist im Connector nicht erforderlich.
- Shopware 6 (Admin API): Authentifizierung über OAuth 2.0 Client-Credentials-Flow; der resultierende Access Token ist nur 600 Sekunden gültig. Für längere Extraktionsläufe muss der Connector den Token proaktiv erneuern, statt auf den ersten 401-Fehler zu warten.
- PlentyONE (REST API): Authentifizierung ebenfalls über OAuth 2.0; der Token ist 86.400 Sekunden (24 Stunden) gültig – deutlich unkritischer für einzelne Läufe, aber relevant bei über Tage laufenden, budgetgesteuerten Extraktionen.
Dynamische Runtime-Dokumentation
Ein praktischer Vorteil der JSON-2 API für die Integrationsarbeit: Jede Odoo-Instanz stellt unter dem Pfad /doc eine laufzeitgenerierte Dokumentation bereit. Laut Odoo sind die tatsächlich verfügbaren Modelle, Felder und Methoden für jede Datenbank spezifisch und lassen sich genau auf dieser /doc-Seite einsehen.
Das ist deshalb relevant, weil sich Odoo-Instanzen in ihrem tatsächlichen Datenmodell unterscheiden – abhängig von installierten Modulen, aktivierten Funktionen und individuell angelegten Custom Fields wie den in Migrationsprojekten verwendeten x_shopware_uuid-Feldern. Eine statische, versionsgebundene API-Dokumentation könnte diese instanzspezifischen Unterschiede nicht abbilden.
Für einen Connector bedeutet das in der Praxis: Vor dem produktiven Einsatz sollte die tatsächliche Feldstruktur der Zielinstanz über /doc geprüft werden, statt sich ausschließlich auf eine allgemeine Dokumentation zu verlassen. Das gilt insbesondere für Custom Fields, die im Rahmen einer Migration nachträglich zum Datenmodell hinzugefügt wurden – sie erscheinen nur in der instanzspezifischen Laufzeitdokumentation, nicht in der allgemeinen Odoo-Kerndokumentation.
JSON-2 als Basis der Shopware-Odoo-Integration
Die JSON-2 API bildet die Transportbasis für die laufende Synchronisation zwischen Shopware und Odoo. Fehlerbehandlung und Retry-Logik liegen dabei bewusst beim aufrufenden Client, nicht bei der API selbst: JSON-2 führt keine automatischen Wiederholungsversuche aus. Wie diese Client-seitige Fehlerbehandlung, Event-Verarbeitung und Queue-Anbindung konkret aufgebaut werden, zeigt Odoo Shopware 6 Connector.
Die JSON-2 API ist die technische Grundlage der Integration. Wie sie sich in die Gesamtarchitektur einer ERP-Migration einfügt, zeigt unser Überblick zur Migration von PlentyONE zu Odoo.
Häufig gestellte Fragen zur Odoo JSON-2 API
Können wir eine bestehende XML-RPC-Integration einfach weiterlaufen lassen?
Technisch ist das für eine gewisse Übergangszeit möglich, da die Entfernung erst für spätere Odoo-Versionen angekündigt ist. Für neue Entwicklungen empfiehlt sich dennoch direkt die JSON-2 API, um nicht kurz- bis mittelfristig eine erneute Migration der Integrationsschicht einplanen zu müssen.
Was passiert, wenn unser gewähltes Odoo-Hosting-Modell keinen externen API-Zugriff erlaubt?
Dann steht die JSON-2 API in ihrer vollen Funktion nicht zur Verfügung, was eine Shopware-Integration erheblich erschwert oder unmöglich macht. Diese Voraussetzung sollte deshalb vor der endgültigen Wahl des Hosting-Modells geprüft werden, nicht danach.
Ist die JSON-2 API auch für sehr große Datenmengen geeignet?
Ja, insbesondere in Kombination mit der batchfähigen load()-Methode, die mehrere Datensätze pro Aufruf verarbeitet. Für Massenmigrationen mit mehreren hunderttausend Artikeln ist das die empfohlene Vorgehensweise gegenüber einzelnen create()-Aufrufen.
Quellen
Die Aussagen zur JSON-2 API, zum /doc-Endpoint und zur Verfügbarkeit des externen API-Zugriffs je Odoo-Plan basieren auf der offiziellen Odoo-Dokumentation: External JSON-2 API sowie External RPC API. Hinweis: Odoo hat den Entfernungszeitpunkt der RPC-Schnittstellen bereits einmal verschoben (ursprünglich Odoo 20/2026, aktuell Odoo 22/2028 bzw. Online 21.1/2027) – diese Angabe sollte vor jeder Veröffentlichung erneut gegen die Live-Dokumentation geprüft werden.
API-Architektur für Ihre Migration prüfen lassen
Ob Ihr gewähltes Odoo-Betriebsmodell und Ihre Edition die JSON-2 API im benötigten Umfang überhaupt bereitstellen und wie die konkrete Integrationsarchitektur zu Ihrem bestehenden Shopsystem aussehen sollte, klären wir im Rahmen unseres kostenlosen, unverbindlichen E-Commerce Audits.
Lassen Sie Ihre API-Architektur technisch prüfen – kostenfrei und unverbindlich.
„Wir sind unsicher, ob unser geplantes Odoo-Hosting die benötigte API überhaupt freischaltet.“ Das ist die erste Frage, nicht die letzte. Ohne externen API-Zugriff ist die hier beschriebene Integration technisch nicht umsetzbar – diese Voraussetzung steht deshalb vor jeder Architekturentscheidung, nicht danach.
✔ kostenlos ✔ unverbindlich ✔ geprüft gegen reale Odoo-19-Instanzen ✔ Antwort innerhalb von 24 Stunden
Christopher Einenkel
Christopher Einenkel ist der strategische Kopf der HQ GmbH für hochentwickelte Systemintegrationen und komplexe API-Architekturen. Immer wenn Datensynchronisationen an harte Grenzen stoßen oder anspruchsvolle Enterprise-Systeme wie Salesforce an Shopify angebunden werden müssen, konzipiert er maßgeschneiderte, hochperformante Schnittstellen-Logiken.
Sein Track Record umfasst die Eigenentwicklung proprietärer Enterprise-Lösungen, darunter automatisierte KI-Übersetzungstools für Artikelstammdaten, lückenlose B2B-Einkaufssysteme sowie automatisierte Marktbewertungs- und Wettbewerbsüberwachungen. Darüber hinaus steuert er für unsere Großkunden die technische Implementierung und API-Vernetzung digitaler Software-Callcenter-Anlagen in bestehende CRM- und ERP-Landschaften.
