Tutorial zur Odoo REST- und XML-RPC-API-Integration: Verbinden Sie jedes System

Odoo stellt sein gesamtes Datenmodell über externe APIs zur Verfügung und ermöglicht so die Integration in praktisch jedes System – E-Commerce-Plattformen, CRM-Tools, Business-Intelligence-Software, mobile Apps und benutzerdefinierte Anwendungen. Dieses Tutorial behandelt alle drei API-Protokolle (XML-RPC, JSON-RPC und REST), Authentifizierungsmethoden, CRUD-Operationen und reale Integrationsmuster mit Codebeispielen und Best Practices.

Wichtige Erkenntnisse

• Odoo bietet drei API-Protokolle: XML-RPC (am ausgereiftesten), JSON-RPC (browserfreundlich) und REST (Odoo 19, OpenAPI-kompatibel) – Alle APIs erfordern eine Authentifizierung mit Datenbankname, Benutzername und Passwort oder API-Schlüssel
• CRUD-Operationen folgen einem einheitlichen Muster über alle Protokolle hinweg: Suchen, Lesen, Erstellen, Schreiben, Verknüpfung aufheben
• Domänenfilter verwenden für komplexe Abfragen eine polnische Notationssyntax
• Paginierung, Feldauswahl und Stapeloperationen optimieren die Leistung großer Datensätze

API-Protokollvergleich

Authentifizierung

XML-RPC-Authentifizierung

Die XML-RPC-Authentifizierung verwendet einen zweistufigen Prozess: Authentifizieren Sie sich, um eine Benutzer-ID (UID) zu erhalten, und verwenden Sie diese UID dann für nachfolgende Aufrufe.

Der Authentifizierungsaufruf erreicht den Endpunkt /xmlrpc/2/common mit der Methode authenticate und übergibt den Datenbanknamen, den Benutzernamen, das Kennwort und ein leeres Objekt. Die Antwort ist die numerische Benutzer-ID. Alle nachfolgenden Datenaufrufe verwenden /xmlrpc/2/object mit der Methode execute_kw und übergeben die Datenbank, die UID, das Kennwort, den Modellnamen, den Methodennamen und die Argumente.

JSON-RPC-Authentifizierung

JSON-RPC verwendet sitzungsbasierte Authentifizierung über den Endpunkt /web/session/authenticate. Der Anforderungstext ist ein JSON-Objekt mit jsonrpc: "2.0", einer Methode von call und Parametern, die db, login und password enthalten. Die Antwort enthält eine Sitzungs-ID im Cookie, die nachfolgende Anfragen authentifiziert.

REST-API-Authentifizierung (Odoo 19)

Die REST-API unterstützt im Odoo-Backend generierte API-Schlüssel:

1. Navigieren Sie zu Einstellungen > Benutzer > API-Schlüssel
2. Generieren Sie einen neuen Schlüssel mit den angegebenen Berechtigungen
3. Fügen Sie den Schlüssel in den Header Authorization: Bearer ein

REST-Endpunkte folgen dem Muster /api/{model} für Sammlungen und /api/{model}/{id} für einzelne Datensätze.

CRUD-Operationen

Suchen und lesen

Der häufigste Vorgang besteht darin, nach Datensätzen mit bestimmten Kriterien zu suchen und deren Feldwerte zu lesen.

Domänenfilter verwenden die polnische Notation (Präfixnotation) mit Operatoren:

Bedingungen kombinieren: Verwenden Sie & (AND), | (OR) und ! (NOT) als Präfixoperatoren:

• UND: ['&', ['state', '=', 'sale'], ['amount_total', '>', 1000]] entspricht Verkaufsaufträgen über 1000
• ODER: ['|', ['state', '=', 'sale'], ['state', '=', 'done']] stimmt mit einem der beiden Bundesstaaten überein
• Komplex: ['&', ['state', '=', 'sale'], '|', ['partner_id', '=', 5], ['partner_id', '=', 10]]

Feldauswahl: Fordern Sie nur die Felder an, die Sie benötigen, um die Nutzlastgröße zu reduzieren und die Leistung zu verbessern. Übergeben Sie einen fields-Parameter mit einer Liste von Feldnamen. Wenn es weggelassen wird, werden alle Felder zurückgegeben.

