Ordem de carga inicial
A carga inicial tem dependências rígidas: um produto referencia categoria e marca por
externalReference, e o preço referencia o SKU. Enviar fora de ordem gera itens
incompletos que só aparecem depois de um reenvio.
Esta página começa depois da ativação. Warehouse, commercialPolicyId e os
shippingPolicyId já precisam existir — veja
Ativar uma loja.
Sequência
O diagrama responde: em que ordem eu envio, e em que ponto posso enviar o próximo lote?
A dependência é do webhook, não do 200 OK: publicar estoque ou preço antes de
ProductWithSKUs_Created chegar tem boa chance de falhar por SKU inexistente.
Marcas
POST /v1/batch/Brands — precisa vir antes do produto que a referencia.
Categorias
POST /v1/batch/Categories — aceita árvore aninhada via children, então a estrutura
inteira pode ir em uma chamada.
Produtos e SKUs
POST /v1/batch/Products — o produto carrega seus SKUs. Referencia categoria e marca
pelos externalReference enviados nos passos anteriores.
Estoque
POST /v1/batch/Warehouses/sku — só funciona depois que o SKU existe.
O aceite do lote chega como WarehouseSKU_Created — o data é o lote inteiro, não um
item por notificação. Mas esse evento não garante que todos os itens entraram: o
core aceita o lote com 200 mesmo quando parte dos SKUs falha, e a lista de erros não
é repassada. Confirme os números com
GET /v1/batch/Warehouses/stock?warehouseExternalReference=. Veja
Conferir estoque.
Preço
POST /v1/batch/Pricing — precisa do SKU e da commercialPolicyId. Este é o passo que
torna o item vendável: sem preço vigente, ele não aparece como comprável mesmo com
estoque.
Tamanho de lote
Cada requisição aceita uma lista. O corpo tem limite de 100 MB na plataforma (pode ser alterado conforme a necessidade do cliente); na prática, lotes de 500 a 1.000 itens são o ponto de equilíbrio entre throughput e facilidade de reprocessar um lote que falhou.
Como o processamento é assíncrono, o 200 OK significa apenas “lote aceito”. Não
interprete como “produto criado” — quem confirma isso é o webhook do evento
correspondente.
Reprocessar sem duplicar
Todas as rotas em lote são idempotentes por externalReference. Reenviar o mesmo lote:
- atualiza o que já existe;
- cria o que ainda não existe;
- não duplica nada.
Isso torna seguro o padrão “reenvia o lote inteiro quando qualquer item falhar”, que é bem mais simples de operar do que rastrear item a item.
A idempotência vale para o par externalReference + tenant. Se o ERP mudar o código
de um item já publicado, a plataforma trata como item novo — o antigo continua na
vitrine até ser removido explicitamente.
Warehouse é a exceção. POST /v1/batch/Warehouses reconcilia pelo name, não
pelo externalReference. Veja Warehouses.