Marketplace Catalog Sync

• Einen Seller-Connector aufbauen, der neue SKUs in einen VTEX-Marktplatz übertragen und den Vorschlags-Lebenszyklus (senden → ausstehend → genehmigt/abgelehnt) verwalten muss.
• Den Change-Notification-Ablauf implementieren, um zu erkennen, ob eine SKU bereits im Marktplatz vorhanden ist (200 OK) oder ein neuer Vorschlag erforderlich ist (404 Not Found).
• Preis- und Bestandsänderungen über die Endpunkte /notificator/{sellerId}/changenotification/{sellerSkuId}/price und /inventory synchronisieren.
• Den sellerseitigen Fulfillment-Simulation-Endpunkt (POST /pvt/orderForms/simulation) implementieren, der innerhalb von 2,5 Sekunden antworten muss.

• Sie führen marketplace-seitige Katalogoperationen durch, wie direkte POST /api/catalog/pvt/product- oder POST /api/catalog/pvt/stockkeepingunit-Schreibvorgänge – das sind keine Seller-Connector-Flows.
• Sie benötigen Logik zur Auftragsabwicklung oder Rechnungsverarbeitung (siehe stattdessen den marketplace-fulfillment-Skill).
• Sie benötigen Rate-Limiting-Muster isoliert, entkoppelt von Katalog-Benachrichtigungs-Flows (siehe stattdessen den marketplace-rate-limiting-Skill).

Seller-Connectoren müssen POST .../changenotification/{sellerId}/{sellerSkuId} verwenden – nicht die einsegmentige Route changenotification/{skuId}, die eine VTEX-SKU-ID des Marktplatzes erwartet. Diese Skill dokumentiert den Unterschied, erklärt, warum offizielle Dokumentationen die beiden Routen manchmal vermischen, und liefert konkrete TypeScript-Beispiele sowohl für den 200- (Aktualisierung) als auch den 404- (neuer Vorschlag) Antwortpfad.

Neue SKUs müssen den Vorschlags-/Genehmigungsworkflow über PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId} durchlaufen — direkte Catalog-API-Schreibvorgänge sind für externe Verkäufer nicht zulässig und geben den Fehler 403 Forbidden zurück. Der Skill erzwingt eine Statusprüfung vor jeder Vorschlagsaktualisierung, da Vorschläge nur im Status Pending geändert werden können; genehmigte oder abgelehnte Vorschläge können nicht mehr bearbeitet werden.

Preis- und Inventaraktualisierungen werden über separate POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price- und .../inventory-Endpunkte gesendet, wobei das Pfadsegment die SKU-ID des Verkäufers ist (nicht die VTEX-SKU-ID des Marktplatzes). Nach diesen Benachrichtigungen ruft der Marktplatz den Fulfillment-Simulation-Endpunkt des Verkäufers auf, um aktuelle Daten abzurufen.

Der Marktplatz ruft den POST /pvt/orderForms/simulation-Endpunkt des Verkäufers nach jeder Preis- oder Lagerbestandsbenachrichtigung auf. VTEX wartet maximal 2,5 Sekunden auf eine Antwort; wird dieses Limit überschritten, wird das Produkt im Storefront als nicht verfügbar markiert. Diese Skill bietet ein Cache-First-Implementierungsmuster (In-Memory oder Redis), sodass der Endpunkt in unter 50 ms antwortet.

Das Senden von Massen-Änderungsbenachrichtigungsanfragen ohne Drosselung löst 429-Antworten aus, die den gesamten API-Zugang des Verkäufers blockieren. Diese Fähigkeit bietet eine stapelverarbeitete, parallelitätskontrollierte Benachrichtigungsschleife mit Verzögerungen pro Stapel, Analyse des retry-after-Headers und exponentiellem Backoff bei 429-Fehlern.

Catalog System-Routen (z. B. changenotification) verwenden den Store-Hostnamen ({account}.vtexcommercestable.com.br), während SKU-Vorschlagsrouten https://api.vtex.com/{accountName} verwenden. Beide Oberflächen authentifizieren sich mit denselben X-VTEX-API-AppKey- und X-VTEX-API-AppToken-Headern. Der Skill stellt eine typisierte SellerConnectorConfig und eine Axios-Client-Factory bereit, die beide Basis-URLs abdeckt.

Ein Verkäufer verbindet sich zum ersten Mal mit einem VTEX-Marktplatz und muss seinen gesamten SKU-Katalog registrieren. Die Integration ruft changenotification/{sellerId}/{sellerSkuId} für jede SKU auf; jeder 404-Fehler löst einen PUT SKU-Vorschlag aus, wodurch jede SKU zur Genehmigung durch den Operator in die ausstehende Überprüfungswarteschlange des Marktplatzes eingereiht wird.

Das Lagersystem eines Verkäufers gibt Preis- oder Bestandsänderungsereignisse aus. Der Connector sendet gebündelte Preis- und Bestandsbenachrichtigungen über die /notificator/-Endpunkte, und der Fulfillment-Simulationsendpunkt des Verkäufers – gestützt durch einen vorgewärmten Cache – beantwortet Abfragen des Marktplatzes innerhalb der 2,5-Sekunden-Frist.

Ein Betreiber muss Produktdaten in einem Vorschlag aktualisieren, der gesendet, aber noch nicht überprüft wurde. Die Integration ruft zunächst GET /suggestions/{sellerId}/{sellerSkuId} auf, um zu bestätigen, dass der Vorschlag noch den Status Pending hat, und sendet dann ein PUT mit den korrigierten Daten. Vorschläge, die bereits genehmigt oder abgelehnt wurden, werden mit einer Warnung übersprungen.

Nach einer Produktdatenmigration müssen Hunderte von SKUs erneut benachrichtigt werden. Die Integration verwendet das Stapel-Benachrichtigungsmuster — SKUs werden in Gruppen von fünf verarbeitet, mit 200-ms-Verzögerungen zwischen den Stapeln und einer 429-bewussten Wiederholungslogik — um den Marketplace Catalog Sync erneut zu benachrichtigen, ohne Ratenlimit-Sperren auszulösen.