# Atualizar estoque

> Grava o saldo disponível de até 20 variações por requisição, identificadas por código de barras, código externo ou ids.

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


## O que faz

Para cada item, localiza a variação e grava a **quantidade disponível**. Cada variação é processada separadamente: umas podem ser atualizadas e outras não.

## Requisição

| | |
|---|---|
| **Método** | `POST` |
| **URL** | `https://api.viashopmoda.com.br/via/estoque/atualizar/{TOKEN}` |
| **Corpo** | Lista JSON `[ {...}, {...} ]`, até 20 itens por requisição, cabeçalho `Content-Type: application/json` |
| **Token** | Substitua `{TOKEN}` pelo token da loja. Ele vai no caminho da URL, não em cabeçalho. |


## Campos

O corpo é uma **lista** `[ {...}, {...} ]` com no máximo 20 itens. Cada item tem os campos abaixo.

| Campo | Tipo | Obrigatório | Limites | Descrição |
|---|---|---|---|---|
| `cod_produto` | integer | não |  | Código do produto na loja virtual |
| `cod_grade` | integer | não |  | Consultar códigos da grade em [grade/consultar](https://api.viashopmoda.com.br/docs-api/?p=recursos/grade/consultar&formato=md) |
| `cod_estampa` | integer | não |  | Consultar códigos da estampa em [estampa/consultar](https://api.viashopmoda.com.br/docs-api/?p=recursos/estampa/consultar&formato=md) |
| `cod_barras` | string | não |  | Código de barras cadastrado na loja virtual de acordo com o padrão do seu sistema |
| `cod_externo` | string | não |  |  |
| `quantidade` | integer | **sim** |  | Quantidade de estoque q ser atualizada |


## Regras (valem acima da tabela)

- Identifique a variação por **um** destes, nesta prioridade: `cod_barras` → `cod_externo` → `cod_produto` + `cod_grade` + `cod_estampa`.
- `quantidade` é o **saldo final** disponível, não a movimentação.
- Saldo menor que 0 é gravado como 0 (com aviso em `msg_alerta`).
- Se a loja tiver margem de segurança negativa configurada (ex.: −2), ela é somada à quantidade enviada; a resposta traz `gordura` e um aviso.
- Preços enviados aqui são **ignorados**. Use [`preco/atualizar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/preco/atualizar&formato=md).
- Máximo de 20 itens; acima disso a requisição inteira é recusada.

## Exemplo

```json
[
  { "cod_barras": "7890000000101", "quantidade": 4 },
  { "cod_barras": "7890000000102", "quantidade": 0 },
  { "cod_produto": 325, "cod_grade": 17, "cod_estampa": 709, "quantidade": 2 }
]
```

```json
{
  "retorno": true,
  "msg_alerta": [],
  "qtd_atualizar": 3,
  "qtd_atualizados": 2,
  "qtd_nao_atualizados": 1,
  "atualizados": [ ... ],
  "nao_atualizados": [
    { "cod_barras": "7890000000102", "quantidade": 0, "erro": "..." }
  ],
  "gordura": 0
}
```

Erros da requisição inteira:

| Mensagem | Causa |
|---|---|
| `POST de 'estoque' deve ser um array (object)` | Corpo enviado como objeto; envie uma lista. |
| `Permitido enviar no máximo 20 registros por requisição. Quantidade enviada N` | Lote grande demais. |

Erro por item (em `nao_atualizados[].erro`): `faltou: cod_barras, cod_externo ou cod_produto, cod_grade e cod_estampa`, ou variação não encontrada.

## Pode reenviar?

Sim. Como é o saldo final, reenviar o mesmo lote dá o mesmo resultado.

## Onde entra no processo

Guia [Estoque e preço](https://api.viashopmoda.com.br/docs-api/?p=guias/estoque-e-preco&formato=md).

## Erros comuns de integração

- Enviar `-1` para "baixar uma unidade". Envie o saldo resultante.
- Enviar um objeto em vez de lista quando há um só item. Use `[ { ... } ]`.
- Enviar o estoque inteiro periodicamente em vez de só o que mudou.
