ERP de compras do seller

Compras é o caminho da mercadoria que entra: você cadastra fornecedores, pede preço (cotação), faz o pedido de compra, recebe a mercadoria ou a nota fiscal do fornecedor (NF-e) e o sistema dá entrada no estoque e gera o que precisa ser pago. Estas rotas foram pensadas para o seller não depender de planilhas.

Como funciona

Ciclo de um pedido de compra:

Estados de uma NF-e de entrada:

1. Cotar (opcional)
   Abra uma cotação, registre as ofertas e converta a melhor em pedido.
2. Pedir
   Crie o pedido, submeta, aprove se necessário e marque como enviado.
3. Receber
   Receba o pedido no depósito, ou importe o XML da NF-e, vincule as linhas e lance.
4. Pagar
   As contas a pagar geradas pela NF-e aparecem no financeiro.

Conceitos importantes

Custo médio ponderado

Cada entrada recalcula o custo médio do produto no depósito, ponderando o saldo atual pelo custo novo. O custo novo é o unitário mais a parte do frete e das outras despesas da compra, rateada pelo valor da linha. Veja o resultado em Custos.

Preço aprendido por fornecedor

Criar um pedido e lançar uma NF-e gravam o último custo e a última quantidade por produto e fornecedor. Consulte em Fornecedores.

Fatores de conversão

Uma nota pode vir em caixas e o seu estoque ser em unidades. O conversion_factor da linha traduz uma coisa na outra. Se quantity vezes o fator não der um número inteiro, o lançamento é recusado.

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

• Receber o pedido e lançar a NF-e da mesma compra: o estoque entra em dobro.
• Esperar que send mande e-mail ao fornecedor: ele só muda o estado.
• Chamar receive num pedido approved: só sent e partially_received podem ser recebidos.
• Tentar lançar uma nota pending_match: vincule ou ignore todas as linhas primeiro.
• Mandar PUT de fornecedor sem active, email e phone: eles são apagados ou reativados.
• Passar product_id de outro dono num pedido: a plataforma aceita e o estoque do catálogo não reflete.

Próximos passos