ERP de estoque do seller

O ERP do seller é o conjunto de rotas com que um lojista controla o próprio estoque, compras, financeiro, caixa e fiscal, sem depender de um sistema externo. Esta seção cobre o estoque: onde as unidades estão (depósitos), quantas há (saldos), o que mexeu nelas (movimentos) e o que já está prometido (reservas).

Como funciona

O estoque é um livro-razão: você nunca edita o saldo, você lança um movimento e o saldo muda como consequência. Cada linha da grade de saldos é um par produto e depósito.

1. Crie um depósito
   POST /inventory/warehouses com o nome. Sem depósito não há onde guardar nada.
2. Dê entrada no estoque
   POST /inventory/movements com type: in, ou receba uma compra ou uma NF-e de entrada na seção de compras.
3. Defina o mínimo
   PUT /inventory/stock/reorder-point para receber o alerta de estoque baixo.
4. Acompanhe
   GET /inventory/stock para o saldo e GET /inventory/movements para o histórico.

Estados de uma reserva:

Conceitos importantes

Movimento: in, out e adjust

in soma, out subtrai e adjust aplica um delta com sinal. Para corrigir uma contagem física, calcule a diferença e envie como adjust. O servidor não aceita informar o saldo final.

Estoque do ERP e estoque do catálogo

O ERP guarda o saldo por depósito. A vitrine, o checkout e o painel leem a quantidade do produto no catálogo. Quando o produto é do próprio seller, cada movimento do ERP também ajusta essa quantidade, com lançamento no razão de estoque da loja. Produto de outro dono nunca é tocado.

Autenticação e escopo

Todas as rotas ficam sob /api/v1/vendor/erp e pedem o token de um usuário seller (lojista), enviado em Authorization: Bearer $TOKEN. Um seller é um vendedor que opera dentro do marketplace da loja, com catálogo, pedidos e financeiro próprios. O token de administrador recebe 403 aqui. Veja Tokens.

O seller é descoberto pelo token. Nenhuma rota aceita vendor_id no corpo ou na URL, e um registro de outro seller responde como se não existisse (404). Não há checagem de privilégio por função do ERP: qualquer usuário seller aprovado da loja que tenha um token válido alcança todas as rotas.

Dinheiro, quantidades e datas

Todo valor monetário é um inteiro em centavos (4990 = R$ 49,90) e o nome do campo termina em _cents. Quantidades são inteiros. Datas de vencimento e de período são YYYY-MM-DD; carimbos de data e hora são RFC 3339 em UTC. Veja Ids, dinheiro e datas.

Erros e listas

O corpo de erro é {"error": "texto"}, às vezes com detail. As mensagens de validação do ERP vêm em inglês, muitas com o prefixo vendorerp:, e algumas em português; as tabelas de erros mostram o texto como o servidor devolve. Regra geral: 400 para validação e para transição de estado inválida, 404 quando o registro não existe (a decisão é feita procurando a palavra not found na mensagem), 500 quando um id de filtro ou de caminho não é um UUID válido. Veja Erros.

As listas respondem {"<plural>": [...], "total": N}. Quando a rota é paginada, total é a contagem de todas as páginas; quando não é, é o tamanho do vetor. Apagar é sempre exclusão lógica (soft delete): o registro some das listas, mas não é destruído. Veja Paginação.

Endpoints

Erros comuns

• Enviar adjust com o saldo final em vez do delta. quantity: 50 soma 50, não deixa o saldo em 50.
• Tentar apagar ou desativar um depósito com saldo. Transfira ou dê baixa antes (409).
• Fazer PUT de depósito sem is_active: o depósito volta a ficar ativo.
• Usar quantity (físico) para prometer prazo ao cliente. Use available.
• Passar um id que não é UUID num filtro e esperar 400: a plataforma responde 500.
• Contar com to=2026-10-31 para incluir o dia 31: sem hora, o dia 31 fica de fora. Use 2026-10-31T23:59:59Z.

Próximos passos