Transações e extrato

O ledger financeiro do bitERP — como consultar transações, o extrato por conta e o saldo, e remover lançamentos. Na API de Integrações você não cria nem edita transações: apenas consulta e exclui (soft delete).

As transações financeiras (/financial-transactions) são o ledger (livro-razão) do tenant: cada linha é um crédito ou débito lançado em uma conta financeira. Na API de Integrações você não cria nem edita transações — elas nascem de fluxos de negócio (veja abaixo). O que você faz por aqui é consultar (transações, extrato e saldo) e remover lançamentos via exclusão lógica (soft delete).

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

Como as transações são criadas

Você não cria transações diretamente pela API de Integrações. Elas são geradas pelo bitERP em fluxos de negócio:

Alocação/liquidação de uma conta a receber ou a pagar (o pagamento em si é uma transação).
Liquidação automática ao criar um recebível/pagável com auto_generate_transaction em uma conta manual (cash/digital_wallet).
Importação OFX, transferências entre contas e integrações bancárias.

O source de cada transação indica sua origem: manual, ofx, integration, migration ou transfer.

Conceitos e campos-chave

O sinal do amount define a natureza do lançamento: crédito é positivo, débito é negativo.

Campo	Tipo	Observações
`account_id`	UUID	Conta financeira do lançamento
`amount`	string	Decimal `numeric(18,6)` com sinal: positivo = crédito (`"1500.000000"`), negativo = débito (`"-250.500000"`)
`posted_at`	date-time	Data/hora contábil do lançamento
`source`	enum	`manual`, `ofx`, `integration`, `migration`, `transfer`
`trn_type`	string	Tipo do lançamento (ex.: `CREDIT`, `DEBIT`, `XFER`)
`is_reconciled`	boolean	Se a transação já foi conciliada
`transfer_id`	UUID	Preenchido quando faz parte de uma transferência
`memo`, `name`	string	Descrição / contraparte
`metadata`	object

Extrato de uma conta

GET /financial-transactions/account/{accountId} retorna o extrato — todas as transações da conta, ordenadas da mais recente para a mais antiga (posted_at decrescente). O retorno é um array simples (não paginado).

curl "https://api.biterp.ai/financial-transactions/account/9c8b7a6d-5e4f-4321-8b0a-1d2c3e4f5a6b" \
  -H "Authorization: Bearer sk_abc123_secretXYZ"

Saldo

GET /financial-transactions/balance/{accountId} retorna o saldo da conta (initial_balance + SOMA(amount)), no mesmo formato do endpoint de saldo de contas financeiras:

{ "balance": "15234.560000" }

Listar e remover

GET /financial-transactions lista transações de forma paginada (ver filtros e paginação); a ordenação padrão é posted_at decrescente. DELETE /financial-transactions/{id} faz soft delete e responde 204 No Content.

Referência dos endpoints

Método	Endpoint	Referência
GET	`/financial-transactions`	Listar transações
GET	`/financial-transactions/account/{accountId}`	Extrato da conta
GET	`/financial-transactions/balance/{accountId}`	Saldo da conta
GET	`/financial-transactions/{id}`	Buscar por ID
DELETE	`/financial-transactions/{id}`	Remover transação