Marketplace Catalog Sync

• Het bouwen van een verkopersconnector die nieuwe SKU's naar een VTEX-marketplace moet pushen en de suggestiecyclus (verzenden → in behandeling → goedgekeurd/afgewezen) moet afhandelen.
• Het implementeren van de Change Notification-flow om te detecteren of een SKU al bestaat in de marketplace (200 OK) of een nieuwe suggestie vereist (404 Not Found).
• Het synchroniseren van prijs- en voorraadwijzigingen via de /notificator/{sellerId}/changenotification/{sellerSkuId}/price- en /inventory-eindpunten.
• Het implementeren van het Fulfillment Simulation-eindpunt aan de verkoperskant (POST /pvt/orderForms/simulation) dat binnen 2,5 seconden moet reageren.

• U voert catalogusbewerkingen aan de marketplace-kant uit, zoals directe POST /api/catalog/pvt/product- of POST /api/catalog/pvt/stockkeepingunit-schrijfacties — dit zijn geen seller-connector-flows.
• U hebt logica nodig voor orderafhandeling of factuurbeheer (zie in plaats daarvan de marketplace-fulfillment-skill).
• U hebt rate-limitingpatronen nodig in isolatie, losgekoppeld van catalogusmeldingsflows (zie in plaats daarvan de marketplace-rate-limiting-skill).

Verkopersconnectoren moeten POST .../changenotification/{sellerId}/{sellerSkuId} gebruiken — niet de enkelsegment-route changenotification/{skuId}, die een marketplace VTEX SKU ID verwacht. Deze vaardigheid documenteert het onderscheid, legt uit waarom officiële documentatie de twee routes soms door elkaar haalt, en biedt concrete TypeScript-voorbeelden voor zowel het 200- (update) als het 404- (nieuwe suggestie) responspad.

Nieuwe SKU's moeten de suggestie-/goedkeuringsworkflow doorlopen via PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId} — directe schrijfacties naar de Catalog API zijn verboden voor externe verkopers en retourneren een 403 Forbidden-fout. De vaardigheid voert een statuscontrole uit vóór elke suggestie-update, omdat suggesties alleen kunnen worden gewijzigd wanneer ze de status Pending hebben; goedgekeurde of afgewezen suggesties kunnen niet worden aangepast.

Prijs- en voorraadwijzigingen worden verzonden via afzonderlijke POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price- en .../inventory-eindpunten, waarbij het padsegment de SKU-ID van de verkoper is (niet de VTEX SKU-ID van de marketplace). Na deze meldingen roept de marketplace het Fulfillment Simulation-eindpunt van de verkoper aan om actuele gegevens op te halen.

De marketplace roept het POST /pvt/orderForms/simulation-eindpunt van de verkoper aan na elke prijs- of voorraadmelding. VTEX wacht maximaal 2,5 seconden op een reactie; het overschrijden van deze limiet markeert het product als niet beschikbaar in de winkelomgeving. Deze vaardigheid biedt een cache-first implementatiepatroon (in-memory of Redis) zodat het eindpunt reageert in minder dan 50 ms.

Het verzenden van bulk Change Notification-verzoeken zonder beperking veroorzaakt 429-reacties die de volledige API-toegang van de verkoper blokkeren. Deze vaardigheid biedt een verwerking in batches met gelijktijdigheidscontrole, vertragingen per batch, het verwerken van de retry-after-header en exponentiële terugval bij 429-fouten.

Catalog System-routes (bijv. changenotification) gebruiken de hostnaam van de winkel ({account}.vtexcommercestable.com.br), terwijl SKU Suggestion-routes gebruikmaken van https://api.vtex.com/{accountName}. Beide oppervlakken authenticeren met dezelfde X-VTEX-API-AppKey- en X-VTEX-API-AppToken-headers. De skill biedt een getypeerde SellerConnectorConfig en een Axios-clientfabriek die beide basis-URL's ondersteunt.

Een verkoper maakt voor het eerst verbinding met een VTEX-marketplace en moet de volledige SKU-catalogus registreren. De integratie roept changenotification/{sellerId}/{sellerSkuId} aan voor elke SKU; elke 404 activeert een PUT SKU-suggestie, waardoor elke SKU in de wachtrij voor beoordeling door de marketplace-operator wordt geplaatst.

Het magazijnsysteem van een verkoper genereert gebeurtenissen bij prijs- of voorraadwijzigingen. De connector verstuurt gebundelde prijs- en voorraadmeldingen via de /notificator/-eindpunten, en het Fulfillment Simulatie-eindpunt van de verkoper — ondersteund door een vooraf gevulde cache — reageert op polling-verzoeken van de marketplace binnen de deadline van 2,5 seconden.

Een operator moet productgegevens bijwerken in een suggestie die is verzonden maar nog niet is beoordeeld. De integratie roept eerst GET /suggestions/{sellerId}/{sellerSkuId} aan om te bevestigen dat de suggestie nog de status Pending heeft, waarna een PUT wordt uitgevoerd met de gecorrigeerde gegevens. Suggesties die al zijn goedgekeurd of afgewezen, worden overgeslagen met een waarschuwing.

Na een productdatamigatie moeten honderden SKU's opnieuw worden gemeld. De integratie maakt gebruik van het gebatchte meldingspatroon — SKU's worden verwerkt in groepen van vijf met vertragingen van 200 ms tussen batches en 429-bewuste herprobeermechanismen — om de marktplaats opnieuw te notificeren zonder snelheidsbegrenzing te activeren.