Paginierung: Verwenden Sie die Parameter offset und limit, um Ergebnisse zu paginieren. Beispiel: offset: 20, limit: 20 gibt die Datensätze 21-40 zurück.

Datensätze erstellen

Erstellen Sie Datensätze, indem Sie die Methode create mit einem Wörterbuch von Feldwerten aufrufen. Erforderliche Felder müssen enthalten sein. Die Antwort gibt die ID des neu erstellten Datensatzes zurück (oder ein Array von IDs für die Batch-Erstellung).

Beispiel: Zum Erstellen eines Kontakts ist mindestens das Feld name erforderlich. Zu den optionalen Feldern gehören email, phone, company_id, street, city, state_id, country_id und benutzerdefinierte Felder.

Verwenden Sie für verwandte Datensätze (one2many oder Many2many) spezielle Befehlstupel:

Datensätze aktualisieren

Aktualisieren Sie Datensätze, indem Sie die Methode write mit den Datensatz-IDs und einem Wörterbuch geänderter Felder aufrufen. Schließen Sie nur Felder ein, die geändert werden müssen. Ausgelassene Felder behalten ihre aktuellen Werte.

Stapelaktualisierungen werden unterstützt: Übergeben Sie eine Liste von IDs, um mehrere Datensätze mit denselben Werten in einem einzigen Aufruf zu aktualisieren.

Datensätze löschen

Löschen Sie Datensätze, indem Sie die Methode unlink mit den Datensatz-IDs aufrufen. Bei Erfolg gibt die Methode „True“ zurück.

Seien Sie beim Löschen vorsichtig – viele Odoo-Datensätze sind durch Geschäftsregeln geschützt. Der Versuch, beispielsweise eine gebuchte Rechnung zu löschen, führt zu einem Fehler. Verwenden Sie stattdessen die entsprechende Geschäftsmethode (z. B. button_cancel vor dem Löschen).

Integrationsmuster in der realen Welt

E-Commerce-Auftragssynchronisierung

Synchronisieren Sie Bestellungen von einer externen E-Commerce-Plattform mit Odoo:

1. Umfrage nach neuen Bestellungen: Fragen Sie die E-Commerce-API nach Bestellungen seit dem letzten Synchronisierungszeitstempel ab
2. Kunden abgleichen: Odoo-Kontakte per E-Mail durchsuchen; erstellen, falls nicht gefunden
3. Auftrag erstellen: Erstellen Sie den Auftrag mit Kunden-, Posten-, Versand- und Zahlungsinformationen
4. Bestellung bestätigen: Rufen Sie action_confirm auf, um die Bestellung über den Workflow zu verarbeiten
5. E-Commerce aktualisieren: Senden Sie die Odoo-Bestellreferenz zurück an die E-Commerce-Plattform

Inventarsynchronisierung

Halten Sie die Lagerbestände zwischen Odoo und einem externen Kanal synchronisiert:

1. Lagerbestände lesen: Rufen Sie search_read auf stock.quant mit Standortfiltern auf
2. Push-Updates: Mengenänderungen an den externen Kanal senden
3. Reservierungen bearbeiten: Konto für reservierten Lagerbestand (für ausstehende Bestellungen reserviert)
4. Synchronisierung planen: Alle 15–30 Minuten ausführen, um die Genauigkeit zu gewährleisten

CRM-Lead-Import

Importieren Sie Leads von Marketingplattformen in Odoo CRM:

1. Leads abrufen: Ziehen Sie neue Leads aus der Marketingplattform-API
2. Deduplizieren: Durchsuchen Sie Odoo per E-Mail oder Telefon nach vorhandenen Kontakten
3. Leads erstellen: Erstellen Sie Datensätze in crm.lead mit Quellenverfolgung
4. Zuweisen: Verwenden Sie die Lead-Zuweisungsregeln von Odoo oder weisen Sie basierend auf benutzerdefinierter Logik zu

Finanzdatenexport

Finanzdaten auf eine Business-Intelligence-Plattform exportieren:

1. Kontenplan exportieren: Lesen Sie account.account für die Kontostruktur
2. Journaleinträge exportieren: account.move.line mit Datumsfiltern lesen
3. Salden exportieren: Verwenden Sie read_group, um Salden nach Konto und Zeitraum zu aggregieren
4. Zeitplan: Wird täglich nach dem Fenster zum Schließen der Buchhaltung ausgeführt

