Odoo 19 mit anderen Systemen integrieren: APIs, Webhooks, Konnektoren und Middleware

Nur sehr wenige Unternehmen kommen mit einem einzigen System aus. Selbst wenn Odoo das zentrale ERP ist, muss es meist mit einem Zahlungsdienstleister, einem Versanddienstleister, einer Bank, einem Onlineshop, einem Zeiterfassungsgerät oder einer Altanwendung kommunizieren. Die Qualität dieser Verbindungen entscheidet darüber, ob Ihre Daten verlässlich sind oder ob Ihr Team jeden Monat Differenzen von Hand abstimmt.

Odoo 19 Enterprise bietet einen mehrstufigen Werkzeugkasten: integrierte Konnektoren, die in den Apps konfiguriert werden, eine externe API für Entwickler, Automatisierungsregeln, die Webhooks empfangen und senden können, sowie Dateiimporte für Fälle, in denen keine Live-Verbindung möglich ist. Middleware-Tools setzen darauf auf, wenn Sie die Orchestrierung zwischen vielen Systemen benötigen.

Ein Hinweis zu den Quellen: Dieser Artikel folgt der offiziellen Odoo-Dokumentation für Version 19.0 (dem Repository odoo/documentation). Menüs, Optionen und Tarifbedingungen können sich je nach Version und Hosting-Art ändern. Prüfen Sie daher jeden Schritt in einer Test- oder duplizierten Datenbank, bevor Sie ihn in der Produktion anwenden.

Das passende Integrationsmuster wählen

Gehen Sie vom geschäftlichen Bedarf aus, nicht von der Technologie. Fragen Sie, welche Daten in welche Richtung, wie schnell fließen müssen und wer den führenden Datensatz besitzt. Wählen Sie dann die schlankeste Option, die den Bedarf erfüllt.

• Nutzen Sie einen integrierten Konnektor, wenn Odoo den Anbieter bereits unterstützt, etwa einen gelisteten Zahlungsanbieter, Versanddienstleister, Anbieter für Banksynchronisierung oder den Amazon-Konnektor.
• Nutzen Sie die externe API, wenn eine andere Anwendung Odoo-Datensätze nach eigenem Zeitplan lesen oder schreiben muss.
• Nutzen Sie einen eingehenden Webhook, wenn ein externes System ein Ereignis in dem Moment an Odoo übermitteln soll, in dem es eintritt.
• Nutzen Sie einen ausgehenden Webhook, wenn Odoo nach einer Änderung ein anderes System benachrichtigen soll, zum Beispiel wenn ein Datensatz angelegt oder ein Feld aktualisiert wird.
• Nutzen Sie Middleware, wenn mehrere Systeme beteiligt sind, Daten stark transformiert werden müssen oder Sie zentrale Wiederholungsversuche und ein zentrales Monitoring benötigen.
• Nutzen Sie den Dateiimport, wenn die Gegenseite nur Dateien liefert, etwa Kontoauszüge im Format CAMT.053, OFX, QIF, CSV oder XLSX.

Die externe API in Odoo 19: JSON-2 und API-Schlüssel

Odoo 19 führt die JSON-2-API ein, die einen Teil des ORM über HTTP bereitstellt. Jeder Aufruf ist eine POST-Anfrage an einen Endpunkt der Form /json/2/, gefolgt vom Modell- und Methodennamen, zum Beispiel die Methode search_read des Modells res.partner. Der Request-Body enthält die Methodenargumente als JSON.

Zur Authentifizierung wird ein API-Schlüssel im Authorization-Header als Bearer-Token gesendet. Einen separaten Anmeldeschritt mit Benutzer-ID und Passwort gibt es nicht; der Schlüssel identifiziert den Benutzer, und die Integration handelt mit dessen Zugriffsrechten.

