# Estoque e preço — atualização contínua

> Como manter estoque e preços em dia depois da carga inicial, sem estourar os limites.

Fonte: https://api.viashopmoda.com.br/docs-api/?p=guias/estoque-e-preco · Atualizado em 16/11/2026


## Resumo em 30 segundos

- A cada movimentação no ERP (entrada, saída, ajuste, reserva de pedido), envie **só as variações que mudaram** com [`estoque/atualizar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/estoque/atualizar&formato=md): lista de até 20 itens com `cod_barras` e a **quantidade disponível final**.
- Para mudar o preço de **todas as variações** de um produto: [`produto/alterar_precos`](https://api.viashopmoda.com.br/docs-api/?p=recursos/produto/alterar_precos&formato=md).
- Para dar um preço diferente a **uma variação**: [`preco/atualizar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/preco/atualizar&formato=md).

## Estoque

### O que enviar

`quantidade` é o **saldo disponível para venda** — não é a quantidade a somar ou subtrair.

```json
[
  { "cod_barras": "7890000000101", "quantidade": 4 },
  { "cod_barras": "7890000000102", "quantidade": 0 }
]
```

A variação pode ser identificada por **um** destes:
1. `cod_barras` (recomendado);
2. `cod_externo` da variação;
3. `cod_produto` + `cod_grade` + `cod_estampa`.

### Como o estoque da loja se comporta

- Quando um pedido é criado na loja, a ViaShopModa **já baixa** o estoque. O ERP precisa reservar o pedido (guia [Pedidos](https://api.viashopmoda.com.br/docs-api/?p=guias/pedidos&formato=md)) para que o saldo que ele envia depois já desconte essa venda.
- Saldo negativo vira **0**.
- A loja pode ter configurado uma **margem de segurança** de estoque (ex.: sempre mostrar 2 a menos). Ela é aplicada automaticamente sobre a quantidade enviada; a resposta informa a margem em `gordura`.

### Quando enviar

| Evento no ERP | Enviar |
|---|---|
| Entrada de mercadoria, ajuste de inventário | As variações afetadas |
| Venda em outro canal (loja física, marketplace) | As variações vendidas |
| Pedido da loja reservado no ERP | Nada (a loja já baixou) — a menos que o saldo do ERP fique diferente |
| Cancelamento processado no ERP | As variações liberadas |

> **Não** envie o estoque inteiro em intervalos fixos. Com 2.500 requisições por dia e 20 itens por requisição, isso esgota o limite e atrasa as atualizações que importam.

### Conferência

Para comparar saldos, use `GET estoque/consultar` (sem filtro lista 100 variações por página) — de preferência fora do horário de pico e no máximo uma vez por dia.

## Preço

Cada produto tem quatro preços: `preco_atacado`, `preco_varejo`, `preco_atacado_promo`, `preco_varejo_promo`.

| Situação | Rota | Observação |
|---|---|---|
| Mudar o preço do produto (vale para todas as variações) | `produto/alterar_precos` | Até 20 produtos por requisição, por `cod_produto` ou `cod_ref`. |
| Uma variação com preço diferente (ex.: tamanho GG mais caro) | `preco/atualizar` | Até 20 variações. `null` volta a usar o preço do produto. |
| Reenvio completo do produto | `produto/cadastrar` | Também grava os preços, mas recria as variações. |

### Promoção ("de / por")

Ao **enviar**: `preco_*` = preço normal; `preco_*_promo` = preço promocional, **menor** que o normal. A loja passa a vender pelo promocional e mostra o normal riscado ("de R$ 129,90 por R$ 99,90").

```json
{ "preco_varejo": 129.90, "preco_varejo_promo": 99.90 }
```

- Em `produto/cadastrar`, um promocional **maior ou igual** ao preço normal é ignorado (sem promoção).
- Para encerrar a promoção, envie de novo sem o campo `*_promo` (ou com `0`).

> **Atenção ao consultar:** a loja grava invertido. Em `produto/consultar`, `preco_*` é o preço **de venda** (o promocional, se houver) e `preco_*_promo` é o preço **"de"** (o normal). Sem promoção, `preco_*_promo` vem `0.00`.

### Varejo vazio

- Em `produto/cadastrar`: varejo não enviado = igual ao atacado.
- Em `produto/alterar_precos`: varejo `0` = atacado + a margem sugerida configurada na loja.

## Erros comuns de integração

- Enviar a quantidade movimentada (`-2`) em vez do saldo final.
- Mandar mais de 20 itens: em `produto/alterar_precos` o excedente é **descartado** com um aviso em `msg_alerta`; nas outras rotas a requisição é recusada.
- Atualizar o preço de cada variação quando o preço é o mesmo do produto. Use o preço do produto e deixe a variação com `null`.
