# 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.

Fonte: https://api.viashopmoda.com.br/docs-api/?p=guias/catalogo-carga-inicial · 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](https://api.viashopmoda.com.br/docs-api/?p=guias/estoque-e-preco&formato=md)).

## Como o catálogo é organizado

```text
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](https://api.viashopmoda.com.br/docs-api/?p=glossario&formato=md). 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

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

### 3. Enviar as fotos

Uma requisição por foto. A foto fica ligada ao produto e à estampa da variação do `cod_barras` informado.

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

### 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`](https://api.viashopmoda.com.br/docs-api/?p=recursos/produto/atualizar_textos&formato=md): 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`](https://api.viashopmoda.com.br/docs-api/?p=recursos/produto/alterar_colecao&formato=md) |
| Mostrar as outras cores de um modelo cadastrado em vários produtos | [`produto/associar_supervitrine`](https://api.viashopmoda.com.br/docs-api/?p=recursos/produto/associar_supervitrine&formato=md) |
| Sugerir produtos relacionados | [`produto/associar_comprejunto`](https://api.viashopmoda.com.br/docs-api/?p=recursos/produto/associar_comprejunto&formato=md) |
| Guardar o código do ERP em produto, tipo, grade ou estampa | [`cod_externo/associar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/cod_externo/associar&formato=md) |

## 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.