Um einen Schlüssel manuell anzulegen, öffnen Sie Ihre Benutzereinstellungen, gehen zu „Kontosicherheit“ und wählen „Neuer API-Schlüssel“. Beschreibung und Gültigkeitsdauer sind Pflichtangaben, und der Schlüsselwert wird nur einmal angezeigt – speichern Sie ihn daher sofort in einem sicheren Secrets-Tresor. Laut Dokumentation lassen sich Schlüssel für höchstens drei Monate erstellen; planen Sie also von Anfang an eine Routine für die Schlüsselrotation.

Hostet ein Server mehrere Datenbanken, teilt der optionale Header X-Odoo-Database Odoo mit, auf welche Datenbank der Aufruf zielt. Achten Sie hinter einem Reverse Proxy darauf, dass der Host-Header Odoo korrekt erreicht.

Jeder JSON-2-Aufruf läuft in einer eigenen Datenbanktransaktion: Bei Erfolg wird sie festgeschrieben, bei einem Fehler zurückgerollt. Mehrere Aufrufe lassen sich nicht zu einer Transaktion verketten. Bevorzugen Sie daher eine einzelne Methode, die die zusammengehörige Arbeit erledigt, etwa search_read oder eine Geschäftsmethode, statt vieler kleiner Aufrufe, die Daten halb aktualisiert zurücklassen können.

Fehler werden mit einem HTTP-Status 4xx oder 5xx und einem JSON-Body zurückgegeben, der einen Namen und eine Meldung enthält. Ihr Client-Code sollte beides auslesen und protokollieren.

Legacy XML-RPC und JSON-RPC: die Migration planen

Viele bestehende Integrationen nutzen die älteren XML-RPC-Endpunkte oder den JSON-RPC-Endpunkt. In Odoo 19 sind diese veraltet, und laut offizieller Dokumentation ist ihre Entfernung für Odoo 22 vorgesehen. Sie funktionieren heute noch, doch neue Projekte sollten auf JSON-2 aufbauen, und bestehende sollten erfasst und im Rahmen Ihrer Upgrade-Roadmap migriert werden.

• Erfassen Sie jedes Skript, jeden Konnektor und jedes Drittanbieter-Tool, das die alten Endpunkte aufruft.
• Ersetzen Sie die Authentifizierung per Benutzername und Passwort durch eigene API-Schlüssel je Integration.
• Schreiben Sie mehrstufige Abfolgen nach Möglichkeit in einzelne Aufrufe um, da jeder Aufruf eine eigene Transaktion ist.
• Testen Sie die migrierte Version gegen eine duplizierte Datenbank, bevor Sie den Produktionsverkehr umstellen.

Auch die Verfügbarkeit je Tarif spielt eine Rolle. Laut Dokumentation ist der Datenzugriff über die externe API nur in den Odoo-Tarifen Custom verfügbar, nicht in One App Free oder Standard. Prüfen Sie Ihr Abonnement, bevor Sie eine API-basierte Integration auf Odoo Online konzipieren.

Webhooks und Automatisierungsregeln

Mit Automatisierungsregeln kann Odoo ohne eigene Module auf Ereignisse reagieren. In Odoo 19 Enterprise verwalten Sie sie in Studio über das Menü „Automatisierungen“, und eingehende Webhooks haben in Studio zusätzlich einen eigenen Eintrag „Webhooks“. Der Entwicklermodus bietet mehr Kontrolle, einschließlich der Wahl des Zielmodells.

Für einen eingehenden Webhook legen Sie eine Regel mit dem Auslöser „Bei Webhook“ an. Odoo erzeugt die URL automatisch; das externe System sendet eine POST-Anfrage mit einem JSON-Payload an diese URL. Der Code für den Zieldatensatz teilt Odoo mit, auf welchen Datensatz sich der Payload bezieht, und der Reiter „Auszuführende Aktionen“ legt fest, was danach geschieht – typischerweise eine Aktion „Code ausführen“, wenn Sie Datensätze anlegen statt einen einzelnen aktualisieren müssen.

Aktivieren Sie „Aufrufe protokollieren“, während Sie die Regel aufbauen und Fehler suchen. Damit wird die Historie der Anfragen an die URL erfasst, die Sie über die intelligente Schaltfläche „Protokolle“ der Regel öffnen können.

