Mirakl ist kein Marktplatz: Es ist die Plattform hinter vielen, und das verändert die Anbindung an Odoo

Mirakl ist kein Marktplatz, auf dem man verkauft. Es ist die Software, mit der ein Händler seinen eigenen Marktplatz betreibt: Leroy Merlin, Carrefour, Kingfisher, Macy's oder Best Buy werden heute auf der Website von Mirakl als Kunden genannt. Wenn Sie von einem Betreiber eingeladen werden, verkaufen Sie beim Betreiber (seine Kategorien, seine Provision, sein Vertrag), aber Ihr Odoo spricht mit der Mirakl-API, die bei allen dieselbe ist. Ein gut gebauter Mirakl-Konnektor ist nicht «der Konnektor für Leroy Merlin»: Es sind N Marktplätze mit einer einzigen API und unterschiedlichen Zugangsdaten. Und schwierig ist nicht die API, sondern die Verteilung des Bestands auf die Kanäle, die auf dasselbe Lager schauen.

Was alle Mirakl-Betreiber gemeinsam haben und was nicht

Die Verkäufer-API von Mirakl hat für jede Aufgabe einen Operationscode, unabhängig davon, wie der Betreiber heißt: OR11 listet Bestellungen auf, OR23 und OR24 übermitteln die Sendungsverfolgung und markieren den Versand, OR28 erstattet zurück, OF01 lädt Angebote per Datei hoch, IV01 liefert die Abrechnungsdokumente, M11 ist die Nachrichtenfunktion mit dem Käufer und SH21 listet die Zusteller auf. Ein Betreiber kann ganze Funktionsgruppen abgeschaltet haben (manche bieten weder Nachrichten noch Zusteller an, und der Konnektor markiert den Endpunkt bei einem 404 oder 410 als nicht verfügbar), aber wo sie angeboten wird, ist es derselbe Aufruf.

Anders ist alles, was nicht zur API gehört: der Host (adeo-marketplace.mirakl.net bei Leroy Merlin), der Schlüssel und der Shop, der Kategorienbaum und die Pflichtattribute (4.844 Kategorien und 35.364 Attribute in unserem Leroy-Merlin-Konto), die zugelassenen Zusteller (165 Codes), die Rückerstattungsgründe, die Währung und vor allem der Steuermodus: Manche senden die Preise inklusive MwSt. (TAX_INCLUDED), andere ohne (TAX_EXCLUDED). Dieser Punkt hat uns einen echten Fehler beschert: Der Konnektor nahm den Preis inklusive MwSt. als Basis, Odoo addierte die Steuer ein zweites Mal, und aus 48,86 € wurden 59,12 €. Geprüft an den 20 echten Bestellungen des Kontos.

Abbildung in Odoo: ein Konto pro Betreiber

In unserem Mirakl-Konnektor ist jeder Betreiber eine Instanz: ein Datensatz mit Basis-URL, API-URL, Schlüssel, Shop, Unternehmen, Lagerhaus und Verkaufsteam. Beim Verbindungstest liest er /platform/configuration, /account und /channels aus und vermerkt, welche Plattform antwortet, welcher Shop es ist und welche Funktionen er anbietet. Im Screenshot lautet die erkannte Plattform «Marketplace Adeo» und der erkannte Anbieter leroy_merlin.

An der Instanz hängt alles, was zum Betreiber gehört: das Wörterbuch aus Kategorien, Attributen und Werten (eindeutig pro Instanz und Code, sodass sich zwei Betreiber nie in die Quere kommen), die Zuordnung von Kategorien und Zustellern sowie die Preis- und Bestandsregeln. Ein Odoo-Produkt hat pro Instanz ein Binding: dasselbe Produkt, bei jedem Betreiber ein anderes Angebot mit eigener SKU, eigenem Preis und eigener Menge. Einen zweiten Betreiber hinzuzufügen (GACD, dessen Verkäufer-API unter tdmp.mirakl.net antwortet, oder jeden anderen) bedeutet eine weitere Instanz. Die Profile im Katalog füllen nur Standardwerte aus; der Code, der mit Mirakl spricht, ist ein einziger.

