ERP financeiro do seller

O financeiro do ERP é um controle de caixa simples: você registra o que deve pagar e o que tem a receber, baixa cada título quando o dinheiro se move e acompanha o fluxo de caixa. Não é contabilidade nem emite cobrança bancária; é o livro de títulos do seller.

Como funciona

Vida de um título:

1. Registrar o título
   POST /financeiro/payables ou /receivables com descrição, valor e vencimento.
2. Baixar
   POST .../settle, uma ou várias vezes, até quitar.
3. Acompanhar
   GET /financeiro/cashflow para o resumo e /cashflow/series para o gráfico.

Conceitos importantes

Filtros de estado derivados

GET .../payables?status=open não devolve tudo que está em aberto: devolve só o que ainda não venceu e não teve baixa parcial. Para ter tudo que ainda deve, junte open, partial e overdue, ou não filtre e leia status e paid_amount_cents.

Principal, juros e multa

Só o principal reduz o saldo do título e entra nos saldos bancários e no fluxo de caixa. Juros e multa são informativos.

Duas formas de quitar

Pela baixa (settle), que grava o histórico e entra nos saldos; ou pela conciliação bancária, que quita o título casando-o com uma linha do extrato, sem criar baixa.

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

• Filtrar status=open esperando todos os títulos em aberto (ele exclui vencidos e parciais).
• Enviar amount_cents maior que o saldo na baixa (400 valor da baixa acima do saldo devedor).
• Contar com juros e multa para reduzir o saldo: eles não reduzem.
• Apagar um título quitado em vez de reabri-lo: as baixas dele continuam nos saldos.
• Pedir a série de caixa para mais de 180 dias (400).
• Passar um id que não é UUID em supplier_ref_id ou customer_user_id e esperar 404: a lista responde 500 e a criação responde 400.

Próximos passos