ERP de armazém e separação

O WMS leve do seller organiza o depósito em endereços e diz onde cada produto está; a separação (picking) transforma um pedido numa tarefa de ir buscar os itens. O saldo total por depósito continua no ERP de estoque; aqui você detalha onde ele está.

Como funciona

Estados de uma lista de separação:

1. Endereçar
   Cadastre endereços (ou importe um CSV) e dê a primeira contagem de cada produto.
2. Receber o pedido
   A lista nasce open quando o pedido é criado, ou use POST /picking/from-order.
3. Separar
   claim, depois pick item a item, depois pack.

Conceitos importantes

Saldo por endereço e saldo do depósito

São dois livros diferentes. O saldo por endereço só responde onde as unidades estão. Uma contagem com diferença e uma movimentação entre depósitos diferentes ajustam também o saldo do depósito; mover entre endereços do mesmo depósito não mexe nele.

Falta na separação

Se um item não for separado por inteiro, informe shortage_reason. A lista continua válida e pode ser embalada mesmo com itens faltando.

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

• Chamar pick antes de claim: a lista precisa estar em picking.
• Mandar quantity menor que o pedido sem shortage_reason.
• Esperar que pack verifique itens, baixe estoque ou avance o pedido: nada disso acontece.
• Ler item_count no detalhe da lista: vem 0. Conte items.
• Importar CSV esperando tudo-ou-nada: as linhas boas entram e as ruins voltam em errors.
• Criar dois endereços com o mesmo code no mesmo depósito: o segundo falha com 400 genérico.

Próximos passos