Fehlerbehandlung

Häufige API-Fehler

Ratenbegrenzung

Odoo erzwingt standardmäßig keine API-Ratenbegrenzungen, aber Produktionsbereitstellungen sollten Ratenbegrenzungen auf der Reverse-Proxy-Ebene implementieren. Für Odoo.sh gelten Standardlimits, um Missbrauch zu verhindern. Entwerfen Sie Integrationen mit angemessenen Abfrageintervallen und Batch-Vorgängen.

Wiederholungsstrategie

Implementieren Sie einen exponentiellen Backoff für vorübergehende Fehler:

1. Erster Wiederholungsversuch nach 1 Sekunde
2. Zweiter Wiederholungsversuch nach 4 Sekunden
3. Dritter Wiederholungsversuch nach 16 Sekunden
4. Protokollierung und Warnung nach der maximalen Anzahl an Wiederholungsversuchen

Leistungsoptimierung

Batch-Operationen

Bevorzugen Sie Batch-Vorgänge gegenüber der Verarbeitung einzelner Datensätze:

– create akzeptiert eine Liste von Wertewörterbüchern für die Stapelerstellung

• write akzeptiert eine Liste von IDs für Batch-Updates
• search_read mit Paginierung ist effizienter als einzelne read-Aufrufe

Feldauswahl

Geben Sie immer den Parameter fields an, um das Laden unnötiger Daten zu vermeiden. Das Laden aller Felder in einem Modell mit mehr als 50 Spalten führt zu einem erheblichen Mehraufwand, insbesondere bei Modellen wie sale.order oder account.move.line.

Caching

Langsam ändernde Daten lokal zwischenspeichern:

• Produktkatalog (stündlich aktualisieren)
• Kundenliste (Aktualisierung bei Änderungsbenachrichtigung)
• Steuersätze und Finanzpositionen (täglich aktualisieren)

ECOSIRE-Integrationsdienste

Der Aufbau zuverlässiger Integrationen erfordert ein Verständnis sowohl des externen Systems als auch des Datenmodells von Odoo. Die Odoo-Integrationsdienste von ECOSIRE umfassen API-Design, Connector-Entwicklung, Datenzuordnung und laufende Überwachung. Für Unternehmen, die E-Commerce-Plattformen verbinden, bewältigen unsere spezialisierten Shopify-Odoo-Integration und Marktplatz-Konnektoren die häufigsten Szenarien.

Verwandte Lektüre

• Odoo API-Integrationsleitfaden
• ETL-Pipelines für ERP-Daten: Odoo und Shopify
• Docker Odoo-Bereitstellungshandbuch
• Entwicklungshandbuch für benutzerdefinierte Odoo-Module
• API-Sicherheit: Authentifizierung und Autorisierung

Welches API-Protokoll sollte ich für eine neue Integration wählen?

Für neue Projekte auf Odoo 19 nutzen Sie die REST API. Es folgt HTTP-Standards, verfügt über eine automatisch generierte Dokumentation und unterstützt API-Schlüssel zur Authentifizierung. Für Odoo 17 oder 18 ist XML-RPC die zuverlässigste und am besten dokumentierte Option. JSON-RPC eignet sich am besten für browserbasierte Integrationen oder JavaScript-Anwendungen.

Gibt es eine Ratenbegrenzung für die externe API von Odoo?

Odoo selbst erzwingt keine Ratenbegrenzungen. Für Odoo.sh-Bereitstellungen gelten jedoch Einschränkungen auf Infrastrukturebene, und selbst gehostete Bereitstellungen sollten eine Ratenbegrenzung auf der Reverse-Proxy-Ebene (Nginx) implementieren. Entwerfen Sie Integrationen, um Batch-Vorgänge und angemessene Abfrageintervalle unabhängig von Einschränkungen zu verwenden.

Kann ich Workflows (Bestellung bestätigen, Rechnung buchen) über die API auslösen?

Ja. Verwenden Sie die Methode execute_kw mit dem Namen der Workflow-Methode. Rufen Sie beispielsweise action_confirm bei einem Verkauf auf, um ihn zu bestätigen, oder action_post bei einem Konto.Umzug, um einen Journaleintrag zu buchen. Die Workflow-Methoden erzwingen dieselben Geschäftsregeln wie die Benutzeroberfläche.