Endpoints

Obrigações financeiras compartilhadas

A criação avulsa é exclusiva do workspace empresarial. No pessoal, as ocorrências nascem das regras de recorrência; listagem, confirmação de valor e liquidação continuam no mesmo contrato. Regras de valor fixo lançam automaticamente no vencimento e geram o registro em Transações. Estimativas exigem confirmação explícita do valor real; a liquidação comum confirma e registra o pagamento na mesma operação. Nenhuma dessas operações executa Pix ou transferência bancária.

A base é /v1/financial-obligations. Envie o destino explícito em X-Workspace-Id. Valores deste contrato usam centavos inteiros de BRL; datas civis usam AAAA-MM-DD no fuso da empresa.

• GET /, GET /:id, GET /summary e GET /v1/recurring-expenses/projection?months=12: consulta com financial:read. A lista aceita direction (income/expense), status, from, until, overdue, page e limit (máximo 100).
• POST / e PATCH /:id: cadastro, edição e reagendamento, com financial:write. DELETE /:id: exclusão lógica e auditável, com financial:delete.
• POST /:id/submit-approval: solicita aprovação com approvals:submit. A decisão continua no endpoint de etapas, com approvals:decide.
• POST /:id/payments: confirmação explícita, com payables:pay. POST /:id/settlements/:settlementId/reverse: estorno auditável de uma liquidação. Para remover apenas associação de transação existente, use POST /:id/settlements/:settlementId/unlink. Ambas exigem payables:reverse.
• POST /:id/attachments: comprovante privado multipart, campo file, PDF/JPEG/PNG válido até 10 MB. GET /:id/attachments/:attachmentId: download autorizado; acrescente /content para resposta JSON com contentBase64.
• /v1/recurring-expenses/:id/activate, /pause, /resume e /end: ações POST sobre regras compartilhadas, com expectedVersion. Cadastro e listagem usam /v1/recurring-expenses.

Para regras antigas, activate recebe from (hoje ou uma data futura) e historicalDates opcionais. Para uma regra ativa, POST /v1/recurring-expenses/:id/historical-occurrences recebe historicalDates: de 1 a 120 datas anteriores a hoje, selecionadas explicitamente. Datas incompatíveis com a frequência ou com lançamento financeiro existente impedem a operação inteira. Repetir a seleção não duplica as contas.

No cadastro, descrição, valor, vencimento e chave são obrigatórios. Beneficiário, categoria, departamento, centro de custo, projeto, responsável e carteira sugerida são opcionais. Juros/multa usam chargesCents, descontos usam discountCents e exigem adjustmentReason. O total é amountCents + chargesCents − discountCents e deve permanecer positivo. A carteira efetiva é obrigatória apenas no pagamento. A regra recorrente mantém o contrato amount em reais, além de frequência, início, término opcional, isFixed e idempotencyKey.

{
  "description": "Manutenção",
  "amountCents": 20000,
  "dueDate": "2026-09-25",
  "idempotencyKey": "manutencao-setembro-2026"
}

Para confirmar, informe expectedVersion, idempotencyKey, amountCents, paymentDate e walletId. Se a obrigação ainda está estimada, envie também confirmedAmountCents para confirmar o valor real desta ocorrência na mesma transação; valor igual à previsão também precisa dessa confirmação explícita. Uma chave repetida com os mesmos dados retorna o resultado anterior; dados diferentes geram conflito. Não crie outra transação financeira para o mesmo pagamento. O vínculo opcional existingFinancialRecordId associa um lançamento conferido sem novo débito.

Estados da obrigação: open, partial, paid e cancelled. settledCents informa o liquidado e remainingCents o restante. Aprovação é independente. Uma conta open com vencimento anterior a hoje está vencida; rejeição e falta de pagamento não a cancelam. estimated exige confirmação explícita do valor real desta ocorrência, inclusive quando igual à previsão. Edição usa expectedVersion; scope=following altera as próximas abertas, preservando exceções. Mudanças financeiras reavaliam a aprovação.

O total aberto inclui obrigações cadastradas e exclui quitadas, canceladas e previsões virtuais. Vencidas, restante do mês e próximo mês são recortes e não devem ser somados ao total. Pago no mês usa a data efetiva. A projeção identifica actual, obligation e forecast, com horizonte de 1 a 24 meses. Valores estimados e competências passadas são informados separadamente.

Exemplo: em setembro, R$ 300 vencidos e R$ 200 a vencer, mais R$ 100 recorrentes de outubro, representam R$ 600 abertos. R$ 100 já pagos em setembro não entram nesse total. Pagar os R$ 300 em outubro remove a obrigação do aberto e registra o realizado em outubro, uma única vez.

Permissões de pagamento são novas e não são adicionadas automaticamente às credenciais existentes. A aprovação final agora apenas autoriza a obrigação. Valor fixo lança em Transações no vencimento; estimativa e aprovação pendente exigem confirmação. Pagamentos parciais são suportados até o saldo restante. Cartão pessoal ou empresarial registra a ocorrência na fatura sem débito de carteira; o pagamento da fatura permanece separado. Reembolso, contribuição de sócio e devolução de principal não se confundem com lucro.