ERP de cobrança e conciliação

Duas rotinas que fecham o ciclo do financeiro. A cobrança (dunning) transforma contas a receber vencidas numa fila de lembretes com mensagem pronta. A conciliação compara o extrato do banco com os títulos do ERP e quita os que combinam. Ambas operam sobre os títulos do ERP financeiro.

Como funciona

Estados de uma transação do extrato:

1. Cadastrar a conta bancária
   Crie a conta em Contas bancárias.
2. Importar o extrato
   POST /conciliacao/import com o OFX.
3. Decidir as pendentes
   Para cada pending, match, ignore ou deixe para depois.

Conceitos importantes

OFX e FITID

OFX é o formato de extrato que os bancos exportam. Cada transação traz um identificador (FITID) único por conta. A plataforma usa o par conta e FITID para saber que uma transação já foi importada, então reimportar o mesmo período é seguro.

Marcadores da mensagem de cobrança

O texto do modelo aceita {cliente}, {valor}, {vencimento} e {dias_atraso}. A plataforma substitui na fila; marcadores desconhecidos ficam como estão.

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

• Esperar que PUT /cobranca/policy com active dispare envios: nada é enviado.
• Cadastrar etapa com offset_days negativo esperando aviso antes do vencimento: a fila só mostra títulos já vencidos.
• Casar manualmente uma transação com um título de valor diferente (400).
• Tentar reverter uma transação ignored: não há rota; escolha o motivo com cuidado.
• Enviar um arquivo que não é OFX: a importação responde 400 e deixa um registro failed no histórico.
• Importar no modo JSON esquecendo content: o OFX vai como texto no corpo, não como caminho de arquivo.

Próximos passos