Resumo em 30 segundos #
- Para cada produto, faça um
POST produto/cadastrarcom o produto e todas as variações (tamanho × cor) emestoque, já com quantidade. - Tipo, gênero, coleção, grades e estampas são criados automaticamente pelo nome se ainda não existirem. Não é preciso cadastrá-los antes.
- Envie as fotos com
imagens/upload(uma requisição por foto, identificando a variação pelocod_barras). - Depois da carga, mantenha estoque e preço com as rotas de lote (guia Estoque e preço).
Como o catálogo é organizado #
produto (cod_ref "VES001", título, descrição, preços, tipo, gênero, coleção)
├── variação: grade "P" × estampa "AZUL" → cod_barras, quantidade, preço diferenciado (opcional)
├── variação: grade "M" × estampa "AZUL" → ...
└── variação: grade "P" × estampa "FLORAL" → ...Veja os nomes no Glossário. Atenção: o tipo do produto é a rota peso, e o gênero é a rota categoria.
Passo a passo da carga inicial #
1. (Opcional) Conferir os cadastros auxiliares #
Se o ERP precisa usar os ids da loja, consulte o que já existe:
- tipos:
GET peso/consultar - gêneros:
GET categoria/consultar - coleções:
GET colecao/consultar - grades:
GET grade/consultar - estampas:
GET estampa/consultar
Não é obrigatório: produto/cadastrar aceita nomes e cria o que faltar.
2. Cadastrar cada produto com as variações #
{
"cod_ref": "VES001",
"titulo": "VESTIDO XADREZ FLANELA",
"descricao": "Vestido em flanela leve.<br><b>Modelagem:</b> reta",
"tipo": "Vestido",
"genero": "Feminino",
"colecao": "Inverno 2026",
"preco_atacado": 49.99,
"preco_varejo": 99.99,
"peso": 350,
"estoque": [
{ "grade": { "nome": "P" }, "estampa": { "nome": "AZUL CLARO" }, "cod_barras": "7890000000101", "quantidade": 5 },
{ "grade": { "nome": "M" }, "estampa": { "nome": "AZUL CLARO" }, "cod_barras": "7890000000102", "quantidade": 8 },
{ "grade": { "nome": "G" }, "estampa": { "nome": "AZUL CLARO" }, "cod_barras": "7890000000103", "quantidade": 3 }
]
}Detalhes e todas as regras: produto/cadastrar.
3. Enviar as fotos #
Uma requisição por foto. A foto fica ligada ao produto e à estampa da variação do cod_barras informado.
{
"produto": {
"cod_barras": "7890000000101",
"arquivo": "https://seu-servidor.com.br/fotos/VES001-azul-1.jpg"
}
}O upload é assíncrono: a resposta confirma que entrou na fila. Detalhes: imagens/upload.
4. Conferir se o produto está à venda #
GET produto/ocorrencias?id={id} lista o que impede o produto de aparecer na loja: preço zerado, sem foto, sem estoque, coleção inativa etc.
Reenviar um produto (atualização) #
produto/cadastrar é também a rota de atualização: o produto é localizado pelo cod_ref.
Importante: ao reenviar, as variações do produto são substituídas pelas enviadas. Uma variação que não estiver no
estoqueenviado deixa de existir. Sempre envie o produto completo, com todas as variações e as quantidades atuais.
Ao reenviar, a loja mantém as fotos, os produtos relacionados e a SuperVitrine, e reativa o produto se ele estava desativado.
Para mudar só o estoque ou só o preço, não reenvie o produto: use estoque/atualizar, preco/atualizar ou produto/alterar_precos.
Para mudar só título, descrição, SEO ou vídeos, use produto/atualizar_textos: ele não mexe em preço nem em estoque.
Desativar um produto #
POST produto/desativar com {"id": 123} tira o produto da loja e apaga as variações. Para voltar a vender, envie o produto completo de novo com produto/cadastrar.
Organizar a vitrine #
| Para | Use |
|---|---|
| Mover vários produtos de coleção | produto/alterar_colecao |
| Mostrar as outras cores de um modelo cadastrado em vários produtos | produto/associar_supervitrine |
| Sugerir produtos relacionados | produto/associar_comprejunto |
| Guardar o código do ERP em produto, tipo, grade ou estampa | cod_externo/associar |
Erros comuns de integração #
- Cadastrar tipo, gênero, grade e estampa um por um antes do produto, gastando requisições. → Não é preciso: o cadastro do produto cria pelo nome.
- Reenviar o produto com só a variação que mudou. → As outras variações são apagadas.
- Repetir a mesma combinação grade × estampa no
estoque. → O cadastro é recusado. - Usar
cod_barrasrepetido entre variações ou produtos. → Estoque, preço e foto não conseguem achar a variação certa. - Mandar o produto inteiro para mudar o estoque. → Use
estoque/atualizar, que é mais leve e não recria as variações.