API financeira e conectores
O financeiro conecta as condições do credor, os acordos, os meios de cobrança e os recebimentos. As rotas ficam em /api/v1/finance/*, com complementos em credores e acordos. A disponibilidade de um meio depende do conector instalado e da configuração da organização.
Áreas da API
| Família | Responsabilidade |
|---|---|
/finance/connectors, /finance/connections | Catálogo de conectores e ciclo de vida das conexões |
/finance/settings | Emissão automática, prazo da primeira parcela, dia do lote e envio por e-mail |
/finance/charges | Emissão, consulta, reemissão, cancelamento e reenvio de cobranças |
/finance/receipts | Consulta de recebimentos, baixa manual, estorno e uso de crédito |
/finance/batches | Lotes mensais de cobrança |
/finance/settlements, /finance/adjustments | Fechamentos, repasses e ajustes |
/finance/approvals | Pedidos que esperam uma segunda pessoa |
/creditors/{company_id}/finance | Condições financeiras do credor |
/agreements/{agreement_id}/finance | Posição financeira do acordo |
A leitura usa cobres.finance.read. Gestão de conexões e da configuração financeira usa cobres.finance.connections.manage; aprovações usam cobres.finance.approve. Existem permissões próprias para emissão e lotes (cobres.finance.charges.manage), pedidos de baixa manual, estorno e uso de crédito (cobres.finance.manual_payments.request), fechamentos, repasses e ajustes (cobres.finance.settlements.prepare) e condições do credor (cobres.creditors.finance.manage). A coluna de autorização de cada rota está na referência da API.
Ações humanas
Toda escrita financeira (instalar ou alterar conexões, emitir, reemitir, cancelar, baixar, estornar, fechar, repassar, ajustar, aprovar) exige uma pessoa autenticada: uma chave de API recebe 403 actor_not_allowed mesmo com a permissão correspondente. Chaves servem às consultas (GET), que respeitam as permissões de leitura.
Portanto, não substitua a sessão humana por uma chave na expectativa de que todas as ações sejam equivalentes.
Conectores e ambientes
O núcleo financeiro consulta o manifesto do conector para conhecer campos de instalação, capacidades e webhook. Não presuma que todos os provedores suportam os mesmos meios, retornos ou estados.
Uma conexão de homologação pode ser instalada e testada em produção, mas não pode ser ativada nem definida como padrão. A proteção impede que cobranças de teste e eventos simulados atinjam pessoas reais e repasses de produção.
Eventos externos e conciliação
POST /finance/webhooks/{connection_id} recebe mensagens do provedor conforme o contrato do conector. Esse caminho é diferente dos webhooks de saída configurados pela organização. Não encaminhe callbacks genéricos para ele sem seguir o conector.
Emissão, envio e recebimento podem envolver processamento assíncrono. Uma resposta de aceitação não comprova liquidação bancária. Acompanhe o estado retornado pelas consultas, as mensagens do provedor e o fluxo de aprovação do produto.
Pedidos manuais e estornos precisam manter evidência e trilha de aprovação. A interface operacional e o contrato PRD-FINANCEIRO.md detalham esses estados e responsabilidades.