Product Sync API

Ihre Lieferanten aktualisieren regelmäßig die bereitgestellten Produktinformationen. Um die Übernahme der neuen Daten in Ihr System (PIM, Webshop, ERP, etc.) möglichst komfortabel, leichtgewichtig und standardisiert zu gestalten, bietet OXOMI die Product Sync API.

Die Kernidee bei dieser API ist, dass Sie bei jedem Aufruf nur die Liste derjenigen Produkte erhalten, die sich seit dem vorherigen Aufruf der API tatsächlich auch geändert haben.

Statt also jedesmal eine vollständige Datenlieferung einpflegen zu müssen, erhalten Sie das sogenannte „Delta“, also die minimale Menge an Aktualisierungen, um Ihre Produktdaten auf den neuesten Stand zu bringen.

Bedeutung des API-Token

Damit OXOMI sowohl den Zugang authentifizieren als auch die Unterschiede seit der letzten Synchronisierung berechnen kann, werden API-Tokens verwendet. Diese legen Sie in den Einstellungen des Portals an, über das Sie die Produkte beziehen wollen.

Link zu den API-Tokens in der Übersichtskachel für ein Portal

Bei jedem API-Token finden Sie das Shared Secret, das zur Berechnung des Access Tokens benötigt wird. Beim Access Token handelt es sich sozusagen um ein sich regelmäßig änderndes Passwort. Details zur Berechnung der Authentifizierung finden sich hier.

Senden Sie bitte niemals direkt das Shared Secret an den Server! Verwenden Sie dieses nur, um auf einem sicheren System den Access Token zu berechnen!

Des Weiteren speichert jeder API-Token den Zeitpunkt des letzten Datenabgleichs. Dieser Wert wird durch die Nutzung der API fortlaufend aktualisiert. Sie können den Wert jedoch auch manuell anpassen, um nötigenfalls in die Synchronisierung einzugreifen.

Einstellungsmoglichkeiten eines API-Tokens

Jeder API-Token ist fest verknüpft mit einem konkreten Synchronisationsdatum und daher exklusiv zu nutzen. Wenn Sie mehrere Systeme synchronisieren wollen, verwenden Sie bitte unbedingt separate API-Tokens für jedes System! Andernfalls ist es wahrscheinlich, dass Sie unvollständige Deltas erhalten.

Ablauf der Synchronisation

Die API selbst besteht aus zwei Endpunkten.

Zunächst rufen Sie /portals/api/v2/products/changed auf, um die geänderten Produkte seit der letzten Synchronisation zu erhalten. Neben notwendigen Authentifizierungsparametern benötigen Sie insbesondere den Parameter syncStart, der das aktuelle Datum enthalten muss. Als Antwort wird ein JSON-Objekt übermittelt. Dieses enthält unter dem Schlüsselwort products eine Liste der geänderten Produktinformationen als strukturierte Daten. Weitere Details finden Sie in der API-Dokumentation.

Sollten sich seit der letzten Synchronisierung mehr als 512 Produkte geändert haben, können nicht alle Informationen in einer Antwort ausgeliefert werden. In diesem Fall enthält die JSON-Antwort unter dem Schlüsselwort continuationToken einen von - abweichenden Wert. In diesem Fall müssen Sie /portals/api/v2/products/changed nochmals aufrufen und dabei den Parameter continuationToken auf den Wert aus der letzten JSON-Antwort setzen. Setzen Sie außerdem syncStart unbedingt auf den gleichen Wert wie beim ersten Aufruf. Sie erhalten dann den nächsten Teil der geänderten Produkte. Wiederholen Sie dies so lange, bis das JSON-Objekt in der Antwort unter dem Schlüsselwort continuationToken den Wert - enthält. Erst dann haben Sie in mehreren Teilen das vollständige Delta vorliegen.

Bei einem neuen API-Token ist zunächst kein Datum für die letzte Synchronisation gesetzt. Sie erhalten dann bei der ersten Synchronisation den vollen Produktdatenbestand. Um dies zu verhindern, können Sie beim API-Token ein Datum manuell einpflegen.

Wenn Sie Übersetzungen zu ETIM-Klassen und -Merkmalen beziehen wollen, muss der Parameter classificationLabelLanguages zwingend gesetzt werden. Andernfalls werden keine entsprechenden Werte ausgeliefert.

Sobald Sie den vollständigen Satz an Änderungen vorliegen haben, müssen Sie OXOMI den Empfang der Daten noch bestätigen. Rufen Sie hierzu den Endpunkt /portals/api/v1/core/update-sync-date auf und übergeben Sie im Parameter date das Datum, das Sie zuvor beim ersten Abruf der geänderten Produkte genutzt haben. Dies aktualisiert am API-Token den Zeitpunkt des letzten Datenabgleichs, sodass Sie dann beim nächsten Aufruf der API nur noch die zwischenzeitlich aktualisierten Produktdaten erhalten. Weitere Details finden sich in der API-Dokumentation.

Sowohl beim wiederholten Aufruf von /portals/api/v2/products/changed als auch von /portals/api/v1/core/update-sync-date muss stets das gleiche Datum verwendet werden. Stellen Sie hierzu einmalig vor Beginn der Synchronisation das aktuelle Datum fest und nutzen dieses dann bei allen entsprechenden Aufrufen. Andernfalls können zwischenzeitlich aktualisierte Produkte bei der nächsten Synchronisation fehlen.

Rate-Limiting

Eine Beschränkung der Abfragehäufigkeit, sogenanntes Rate-Limiting, findet nicht statt. Wie zuvor beschrieben kann es je nach anfallender Datenmenge jedoch notwendig sein, über das Continuation Token mehrere sich ergänzende Abfragen zu starten.

Weiterführende Hinweise

Wegen der API-Tokens sollte die Product Sync API, auch zum Testen, nur in eigenen Portalen verwendet werden. Das systemweite Demo-Portal ist hierfür nicht geeignet. Nachdem pro Portal mehrere Tokens angelegt werden können, können und sollten Sie für die Entwicklung einfach ein separates Token nutzen. Wenden Sie sich gegebenenfalls für weitere Unterstützung an unseren Support unter support@scireum.net / +49 (0)7151 90316-20 / Live-Support .

Wichtig ist weiterhin, wie grundsätzlich für viele Funktionalitäten von OXOMI, dass Sie in Ihren Partnerschaften die Lieferantennummern pflegen.

Unabhängig von der Synchronisation können jederzeit alle Daten für einzelne Produkte auch über /portals/api/v2/products/spx abgerufen werden. Die Dokumentation dieser API findet sich hier.