Contas financeiras

Uma conta financeira (/financial-accounts) representa onde o dinheiro do tenant entra e sai: uma conta corrente, poupança, caixa ou carteira digital. É a conta que amarra o financeiro — toda transação, conta a receber e conta a pagar referencia uma conta financeira.

Permissão exigida: financial-accounts (ações create, read, update, delete).

Conceitos e campos-chave

Os tipos cash e digital_wallet são contas manuais — é nelas que a liquidação automática de contas a receber/pagar pode gerar transações (ver auto_generate_transaction em Contas a receber).

Criar uma conta

curl -X POST https://api.biterp.ai/financial-accounts \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Conta Corrente - Banco do Brasil",
    "type": "checking",
    "initial_balance": "10000.000000",
    "display_order": 1
  }'

Calcular o saldo

GET /financial-accounts/{id}/balance calcula o saldo atual da conta:

saldo = initial_balance + SOMA(amount de todas as transações da conta)

Como créditos têm amount positivo e débitos amount negativo, a soma já é o valor líquido. O saldo é retornado como string com 6 casas decimais:

{ "balance": "15234.560000" }

Para um saldo histórico (saldo em uma data específica), envie o query param up_to_date (ISO 8601) — só as transações com posted_at até essa data são consideradas:

curl "https://api.biterp.ai/financial-accounts/{id}/balance?up_to_date=2026-06-30T23:59:59Z" \
  -H "Authorization: Bearer sk_abc123_secretXYZ"

Listar e manter

GET /financial-accounts retorna a lista paginada (ver filtros e paginação). Campos filtráveis: name, type, is_active, created_at, updated_at. Ordenação por id, name, type, initial_balance, display_order, created_at.

DELETE /financial-accounts/{id} faz soft delete e responde 204 No Content.

Referência dos endpoints