Marketplace Catalog Sync

• Costruire un connettore venditore che deve inviare nuovi SKU in un marketplace VTEX e gestire il ciclo di vita dei suggerimenti (invio → in attesa → approvato/rifiutato).
• Implementare il flusso di Change Notification per rilevare se uno SKU esiste già nel marketplace (200 OK) o richiede un nuovo suggerimento (404 Not Found).
• Sincronizzare le modifiche a prezzi e inventario tramite gli endpoint /notificator/{sellerId}/changenotification/{sellerSkuId}/price e /inventory.
• Implementare l'endpoint di Fulfillment Simulation lato venditore (POST /pvt/orderForms/simulation) che deve rispondere entro 2,5 secondi.

• Stai eseguendo operazioni di catalogo lato marketplace come scritture dirette tramite POST /api/catalog/pvt/product o POST /api/catalog/pvt/stockkeepingunit — queste non sono flussi seller-connector.
• Hai bisogno di logica per la gestione degli ordini o la gestione delle fatture (consulta invece la skill marketplace-fulfillment).
• Hai bisogno di pattern di rate-limiting in isolamento, disaccoppiati dai flussi di notifica del catalogo (consulta invece la skill marketplace-rate-limiting).

I connettori per i venditori devono utilizzare POST .../changenotification/{sellerId}/{sellerSkuId} — e non la route a segmento singolo changenotification/{skuId}, che si aspetta un ID SKU VTEX del marketplace. Questa skill documenta la distinzione, spiega perché la documentazione ufficiale a volte confonde le due route e fornisce esempi concreti in TypeScript per entrambi i percorsi di risposta: 200 (aggiornamento) e 404 (nuova proposta).

I nuovi SKU devono seguire il flusso di lavoro di suggerimento/approvazione tramite PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId} — le scritture dirette tramite Catalog API sono vietate per i venditori esterni e restituiranno un errore 403 Forbidden. La funzionalità applica un controllo dello stato prima di qualsiasi aggiornamento del suggerimento, poiché i suggerimenti possono essere modificati solo quando si trovano nello stato Pending; i suggerimenti approvati o rifiutati non possono essere modificati.

Gli aggiornamenti di prezzi e inventario vengono inviati tramite endpoint separati POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price e .../inventory, dove il segmento di percorso corrisponde all'ID SKU del venditore (non all'ID SKU VTEX del marketplace). Dopo queste notifiche, il marketplace chiama l'endpoint di Simulazione di Evasione del venditore per recuperare i dati aggiornati.

Il marketplace chiama l'endpoint POST /pvt/orderForms/simulation del venditore dopo ogni notifica di prezzo o inventario. VTEX attende un massimo di 2,5 secondi per una risposta; il superamento di questo limite contrassegna il prodotto come non disponibile nella vetrina. Questa skill fornisce un pattern di implementazione cache-first (in memoria o Redis) in modo che l'endpoint risponda in meno di 50 ms.

L'invio di richieste di notifica di modifica in blocco senza limitazione della velocità genera risposte 429 che bloccano l'intero accesso API del venditore. Questa competenza fornisce un ciclo di notifica in batch con controllo della concorrenza, ritardi per singolo batch, analisi dell'intestazione retry-after e backoff esponenziale sugli errori 429.

Le route del sistema Catalog (ad es., changenotification) utilizzano l'hostname dello store ({account}.vtexcommercestable.com.br), mentre le route SKU Suggestion utilizzano https://api.vtex.com/{accountName}. Entrambe le superfici si autenticano con le stesse intestazioni X-VTEX-API-AppKey e X-VTEX-API-AppToken. La skill fornisce una SellerConnectorConfig tipizzata e una factory del client Axios che copre entrambi i base URL.

Un venditore si connette per la prima volta a un marketplace VTEX e deve registrare l'intero catalogo SKU. L'integrazione chiama changenotification/{sellerId}/{sellerSkuId} per ogni SKU; ogni risposta 404 attiva una richiesta PUT SKU Suggestion, inserendo ogni SKU nella coda di revisione in sospeso del marketplace per l'approvazione da parte dell'operatore.

Il sistema di magazzino di un venditore genera eventi di modifica dei prezzi o delle scorte. Il connettore invia notifiche raggruppate di prezzi e inventario tramite gli endpoint /notificator/, e l'endpoint di Simulazione di Evasione del venditore — supportato da una cache pre-riscaldata — risponde alle richieste di polling del marketplace entro il limite di 2,5 secondi.

Un operatore deve aggiornare i dati di prodotto su un suggerimento che è stato inviato ma non ancora revisionato. L'integrazione chiama prima GET /suggestions/{sellerId}/{sellerSkuId} per confermare che il suggerimento sia ancora nello stato Pending, quindi invia una PUT con i dati corretti. I suggerimenti già approvati o rifiutati vengono ignorati con un avviso.

Dopo una migrazione dei dati di prodotto, centinaia di SKU necessitano di una nuova notifica. L'integrazione utilizza il pattern di notifica in batch — elaborando gli SKU in gruppi di cinque con ritardi di 200 ms tra un batch e l'altro e una logica di retry consapevole degli errori 429 — per notificare nuovamente il marketplace senza innescare blocchi dovuti al superamento dei limiti di frequenza.