Product Sync API

Hinweis

Die in diesem Artikel beschriebene Funktionalität steht Ihnen ab dem Paket „enterprise“ oder nach individueller Vereinbarung zur Verfügung. Kontaktieren Sie für weitere Informationen gerne unseren Support unter support@scireum.net / +49 711 / 205 004 - 10 / Live-Support .

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/v3/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/v3/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/v3/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.

Datenblöcke

Die Product Sync API liefert die Produktinformationen in sogenannten Datenblöcken aus. Dies hat den Vorteil, dass Sie nur die Datenblöcke verarbeiten müssen, die Sie tatsächlich benötigen.

Wir empfehlen dringend, die neueste Version der API zu verwenden, die gegenüber den Vorgängerversionen Verbesserungen aufweist, wie z. B. neue Datenblöcke mit erweiterten Informationen.

Beispiele für Antworten sowie ein herunterladbares JSON-Schema mit allen bereitgestellten Attributen finden Sie in der API-Dokumentation.

In der folgenden Tabelle finden Sie eine Übersicht über die verfügbaren Blöcke.

Block	Ab Version	Beschreibung
<leer>	V1	Ohne Block werden nur sehr grundlegende Produktinformationen ausgeliefert. Dies ist nützlich, damit Sie Produktlöschungen vornehmen können. Details finden Sie unter Datenlöschung.
DETAILS	V3	Gibt das Attribut details aus, das weitere Details wie Bestelldetails, Gruppierung, Marken, Serien usw. enthält. Wichtig: In V1 und V2 wurden diese Informationen bereitgestellt, wenn keine Blöcke angefordert wurden.
MEASUREMENTS	V3	Gibt das Attribut measurements aus, das die Nettoabmessungen des Produkts enthält.
CLASSIFICATIONS	V1	Gibt das Attribut classifications aus, das Klassifizierungsdaten enthält, wie beispielsweise die dem Produkt zugeordnete ETIM-Klasse.
FEATURES	V1	Gibt das Attribut features aus, das Produktmerkmale enthält. Die tatsächlichen ETIM-Merkmale werden hier aufgelistet.
PROPERTIES	V1	Gibt das Attribut properties aus, das verschiedene zusätzliche Attribute und Kennzeichnungen enthält. Dabei handelt es sich um Informationen wie das Ablaufdatum, die Klassifikation als Gefahrgut usw.
TEXTS	V1	Gibt das Attribut texts aus, das alle verfügbaren Produkttexte enthält, wie z. B. kurze und lange Beschreibungen, Marketingtexte usw.
IMAGES	V1	Gibt das Attribut images aus, das alle verfügbaren Produktbilder in verschiedenen Auflösungen enthält. Beachten Sie, dass diese URL unverändert bleibt, sofern der Hersteller das Bild nicht ersetzt.
ATTACHMENTS	V1	Gibt das Attribut attachments aus, das alle verfügbaren Anhänge enthält: Dokumente (Handbücher, Zertifikate, Datenblätter usw.) und Videos. Beachten Sie, dass die URLs unverändert bleiben, sofern der Hersteller den Anhang nicht ersetzt. Anhänge können auch auf externe Quellen verweisen.
PRICES	V2	Gibt das Attribut pricing aus, das die Produktpreise enthält. Beachten Sie, dass die Preisweiterleitung den in Preisanzeige im Portal definierten Regeln folgt und die Berechtigung „Preisexport” erforderlich ist, um Preise in dieser API zu erhalten.
RELATIONSHIPS	V3	Gibt das Attribut relationships aus, das die Beziehung des Produkts zu anderen Produkten enthält, wie z. B. Zubehör, Nachfolger, Vorgänger, Ersatzteile usw.
PACKAGES	V3	Gibt das Attribut packages aus, das Produktverpackungen enthält. Diese enthalten immer die Abmessungen, unabhängig davon, ob der Block MEASUREMENTS angefordert wurde.

Datenlöschung

OXOMI speichert nicht, welche Produkte gelöscht wurden. Dazu müsste man sich merken, ob und wann ein Produkt synchronisiert wurde. Außerdem bedeutet ein Aufruf der API nicht, dass der Aufrufer die empfangenen Daten auch tatsächlich genutzt hat, da es keine API gibt, die den Empfang der Daten bestätigt.

Um Produktlöschungen zu handhaben, empfehlen wir daher folgenden Ansatz:

Speichern Sie beim Synchronisieren von Produkten einige wichtige Informationen zum Produkt in Ihrem System. Wir empfehlen die Verwendung des mitgelieferten Attributs uniqueIdentifier.
Definieren Sie einen separaten API-Token, für den niemals ein Datum festgelegt wird.
Rufen Sie die API mit dem oben genannten API-Token und ohne Blöcke auf, um die Menge der empfangenen Daten und die Geschwindigkeit der Antwort zu verringern.
Sie erhalten eine Liste aller Produkte, die Ihnen heute zur Verfügung stehen, und können diese verwenden, um alle verbleibenden Produkte im Zielsystem zu löschen.

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 711 / 205 004 - 10 / 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/v3/products/spx abgerufen werden. Die Dokumentation dieser API findet sich hier.