Eigene Bestellanbindung über die Mergado Marketplaces API#

Mergado Marketplaces verfügt über fertige Bestellanbindungen für Systeme wie POHODA, Shoptet Premium, WooCommerce, UNAS oder Upgates. Wenn Sie Ihre Bestellungen in einem anderen System verwalten — zum Beispiel in einem eigenen ERP, einer Lagerverwaltungssoftware oder einer internen Anwendung — können Sie diese selbst über die Mergado Marketplaces API anbinden. Sie benötigen dafür lediglich eine Entwicklerin oder einen Entwickler, die bzw. der die Anbindung auf der Seite Ihres Systems programmiert.

Über die API können Sie:

  • Bestellungen herunterladen von allen in Mergado Marketplaces angebundenen Marktplätzen (Allegro, Kaufland, Amazon), einschließlich aller Daten, die der CSV-Export enthält: Kunde, Rechnungs- und Lieferadresse, Zahlung, Versand, Bestellpositionen, Dokumente und Notizen,
  • Bestellungen als importiert markieren, indem Sie die zugehörige ID aus Ihrem System hinterlegen — beim nächsten Download erhalten Sie so nur neue Bestellungen,
  • den Bestellstatus ändern, einschließlich Sendungsnummer und Spediteur. Die Änderung wird direkt an Allegro oder Kaufland übermittelt,
  • eine Rechnung zu einer Bestellung auf Allegro oder Kaufland hochladen.

Die vollständige technische Dokumentation finden Sie in der Mergado Marketplaces API-Dokumentation. Sie listet alle Endpunkte, deren Parameter und das Format der Antworten auf. Die Aufrufe können Sie direkt mit den Daten Ihres Onlineshops ausprobieren.

📝 Gut zu wissen:

  • Die API-Dokumentation und Fehlermeldungen sind auf Englisch.
  • Die API richtet sich an Entwicklerinnen und Entwickler. Wenn Sie Bestellungen ohne Programmierung anbinden möchten, prüfen Sie, ob Ihr System zu den fertigen Anbindungen in Mergado Marketplaces gehört.

Was Sie benötigen#

  • Eine aktive Erweiterung Mergado Marketplaces mit mindestens einem angebundenen Marktplatz.
  • Einen Personal Access Token (PAT) aus Ihrem Mergado-Konto mit der Berechtigung Read e-shop data (Lesen der Daten des Onlineshops).
  • Die ID Ihres Onlineshops in Mergado.
  • Eine Entwicklerin oder einen Entwickler, die bzw. der die Anbindung in Ihrem System programmiert.

⚠️ Verwenden Sie entweder die API oder eine fertige Onlineshop-Anbindung — nicht beides gleichzeitig. Wenn Sie in Mergado Marketplaces eine aktive Bestellanbindung an eine E-Commerce-Plattform (etwa Shoptet Premium, Upgates oder WooCommerce) haben und dieselben Bestellungen gleichzeitig über die API verarbeiten, können sich beide Systeme gegenseitig die Bestellstatus überschreiben.

Einrichtung der Anbindung#