Behandeln Sie die Webhook-URL als Geheimnis. Die Dokumentation warnt, dass ihre Weitergabe unbeabsichtigten Zugriff auf die Datenbank ermöglichen kann. Ist sie kompromittiert, erzeugen Sie mit „Secret rotieren“ eine neue URL und aktualisieren das externe System.

Für ausgehende Benachrichtigungen fügen Sie einer Regel die Aktion „Webhook-Benachrichtigung senden“ hinzu. Sie sendet eine POST-Anfrage mit den Werten der ausgewählten Felder an die angegebene URL, und ein Beispiel-Payload hilft Ihnen, die Struktur vor dem Livegang zu prüfen.

Verwenden Sie beim Schreiben von Aktionen vom Typ „Code ausführen“ die Funktion log, um Meldungen in die Protokolltabelle der Datenbank zu schreiben, damit Fehler für fachliche Benutzer sichtbar sind und nicht nur in den Serverprotokollen.

Studio ist Teil von Odoo Enterprise. In Community gibt es keine Studio-Oberfläche; dieselben Anforderungen werden dort meist über Konfiguration im Entwicklermodus oder über kleine eigene Module abgedeckt, die ein Entwickler pflegt.

Integrierte Konnektoren für gängige Integrationen

Prüfen Sie, bevor Sie Code schreiben, ob Odoo den Anbieter bereits abdeckt. Integrierte Konnektoren werden mit jedem Release gepflegt und sind in der Regel die sicherste Wahl.

• Zahlungsdienstleister: Konfigurieren Sie sie in der App Buchhaltung, Website oder Verkauf unter Konfiguration > Zahlungsanbieter. Zu den gelisteten Anbietern gehören Stripe, Adyen, PayPal, Paymob, Mollie, Razorpay und weitere. Geben Sie die Zugangsdaten im Reiter „Anmeldedaten“ ein und nutzen Sie zunächst den Testmodus mit Sandbox-Zugangsdaten, idealerweise in einer duplizierten Datenbank, um die Rechnungsnummerierung zu schützen. Das Zahlungsjournal muss ein Bankjournal sein.
• Versanddienstleister: Aktivieren Sie sie in den Lager-Einstellungen im Abschnitt Versandkonnektoren. Zu den unterstützten Konnektoren gehören DHL Express, FedEx, UPS, Sendcloud, EasyPost und weitere. Jede Versandmethode startet in einer Testumgebung; der Wechsel in die Produktion erzeugt echte Etiketten, die der Versanddienstleister in Rechnung stellen kann – prüfen Sie daher zuerst Tarife und Etiketten. Die Option „Anfragen debuggen“ protokolliert die ausgetauschten Nachrichten.
• Banken: Die Banksynchronisierung importiert Transaktionen über Drittanbieter wie Plaid, Yodlee, Salt Edge, Ponto, Enable Banking und Basiq und setzt ein gültiges Enterprise-Abonnement voraus. Wird Ihre Bank nicht abgedeckt, importieren Sie Kontoauszugsdateien aus dem Bankjournal im Dashboard der Buchhaltung.
• E-Commerce und Marktplätze: Die eigene App E-Commerce von Odoo nutzt dieselbe Datenbank, daher ist kein Konnektor nötig. Für Amazon synchronisiert der Amazon-Konnektor Bestellungen in Verkaufsaufträge und ordnet Produkte über die interne Referenz zu.
• Zeiterfassungsgeräte: Die App Anwesenheiten unterstützt den Kioskmodus auf einem dedizierten Gerät sowie das Einstempeln im Backend. Biometrische Terminals anderer Hersteller deckt die offizielle Dokumentation nicht ab; sie werden daher meist über ein eigenes Modul oder Middleware angebunden, die die Stempelungen an Odoo übermittelt.

Middleware wie n8n

