O que faz #
Recebe um produto com todas as suas variações e:
- se não existe produto com o
cod_ref→ cria; - se existe → atualiza o produto e substitui todas as variações pelas enviadas.
Tipo, gênero, coleção, grades e estampas são localizados pelo nome e criados se não existirem.
Quando usar: carga inicial do catálogo e quando dados do cadastro do produto mudam (título, descrição, variações novas).
Quando não usar: para mudar só estoque (estoque/atualizar) ou só preço (produto/alterar_precos, preco/atualizar).
Requisição #
| Método | POST |
| URL | https://api.viashopmoda.com.br/via/produto/cadastrar/{TOKEN} |
| Corpo | Objeto JSON { ... }, cabeçalho Content-Type: application/json (JSON cru; form-data é recusado) |
| Token | Substitua {TOKEN} pelo token da loja. Ele vai no caminho da URL, não em cabeçalho. |
Campos #
| Campo | Tipo | Obrigatório | Limites | Descrição |
|---|---|---|---|---|
cod_ref | string | sim | Código de referência do produto | |
titulo | string | sim | máx. 255, gravado em MAIÚSCULAS | Título do produto |
descricao | string | não | Descrição completa do produto. | |
preco_atacado | double | sim | Exemplo: 9.99 | |
preco_varejo | double | sim | Exemplo: 9.99 | |
peso | numeric | não | Peso do produto em gramas | |
altura | numeric | não | em cm | |
largura | numeric | não | em cm | |
comprimento | numeric | não | em cm | |
ncm | string | não | Código NCM do produto | |
preco_atacado_promo | double | não | Exemplo: 9.99 | |
preco_varejo_promo | double | não | Exemplo: 9.99 | |
tipo | integer | sim | O nome do tipo de produto, se não existir será cadastrado. Consultar método | |
genero | integer | sim | O nome do gênero, se não existir será cadastrado. Consultar método | |
colecao | integer | sim | O nome da coleção, se não existir será cadastrado. Consultar método | |
video_produto | string | não | Video de apresentação do produto. Sendo a url do video no youtube ou vimeo no padrão: 'https://vimeo.com/{VIDEO}' ou 'https://youtu.be/{VIDEO}'. | |
video_atacado | string | não | Video ensinando os clientes de atacado a vender esse produto. Sendo a url do video no youtube ou vimeono padrão: 'https://vimeo.com/{VIDEO}' ou 'https://youtu.be/{VIDEO}'. | |
seo_title | string | não | máx. 150 | Título para SEO |
seo_description | string | não | máx. 150 | Descrição para SEO |
estoque | array | sim | ||
estoque[].estampa | object | sim | ||
estoque[].estampa.nome | string | sim | mín. 3, máx. 50 | Nome da estampa |
estoque[].grade | object | sim | ||
estoque[].grade.nome | string | sim | Nome da grade. Ex.: 'XG' | |
estoque[].grade.descricao | string | não | aceita null | Informação adicional para a grade. Ex.: 'Extra G' |
estoque[].cod_barras | string | não | Código de barras cadastrado na loja virtual de acordo com o padrão do seu sistema | |
estoque[].cod_gtin | string | não | ||
estoque[].cod_externo | string | não | ||
estoque[].quantidade | integer | sim | Quantidade de estoque q ser atualizada | |
estoque[].preco_atacado | double | não | aceita null | Preço especial do SKU no atacado, diferenciando do preço produto. Se não enviado, não será atualizado. Se enviado como NULL, o preço de atacado desse SKU passará a ser o valor do produto. |
estoque[].preco_varejo | double | não | aceita null | Preço especial do SKU no varejo, diferenciando do preço produto. Se não enviado, não será atualizado. Se enviado como NULL, o preço de atacado desse SKU passará a ser o valor do produto. |
Regras (valem acima da tabela) #
Identificação: o produto é localizado pelo cod_ref. Se houver mais de um com a mesma referência, a loja usa o ativo.
Variações (estoque)
- Cada item é uma combinação grade × estampa. A mesma combinação repetida faz o cadastro ser recusado.
- Ao atualizar, as variações antigas são apagadas e as enviadas são criadas de novo. Variação não enviada deixa de existir.
- Envie
cod_barrasem todas as variações (a tabela diz "não", mas sem ele não é possível atualizar estoque, preço ou fotos depois). quantidadeé o saldo disponível. A margem de segurança configurada na loja é aplicada automaticamente.
tipo, genero, colecao — envie o nome (texto), não o id, apesar da tabela mostrar "integer". Se não existir, é criado. Valor especial "*DEFAULT": num produto novo usa o padrão da loja (para coleção: "Integração ERP"); num produto existente mantém o que já está gravado.
Preços
preco_atacadoé obrigatório. Se não vier, a loja usa o menorpreco_atacadodas variações; se nenhuma tiver, o cadastro é recusado.preco_varejonão enviado → menorpreco_varejodas variações → se não houver, igual ao atacado.- Preço da variação igual ao do produto é gravado como "herda do produto".
- Promoção:
preco_*_promoé o preço promocional e precisa ser menor que o preço normal; senão é ignorado. Veja Estoque e preço. - A loja pode ter um fator de preço configurado para a sua integração; ele é aplicado só nesta rota.
Textos
tituloé gravado em MAIÚSCULAS, até 255 caracteres.descricaoaceita só as tags<br>,<p>,<b>e<strong>, sem atributos. As demais são removidas.video_produto/video_atacado: só linkshttps://vimeo.com/...ouhttps://youtu.be/....
Medidas: peso em gramas; altura, largura, comprimento em cm (arredondados para cima). ncm só com dígitos.
Ao atualizar, a loja mantém fotos, produtos relacionados (Compre Junto) e SuperVitrine, e reativa o produto se ele estava desativado.
Exemplo #
{
"cod_ref": "VES001",
"titulo": "Vestido xadrez flanela",
"descricao": "Vestido em flanela leve.<br><b>Modelagem:</b> reta<br><b>Composição:</b> 100% viscose",
"tipo": "Vestido",
"genero": "Feminino",
"colecao": "Inverno 2026",
"preco_atacado": 59.90,
"preco_varejo": 119.90,
"preco_varejo_promo": 99.90,
"peso": 350,
"ncm": "62044200",
"seo_title": "Vestido xadrez flanela",
"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": "GG", "descricao": "Extra grande" }, "estampa": { "nome": "AZUL CLARO" }, "cod_barras": "7890000000103", "quantidade": 2, "preco_atacado": 64.90, "preco_varejo": 129.90 }
]
}A variação GG tem preço diferente; as outras herdam o preço do produto.
curl -X POST "https://api.viashopmoda.com.br/via/produto/cadastrar/SEU_TOKEN" \
-H "Content-Type: application/json" \
-d @produto.jsonRespostas #
Sucesso:
{
"retorno": true,
"msg": "Produto Ref. VES001 cadastrado com sucesso.",
"cadastro": true,
"cod_produto": 325,
"cod_tipo": 51,
"cod_colecao": 21,
"cod_genero": 1,
"estoque": {
"estampas": [ { "id": 709, "nome": "AZUL CLARO" } ],
"grades": [ { "id": 14, "nome": "P" }, { "id": 15, "nome": "M" }, { "id": 17, "nome": "GG" } ]
}
}Na atualização, msg diz "atualizado com sucesso" e cadastro vem false. Guarde cod_produto e os ids de grade e estampa se o ERP for usar cod_produto + cod_grade + cod_estampa.
Erros (msg_erro):
| Mensagem | Causa |
|---|---|
Item 'tipo' não enviado ou vazio. | Falta tipo. |
Item 'genero' não enviado ou vazio. | Falta genero. |
Item 'colecao' não enviado ou vazio. | Falta colecao. |
Produto VES001 não importado. A estampa ou grade ... esta duplicada nos itens de estoque. | Mesma grade × estampa repetida. |
preco_atacado não enviado | Sem preço de atacado no produto e nas variações. |
'video_produto' no formato errado. ... | Link de vídeo fora do padrão. |
grade: ... no index:N para ref. VES001 | Grade do item N inválida (ex.: nome vazio). |
estampa: ... index N | Estampa do item N inválida (nome com menos de 3 ou mais de 50 caracteres). |
Pode reenviar? #
Sim. Reenviar o mesmo produto completo produz o mesmo resultado. Atenção apenas para enviar todas as variações.
Onde entra no processo #
Guia Catálogo — carga inicial.
Erros comuns de integração #
- Enviar
tipo,generooucolecaocomo id numérico. - Reenviar com só a variação alterada (as demais somem).
- Mandar o corpo como form-data: esta rota exige JSON cru.
- Usar esta rota para atualizar estoque a cada venda.