1. Erstellen Sie einen Personal Access Token#

  1. Klicken Sie in Mergado Editor oben rechts auf Ihr Profil und öffnen Sie API and Access (API und Zugänge).
  2. Klicken Sie auf + Create token (Token erstellen), geben Sie dem Token einen Namen (zum Beispiel „Bestellanbindung ERP") und legen Sie seine Gültigkeitsdauer fest.
  3. Aktivieren Sie in den Berechtigungen unter der Gruppe E-shop die Option Read e-shop data (Lesen der Daten des Onlineshops). Die Mergado Marketplaces API benötigt keine weiteren Berechtigungen.
  4. Erstellen Sie den Token, kopieren Sie ihn und speichern Sie ihn sicher. Nach dem Verlassen der Seite wird er nicht mehr angezeigt.

Die ausführliche Anleitung finden Sie im Artikel Persönlicher Zugriffstoken (PAT).

⚠️ Verwechseln Sie nicht Read e-shop data (Lesen der Daten des Onlineshops) in der Gruppe E-shop mit Read user’s e-shops (Lesen der Onlineshops des Benutzers) in der Gruppe User. Die Mergado Marketplaces API benötigt Ersteres.

Der Token hat Zugriff auf dieselben Onlineshops wie Ihr Konto. Zum Lesen von Bestellungen genügt Lesezugriff auf den Onlineshop. Für die Änderung eines Bestellstatus, das Hochladen einer Rechnung oder das Hinterlegen einer eigenen Bestell-ID ist Schreibzugriff auf den Onlineshop erforderlich.

2. Ermitteln Sie die ID Ihres Onlineshops#

Jeder API-Aufruf enthält die numerische ID des Onlineshops in Mergado. Am einfachsten ermitteln Sie diese, indem Sie in den Einstellungen unter API and Access (API und Zugänge) die Anzeige interner IDs aktivieren. Die ID des Onlineshops erscheint dann in Klammern neben seinem Namen. Die Vorgehensweise ist im Artikel Anzeige interner Entitäts-IDs beschrieben.

3. Probieren Sie die API in der Dokumentation aus#

  1. Öffnen Sie die Mergado Marketplaces API-Dokumentation.
  2. Klicken Sie auf Authorize und geben Sie Ihren Personal Access Token ein.
  3. Wählen Sie beispielsweise den Endpunkt zur Auflistung von Bestellungen, geben Sie die ID Ihres Onlineshops ein und klicken Sie auf Try it out und dann auf Execute.

Die Dokumentation zeigt Ihnen eine echte Antwort mit Ihren Bestelldaten sowie die genaue Anfrage-URL, die Ihre Entwicklerin oder Ihr Entwickler direkt verwenden kann.

4. Binden Sie Ihr System an#

Alle Aufrufe laufen über die Mergado API unter der Adresse https://api.mergado.com/apps/ordelogyproducts/proxy. Der Token wird im Header Authorization: Bearer <Ihr Token> übermittelt. Die konkreten Endpunkte und Parameter findet Ihre Entwicklerin bzw. Ihr Entwickler in der Dokumentation.

Empfohlener Ablauf für die Bestellsynchronisation#

Für den regelmäßigen Abruf von Bestellungen in Ihr System empfehlen wir folgendes Vorgehen:

  1. Laden Sie Änderungen in regelmäßigen Abständen herunter. Verwenden Sie beim Auflisten von Bestellungen den Parameter updated_since mit dem Zeitpunkt des letzten Downloads. Sie erhalten neue Bestellungen sowie alle, bei denen sich seit dem etwas geändert hat — zum Beispiel Status, Daten, ein Synchronisationsfehler oder eine hochgeladene Rechnung.
  2. Markieren Sie jede Bestellung nach dem Import. Speichern Sie die ID, die die Bestellung in Ihrem System hat. Mit dem Parameter imported=false listen Sie anschließend nur Bestellungen auf, die noch nicht importiert wurden.
  3. Schreiben Sie Änderungen zurück. Wenn Sie eine Bestellung in Ihrem System versenden, übermitteln Sie über die API den Status SENT mit der Sendungsnummer. Die Änderung wird direkt auf den Marktplatz übertragen. Auf dieselbe Weise können Sie auch eine Rechnung hochladen.

Zeitangaben ohne Zeitzone interpretiert die API als mitteleuropäische Zeit (Europe/Prague). In der gleichen Zeitzone befinden sich auch alle Zeitangaben in den Antworten.

Bestellstatus#

Mergado Marketplaces bildet die Status der einzelnen Marktplätze auf einheitliche Status ab. In der API erscheinen sie wie folgt:

API-Status Status in Mergado Marketplaces
OPEN offen
READY nicht versendet
PROCESSING wird verarbeitet
SENT versendet
ONHOLD pausiert
RETURNED zurückgegeben
CANCELLED storniert
UNKNOWN unbekannt

Über die API können folgende Status gesetzt werden:

Marktplatz Setzbare Status
Allegro PROCESSING, SENT, CANCELLED, ONHOLD
Kaufland PROCESSING, SENT, CANCELLED

Bei Amazon können Bestellungen über die API nur gelesen werden.

Der Status in Mergado Marketplaces ändert sich erst, wenn der Marktplatz ihn akzeptiert. Lehnt er ihn ab, gibt die API einen Fehler mit dem Grund des Marktplatzes zurück, und der Fehler erscheint auch bei der Bestellung in Mergado Marketplaces. Eine fehlgeschlagene Änderung wird nicht automatisch wiederholt. Sie können einen Status, den die Bestellung bereits hat, erneut senden — zum Beispiel wenn Sie zu einer bereits versendeten Bestellung nachträglich die Sendungsnummer ergänzen möchten.

Rechnungen#

Zu einer Bestellung auf Allegro oder Kaufland können Sie über die API eine PDF-Rechnung mit einer Größe von höchstens 5 MB zusammen mit der Rechnungsnummer hochladen. Das Ergebnis des Uploads sehen Sie im Bestellverlauf in Mergado Marketplaces.

Limits#

  • Von einer einzelnen IP-Adresse können höchstens 60 Anfragen pro Minute gesendet werden.
  • Ein einzelner Aufruf gibt höchstens 1.000 Bestellungen zurück. Weitere Bestellungen können seitenweise abgerufen werden.

FAQ#

Benötige ich für die API eine spezielle Anbindung in Mergado Marketplaces?#

Nein. Ein Personal Access Token und die ID des Onlineshops genügen. Im Abschnitt Connections (Anbindungen) prüfen Sie lediglich, ob die Bestellsynchronisation für die jeweiligen Marktplätze aktiviert ist. Für die API müssen Sie nichts weiter einrichten.

Die API gibt den Fehler 403 „Missing required scope: shop.read" zurück. Was soll ich tun?#

Der Token hat keine Berechtigung Read e-shop data (Lesen der Daten des Onlineshops). Erstellen Sie einen neuen Token und aktivieren Sie diese Berechtigung in der Gruppe E-shop.

Die API gibt den Fehler 403 „Access denied for this eshop" zurück. Was soll ich tun?#

Ihr Konto hat keinen ausreichenden Zugriff auf den Onlineshop, oder die ID des Onlineshops stimmt nicht überein. Überprüfen Sie die ID des Onlineshops und Ihre Zugriffsrechte. Für die Statusänderung, das Hochladen von Rechnungen und das Hinterlegen einer Bestell-ID ist Schreibzugriff erforderlich. Ein neu erteilter Zugriff kann bis zu 5 Minuten benötigen, bis er wirksam wird.

Die API gibt den Fehler 401 zurück. Was soll ich tun?#

Die Anfrage enthält keinen Token, oder der Token ist ungültig. Prüfen Sie, ob Sie den vollständigen Token im Header Authorization senden und ob seine Gültigkeitsdauer abgelaufen ist oder er widerrufen wurde.

Warum fehlen mir beim Download nach Datum die Statusänderungen älterer Bestellungen?#

Die Parameter date_from und date_to filtern nach dem Datum, an dem die Kundin oder der Kunde die Bestellung aufgegeben hat. Statusänderungen bei älteren Bestellungen — zum Beispiel Stornierungen — werden damit nicht erfasst. Verwenden Sie für die regelmäßige Synchronisation den Parameter updated_since.

Kann ich die API gleichzeitig mit einer Onlineshop-Plattform-Anbindung nutzen?#

Wir empfehlen das nicht. Wenn Bestellungen gleichzeitig von einer Onlineshop-Anbindung (etwa Shoptet Premium oder Upgates) und Ihrem System über die API verarbeitet werden, können sie sich gegenseitig die Bestellstatus überschreiben. Verwenden Sie für die Bestellübertragung entweder die API oder die fertige Anbindung.

Kann ich über die API mit mehreren Onlineshops arbeiten?#

Ja. Der Token funktioniert für alle Onlineshops, auf die Ihr Mergado-Konto Zugriff hat. In jedem Aufruf geben Sie die ID des Onlineshops an, mit dem Sie arbeiten möchten.

Helfen Sie uns bei der Anbindung?#

Die Anbindung selbst programmiert Ihre Entwicklerin oder Ihr Entwickler anhand der Dokumentation. Wenn Sie bei der Anbindung auf ein Problem stoßen oder in der API eine benötigte Angabe fehlt, wenden Sie sich an den Mergado-Support.

Was this article helpful?