Marketplace Catalog Sync

• Bygga en säljaranslutning som behöver skicka nya SKU:er till en VTEX-marknadsplats och hantera livscykeln för förslag (skicka → väntande → godkänd/nekad).
• Implementera flödet för ändringsaviseringar (Change Notification) för att identifiera om en SKU redan finns på marknadsplatsen (200 OK) eller om ett nytt förslag behövs (404 Not Found).
• Synkronisera pris- och lagerändringar via slutpunkterna /notificator/{sellerId}/changenotification/{sellerSkuId}/price och /inventory.
• Implementera säljarens Fulfillment Simulation-slutpunkt (POST /pvt/orderForms/simulation) som måste svara inom 2,5 sekunder.

• Du utför katalogoperationer på marketplace-sidan, till exempel direkta POST /api/catalog/pvt/product- eller POST /api/catalog/pvt/stockkeepingunit-anrop — dessa är inte seller-connector-flöden.
• Du behöver logik för orderhantering eller fakturahantering (se färdigheten marketplace-fulfillment istället).
• Du behöver rate limiting-mönster isolerat, frikopplat från katalognotifieringsflöden (se färdigheten marketplace-rate-limiting istället).

Säljaranslutningar måste använda POST .../changenotification/{sellerId}/{sellerSkuId} — inte den ensegmenterade rutten changenotification/{skuId}, som förväntar sig ett VTEX SKU-ID för marknadsplatsen. Denna skill dokumenterar skillnaden, förklarar varför officiell dokumentation ibland blandar ihop de två rutterna, och tillhandahåller konkreta TypeScript-exempel för både 200- (uppdatering) och 404-svarsflödena (nytt förslag).

Nya SKU:er måste genomgå arbetsflödet för förslag/godkännande via PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId} — direkta skrivningar till Catalog API är förbjudna för externa säljare och returnerar 403 Forbidden. Färdigheten tillämpar en statuskontroll före varje förslagsuppdatering, eftersom förslag endast kan ändras när de befinner sig i tillståndet Pending; godkända eller nekade förslag kan inte ändras.

Pris- och lageruppdateringar skickas via separata POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price- och .../inventory-endpunkter, där sökvägssegmentet är säljarens SKU-ID (inte marketplace VTEX SKU-ID). Efter dessa notifieringar anropar marketplace säljarens Fulfillment Simulation-endpunkt för att hämta aktuella data.

Marknadsplatsen anropar säljarens POST /pvt/orderForms/simulation-endpoint efter varje pris- eller lagernotifiering. VTEX väntar maximalt 2,5 sekunder på ett svar; överskrids denna gräns markeras produkten som otillgänglig i butiksfronten. Den här färdigheten tillhandahåller ett cache-först implementeringsmönster (i minnet eller Redis) så att endpointen svarar på under 50 ms.

Att skicka massvis med Change Notification-förfrågningar utan begränsning utlöser 429-svar som blockerar säljarens hela API-åtkomst. Den här färdigheten tillhandahåller en batchad aviseringsloop med kontrollerad samtidighet, fördröjningar per batch, parsning av retry-after-headern samt exponentiell backoff vid 429-fel.

Catalog System-rutter (t.ex. changenotification) använder butikens värdnamn ({account}.vtexcommercestable.com.br), medan SKU Suggestion-rutter använder https://api.vtex.com/{accountName}. Båda ytorna autentiseras med samma X-VTEX-API-AppKey- och X-VTEX-API-AppToken-huvuden. Skickligheten tillhandahåller en typad SellerConnectorConfig och en Axios-klientfabrik som täcker båda bas-URL:erna.

En säljare ansluter till en VTEX-marknadsplats för första gången och behöver registrera hela sitt SKU-katalog. Integrationen anropar changenotification/{sellerId}/{sellerSkuId} för varje SKU; varje 404-svar utlöser ett PUT SKU-förslag, vilket placerar varje SKU i marknadsplatsens kö för väntande granskning för operatörsgodkännande.

En säljares lagersystem genererar händelser för pris- eller lagerändringar. Kopplingen skickar grupperade pris- och lagernotifieringar via /notificator/-slutpunkterna, och säljarens slutpunkt för uppfyllelesesimulering — som backas upp av ett föruppvärmt cache — svarar på marknadsplatsens förfrågningar inom tidsgränsen på 2,5 sekunder.

En operatör behöver uppdatera produktdata för ett förslag som har skickats men ännu inte granskats. Integrationen anropar först GET /suggestions/{sellerId}/{sellerSkuId} för att bekräfta att förslaget fortfarande har statusen Pending, och skickar sedan ett PUT-anrop med den korrigerade datan. Förslag som redan har godkänts eller nekats hoppas över med en varning.

Efter en produktdatamigrering behöver hundratals SKU:er omnotifieras. Integrationen använder det batchade notifieringsmönstret — bearbetar SKU:er i grupper om fem med 200 ms fördröjning mellan batcharna och 429-medveten återförsökslogik — för att omnotifiera marknadsplatsen utan att utlösa hastighetsbegränsningsblock.