Das eigentliche Problem: den Bestand verteilen

Zwei Mirakl-Betreiber, ManoMano, Amazon, Temu oder Ihr eigener Shop können auf dasselbe Lager schauen. Nur die ersten beiden sind Mirakl: Die anderen haben eine eigene Verkäufer-API (bei Amazon die SP-API) und sind eigene Konnektoren. Aber alle verkaufen gegen denselben Bestand, und keiner weiß etwas von den anderen: Jeder erhält die Menge, die Sie exportieren, und verkauft dagegen bis zum nächsten Export. Das lässt sich nicht «in Echtzeit» lösen, denn weder die API noch der Betreiber funktionieren so; es wird mit Regeln pro Kanal gelöst. Jede Instanz entscheidet vier Dinge, bevor sie eine Menge veröffentlicht:

• Welche Menge betrachtet wird: vorrätig, prognostiziert, frei (abzüglich Reserviertem) oder vorrätig nur in den Lagerhäusern dieser Instanz.
• Wie viel zurückgehalten wird: ein Puffer pro Instanz, der die Verkäufe anderer Kanäle zwischen zwei Exporten abdeckt.
• Mindestmenge zur Veröffentlichung: Bleiben nach dem Puffer weniger als N Einheiten übrig, wird null veröffentlicht: Die letzte Einheit an drei Stellen zu verkaufen, ist der klassische Überverkauf.
• Maximal veröffentlichte Menge: eine Obergrenze pro Instanz, damit einem Betreiber kein Bestand gezeigt wird, der schon einem anderen zugesagt ist.

Die Reihenfolge steht im Code: Menge gemäß Strategie, abzüglich Puffer, null, wenn das Minimum nicht erreicht wird, Kürzung auf das Maximum. Bei 12 freien Einheiten, Puffer 2, Minimum 3 und Maximum 5 sieht jeder Betreiber 5. Erhalten alle einfach die vorrätige Menge, lässt der Erste, der die letzte Einheit verkauft, die anderen ins Leere verkaufen. Puffer und Taktung behandeln wir in Bestand in Echtzeit für Marktplätze, und wie sich alles aus einem einzigen Odoo steuern lässt, in auf mehreren Marktplätzen verkaufen und unter Lösungen.

Bestellungen und Status: von Mirakl zu Odoo und zurück

Mirakl kennt mehr Bestellstatus, als Odoo braucht, und reduziert sie auf sechs: WAITING_ACCEPTANCE, WAITING_DEBIT, STAGING und INCIDENT_OPEN sind «ausstehend»; SHIPPING «im Versand» (der Käufer hat bezahlt und die Versandfrist läuft); SHIPPED «versendet»; RECEIVED und CLOSED «abgeschlossen»; CANCELED und REFUSED «storniert»; REFUNDED «rückerstattet». Die Bestellung im Screenshot kam als SHIPPED herein, wurde auf «Enviado» abgebildet und mit dem Verkaufsauftrag S00509 verknüpft, mit Währung, Summe und Steuer aus dem Payload des Betreibers.

Der Rückweg: Die ausstehende Bestellung wird mit einem PUT an /orders/{id}/accept angenommen, in Stapeln mit einer Obergrenze pro Durchlauf; beim Validieren des Lieferscheins wird die Sendungsverfolgung übermittelt (OR23) und der Versand markiert (OR24), und der Lieferschein wird mit Anfrage und Antwort gestempelt; die validierte Rechnung wird zur Bestellung hochgeladen (OR74), nachdem die vorherige desselben Typs gelöscht wurde (OR72, OR76). Und das inkrementelle Zeitfenster wird nach Aktualisierungsdatum abgefragt, nicht nach Erstellungsdatum: Eine Bestellung, die Wochen später den Status wechselt, käme sonst nie wieder herein.