Middleware-Plattformen wie n8n sitzen zwischen Odoo und anderen Systemen. Es handelt sich um Drittanbieter-Tools, die nicht Teil von Odoo sind und über dieselbe externe API und dieselben Webhooks wie oben beschrieben mit Odoo kommunizieren.

Sie sind nützlich, wenn ein Ereignis mehrere Systeme aktualisieren muss, wenn die Feldzuordnung komplex ist oder wenn Sie einen visuellen Ablauf mit zentraler Fehlerbehandlung und Wiederholungsversuchen wünschen. Der Preis dafür ist eine zusätzliche Komponente, die gehostet, abgesichert, überwacht und aktualisiert werden muss – und es gelten weiterhin dieselben Tarifbedingungen für den API-Zugriff.

Gestaltungsregeln: Idempotenz, Fehlerbehandlung und Protokollierung

Die meisten Integrationsprobleme entstehen durch wiederholte Nachrichten, Teilausfälle und stille Fehler. Planen Sie vom ersten Tag an dafür.

• Machen Sie jeden Schreibvorgang idempotent: Speichern Sie die externe Referenz am Odoo-Datensatz und prüfen Sie sie vor dem Anlegen, damit ein erneut gesendeter Webhook oder ein wiederholter Aufruf keinen doppelten Auftrag und keine doppelte Zahlung erzeugt.
• Legen Sie fest, wem jedes Feld gehört, und lassen Sie nie zwei Systeme denselben Wert überschreiben.
• Halten Sie einen Geschäftsvorgang nach Möglichkeit in einem Aufruf, da jeder JSON-2-Aufruf eine eigene Transaktion ist.
• Wiederholen Sie nur bei vorübergehenden Fehlern, mit zunehmenden Wartezeiten, und leiten Sie dauerhafte Fehler in eine Prüfwarteschlange.
• Protokollieren Sie bei jedem Austausch Anfrage, Antwort und die Referenz des Odoo-Datensatzes, mit „Aufrufe protokollieren“, „Anfragen debuggen“ oder der Historie Ihrer Middleware.
• Überwachen Sie in den ersten Wochen täglich Volumen und Fehler und stimmen Sie Summen wie Zahlungen, Sendungen und Banksalden zwischen den Systemen ab.

Sicherheits-Checkliste

• Legen Sie einen eigenen Integrationsbenutzer an, der nur die Zugriffsrechte hat, die die Integration benötigt, und erzeugen Sie dessen API-Schlüssel über diesen Benutzer.
• Verwenden Sie einen Schlüssel je Integration, halten Sie seinen Zweck in der Beschreibung fest, wählen Sie eine kurze Gültigkeitsdauer und rotieren Sie ihn vor Ablauf.
• Speichern Sie Schlüssel und Webhook-URLs in einem Secrets-Manager, niemals in Tabellen, Chatnachrichten oder im Quellcode.
• Widerrufen Sie Schlüssel und rotieren Sie Webhook-Secrets sofort, wenn eine Lieferantenbeziehung endet oder ein Leck vermutet wird.
• Verwenden Sie immer HTTPS und entwickeln und testen Sie jede Integration in einer duplizierten Datenbank, bevor Sie sie in der Produktion aktivieren.

Wie 1CBMS Sie unterstützen kann

1CBMS konzipiert und implementiert Integrationen für Odoo 19 für Unternehmen in Ägypten und im Irak – von der Konfiguration von Zahlungsanbietern, Versanddienstleistern und Bank-Feeds über den Aufbau von Integrationen mit der JSON-2-API und Webhooks und die Migration von Legacy-Skripten auf XML-RPC-Basis bis zur Anbindung von Zeiterfassungsgeräten und eigenen Systemen über eigene Module oder Middleware. Wir beginnen mit einer Übersicht über Datenverantwortung und Datenflüsse, testen alles in einer duplizierten Datenbank und übergeben eine klare Dokumentation und ein Monitoring, damit Ihr Team den Zahlen vertrauen kann. Kontaktieren Sie uns unter www.1cbms.com, um Ihre Integrationslandschaft prüfen zu lassen.