Marketplace Catalog Sync

• Construindo um conector de seller que precisa enviar novos SKUs para um marketplace VTEX e gerenciar o ciclo de vida de sugestões (enviar → pendente → aprovado/negado).
• Implementando o fluxo de Change Notification para detectar se um SKU já existe no marketplace (200 OK) ou se precisa de uma nova sugestão (404 Not Found).
• Sincronizando alterações de preço e estoque por meio dos endpoints /notificator/{sellerId}/changenotification/{sellerSkuId}/price e /inventory.
• Implementando o endpoint de Fulfillment Simulation do lado do seller (POST /pvt/orderForms/simulation), que deve responder em até 2,5 segundos.

• Você está realizando operações de catálogo no lado do marketplace, como gravações diretas de POST /api/catalog/pvt/product ou POST /api/catalog/pvt/stockkeepingunit — esses não são fluxos de seller-connector.
• Você precisa de lógica de fulfillment de pedidos ou de manipulação de faturas (consulte a skill marketplace-fulfillment em vez disso).
• Você precisa de padrões de rate-limiting de forma isolada, desacoplados dos fluxos de notificação de catálogo (consulte a skill marketplace-rate-limiting em vez disso).

Conectores de seller devem usar POST .../changenotification/{sellerId}/{sellerSkuId} — e não a rota de segmento único changenotification/{skuId}, que espera um ID de SKU VTEX do marketplace. Esta skill documenta a distinção, explica por que a documentação oficial às vezes confunde as duas rotas e fornece exemplos concretos em TypeScript para os dois caminhos de resposta: 200 (atualização) e 404 (nova sugestão).

Novos SKUs devem passar pelo fluxo de sugestão/aprovação via PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId} — gravações diretas na API de Catálogo são proibidas para sellers externos e retornarão 403 Forbidden. A skill aplica uma verificação de status antes de qualquer atualização de sugestão, pois as sugestões só podem ser modificadas enquanto estiverem no estado Pending; sugestões aprovadas ou negadas não podem ser alteradas.

As atualizações de preço e estoque são enviadas por meio de endpoints separados: POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price e .../inventory, onde o segmento de caminho é o ID de SKU do seller (não o ID de SKU VTEX do marketplace). Após essas notificações, o marketplace chama o endpoint de Simulação de Fulfillment do seller para recuperar os dados atuais.

O marketplace chama o endpoint POST /pvt/orderForms/simulation do seller após cada notificação de preço ou estoque. A VTEX aguarda no máximo 2,5 segundos por uma resposta; exceder esse limite marca o produto como indisponível na vitrine. Esta skill fornece um padrão de implementação com cache em primeiro lugar (em memória ou Redis) para que o endpoint responda em menos de 50 ms.

O envio de requisições em massa de Notificações de Alteração sem controle de throttling aciona respostas 429 que bloqueiam todo o acesso à API do vendedor. Esta skill fornece um loop de notificação em lotes com controle de concorrência, atrasos por lote, análise do cabeçalho retry-after e backoff exponencial em erros 429.

As rotas do Sistema de Catálogo (ex.: changenotification) utilizam o hostname da loja ({account}.vtexcommercestable.com.br), enquanto as rotas de Sugestão de SKU utilizam https://api.vtex.com/{accountName}. Ambas as superfícies se autenticam com os mesmos headers X-VTEX-API-AppKey e X-VTEX-API-AppToken. A skill fornece um SellerConnectorConfig tipado e uma factory de cliente Axios que cobre ambas as URLs base.

Um seller está se conectando a um marketplace VTEX pela primeira vez e precisa cadastrar todo o seu catálogo de SKUs. A integração chama changenotification/{sellerId}/{sellerSkuId} para cada SKU; cada resposta 404 aciona um PUT de Sugestão de SKU, colocando cada SKU na fila de revisão pendente do marketplace para aprovação do operador.

O sistema de armazém de um seller emite eventos de alteração de preço ou estoque. O conector envia notificações em lote de preço e estoque por meio dos endpoints /notificator/, e o endpoint de Simulação de Fulfillment do seller — apoiado por um cache pré-aquecido — responde às requisições de polling do marketplace dentro do prazo de 2,5 segundos.

Um operador precisa atualizar os dados do produto em uma sugestão que foi enviada, mas ainda não foi revisada. A integração primeiro chama GET /suggestions/{sellerId}/{sellerSkuId} para confirmar que a sugestão ainda está no estado Pending, em seguida, emite um PUT com os dados corrigidos. Sugestões já aprovadas ou recusadas são ignoradas com um aviso.

Após uma migração de dados de produtos, centenas de SKUs precisam de nova notificação. A integração utiliza o padrão de notificação em lotes — processando SKUs em grupos de cinco com intervalos de 200 ms entre os lotes e lógica de retry com reconhecimento de erro 429 — para notificar novamente o marketplace sem acionar bloqueios por limite de taxa.