# Cadastrar ou atualizar produto

> Cria o produto com todas as variações (tamanho × cor) e estoque, ou atualiza o produto que já tem o mesmo cod_ref.

Fonte: https://api.viashopmoda.com.br/docs-api/?p=recursos/produto/cadastrar · Atualizado em 18/11/2026


## 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](https://api.viashopmoda.com.br/docs-api/?p=recursos/peso/consultar&formato=md) |
| `genero` | integer | **sim** |  | O nome do gênero, se não existir será cadastrado. [Consultar método](https://api.viashopmoda.com.br/docs-api/?p=recursos/categoria/consultar&formato=md) |
| `colecao` | integer | **sim** |  | O nome da coleção, se não existir será cadastrado. [Consultar método](https://api.viashopmoda.com.br/docs-api/?p=recursos/colecao/consultar&formato=md) |
| `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_barras` em 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 menor `preco_atacado` das variações; se nenhuma tiver, o cadastro é recusado.
- `preco_varejo` não enviado → menor `preco_varejo` das 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](https://api.viashopmoda.com.br/docs-api/?p=guias/estoque-e-preco&formato=md#promocao-de-por).
- 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.
- `descricao` aceita só as tags `<br>`, `<p>`, `<b>` e `<strong>`, sem atributos. As demais são removidas.
- `video_produto` / `video_atacado`: só links `https://vimeo.com/...` ou `https://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

```json
{
  "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.

```bash
curl -X POST "https://api.viashopmoda.com.br/via/produto/cadastrar/SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d @produto.json
```

## Respostas

Sucesso:

```json
{
  "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](https://api.viashopmoda.com.br/docs-api/?p=guias/catalogo-carga-inicial&formato=md).

## Erros comuns de integração

- Enviar `tipo`, `genero` ou `colecao` como 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.