Wo es zu Duplikaten kommt, wenn der Konnektor nicht idempotent ist

An drei Stellen. Die Bestellung: Die Datenbank lehnt zwei Datensätze mit derselben Kennung in derselben Instanz ab (unique(instance_id, mirakl_order_id)); der Import aktualisiert den vorhandenen. Der Versand: Der Konnektor liest vorher den Status erneut aus; ist er bereits SHIPPED, wird nichts wiederholt, und schlägt das erneute Auslesen fehl, nimmt er nichts an und ruft auf, denn «bereits versendet» bei einem Timeout als gegeben anzunehmen, hinterließ Bestellungen ohne Sendungsverfolgung. Und die Rückerstattung, bei der es um Geld geht: Beim Audit der Version 16.15.1 stellten wir fest, dass der HTTP-Client jede Anfrage bei 5xx oder Timeout wiederholte, auch die von OR28. Ein Timeout sagt nicht, dass die Anfrage nicht angekommen ist: Er sagt, dass Sie es nicht wissen. Heute werden nur Lesezugriffe wiederholt, außer beim 429, der garantiert, dass nichts verarbeitet wurde; und die Schaltfläche weigert sich, eine zweite vollständige Rückerstattung zu senden, wenn die Bestellung bereits als rückerstattet geführt wird.

Abrechnungen: was die API liefert und warum sie einen eigenen Abgleich verdient

Mirakl zahlt nicht Bestellung für Bestellung: Es überweist periodisch einen Nettobetrag, und IV01 liefert das Dokument, das ihn erklärt, mit dem überwiesenen Betrag und vier Töpfen: Bestellungen, Provisionen, Rückerstattungen und zurückerstattete Provisionen. Der Konnektor speichert jedes Dokument pro Instanz (Zeitraum, Währung, Zahlungsstatus) und berechnet aus den Töpfen ein eigenes Netto. Was bis zum überwiesenen Betrag fehlt, sind «sonstige Gebühren», fast immer die Grundgebühr des Betreibers: Eine reale Abrechnung schleppte 39,00 € Differenz mit, bis wir diesen Rest eingebaut haben; so steht er als eigene Zeile da, statt sich in einer namenlosen Differenz zu verstecken.

Wann sich ein Mirakl-Betreiber nicht lohnt

Dass die API dieselbe ist, heißt nicht, dass jede Einladung ein Ja verdient. Der Aufwand für den Einstieg liegt im Katalog, nicht in der Integration: Ihre Kategorien gegen einen Baum mit Tausenden Knoten abzubilden und die Pflichtattribute jeder Produktfamilie auszufüllen, ist Handarbeit und wiederholt sich bei jedem Betreiber. Wenige passende Kategorien, eine Provision, die nach der Grundgebühr die Marge auffrisst, oder eine Annahmefrist, die Ihr Lager nicht einhält: Nichts davon lohnt sich, so einfach die Anbindung auch ist. Das Signal liefert die Instanz, bevor Sie etwas veröffentlichen: Wörterbuch synchronisieren, zehn Familien zuordnen und zählen, wie viele Pflichtattribute Ihnen fehlen. Sind es Hunderte, kostet es Sie mehr, als es Ihnen einbringt.

Der Konnektor, mit dem wir all das umgesetzt haben, ist mit echten Bestellungen produktiv und grün (163 von 163 Tests) unter Odoo 19, 18 und 17, nach dem Audit der Version 16.15.1 (121 mögliche Befunde, 18 bestätigt). Wenn Sie den Mirakl-Konnektor eines anderen übernehmen, steht in Audit eines geerbten Odoo-Konnektors, worauf Sie achten sollten; wenn die Plattform, die mit Odoo sprechen soll, Ihre eigene ist, geht es um einen Odoo-Konnektor für Ihre Software.

Häufige Fragen

Nützliche Links bei FlexigoTech

Was wir dafür tun