Movimentações

Envie as entradas, saídas e vendas do ERP e leia de volta o livro do WMS, com os ajustes feitos pela operação.

Todo saldo do WMS muda por uma movimentação, registrada num livro que não se altera: o que foi lançado errado é corrigido por um estorno, que é outro lançamento.

Enviar entradas, saídas e vendas

POST/wms/movements

{
  "items": [
    {"external_id": "NF-123456-1", "type": "receipt", "store_code": "0012", "storage_location": "01",
     "internal_code": "1001", "quantity": 48, "reason": "COMPRA", "document": "NF 123456",
     "occurred_at": "2026-11-10T07:40:00-03:00"},
    {"external_id": "CUPOM-998877-3", "type": "sale", "store_code": "0012", "storage_location": "01",
     "bin": "05-003-02", "internal_code": "1001", "quantity": 2}
  ]
}

`type`	Quando	Endereço (`bin`)
`receipt`	Nota de compra, transferência recebida, devolução de cliente	Vazio: vai para "A endereçar", e a operação guarda depois
`issue`	Transferência enviada, consumo, perda	Vazio: baixa do "A endereçar"
`sale`	Venda	Vazio: baixa do "A endereçar"

Saída e venda saem de um endereço

O WMS baixa o saldo de um endereço. Sem bin, a saída e a venda baixam do "A endereçar", e só passam se houver saldo lá. Se o produto já foi guardado na prateleira, informe o endereço (GET /wms/bin-stocks diz onde está), ou combine com o cliente que a zona "A endereçar" aceite saldo negativo. Saída sem saldo volta com wms_insufficient_stock, e nada é gravado.

O `external_id`: enviar sem medo de duplicar

Cada linha leva um external_id único no seu ERP (por exemplo, número da nota + item). Ele torna o envio seguro de repetir:

Situação	Resultado do item
Linha nova	`created`
A mesma linha de novo, igual	`skipped`, com o `id` do lançamento que já existia. Nada é lançado duas vezes
O mesmo `external_id` com conteúdo diferente	`error`, `wms_idempotency_conflict`

Isso vale para sempre, não só por 24 horas como o cabeçalho Idempotency-Key. Para corrigir uma linha já lançada, fale com a operação: a correção é um estorno no BIX.

Quantidade e produto

Com internal_code, a quantidade está na unidade do item de estoque (normalmente a unidade).
Com ean, a quantidade está na unidade daquele código: 2 caixas de 12 são 24 unidades.

Recusas

Além de invalid_parameter e store_not_allowed, o WMS recusa com os seus próprios códigos:

`code`	Motivo
`wms_insufficient_stock`	A origem não tem saldo para a saída
`wms_bin_blocked`	Endereço inativo ou bloqueado para entrada ou saída
`wms_idempotency_conflict`	O `external_id` já foi usado com outro conteúdo
`wms_invalid_structure`	Depósito, endereço ou motivo inválido para o tipo

Ler o livro

GET/wms/movements

O livro traz tudo o que mexeu no estoque, inclusive o que a operação fez no BIX: guardar, repor, ajustar e, principalmente, o ajuste de inventário (count_adjustment), que é como o resultado de uma contagem chega ao saldo.

Para sincronizar, use o cursor since_id:

Primeira leitura: sem since_id (ou since_id=0).
Guarde o maior id recebido.
Na próxima vez, peça since_id=<o maior id>. Vêm só os lançamentos novos, na ordem.

O livro só cresce: um lançamento nunca muda depois de gravado. Por isso o id é um cursor confiável, ao contrário de uma data de alteração.

Campo	O que é
`from` / `to`	Origem e destino (endereço, depósito e loja). A entrada não tem origem; a saída não tem destino
`external_id`	O que você mandou ao lançar pela API; `null` para o que nasceu no BIX
`source`	`integration` (esta API), `web`, `app`, `import` (arquivo) ou `system`
`reversal_of`	Se for um estorno, o `id` do lançamento estornado