API ViaShopModa documentação

Catálogo — carga inicial e manutenção de produtos

Como enviar os produtos do ERP para a loja — o que é criado automaticamente, a ordem das chamadas e o que acontece ao reenviar um produto.

Ver como Markdown Atualizado em 18/11/2026

Resumo em 30 segundos #

  1. Para cada produto, faça um POST produto/cadastrar com o produto e todas as variações (tamanho × cor) em estoque, já com quantidade.
  2. 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.
  3. Envie as fotos com imagens/upload (uma requisição por foto, identificando a variação pelo cod_barras).
  4. 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 estoque enviado 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 #

ParaUse
Mover vários produtos de coleçãoproduto/alterar_colecao
Mostrar as outras cores de um modelo cadastrado em vários produtosproduto/associar_supervitrine
Sugerir produtos relacionadosproduto/associar_comprejunto
Guardar o código do ERP em produto, tipo, grade ou estampacod_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_barras repetido 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.