Operações financeiras

Estas operações registram fatos dentro do LIGGA. Elas não executam pagamentos em bancos, PIX ou transações na adquirente. Produção, Repasses, Documentos e Vitrines ficam fora desta expansão.

Os comandos operacionais de vendas, despesas e financeiro aceitam até 12.000 bytes de JSON normalizado pelo banco, incluindo os identificadores do caminho incorporados à operação. Os limites individuais de itens, parcelas e campos não são cumulativos: uma combinação que ultrapasse esse teto retorna 422 validation e não grava parte da operação.

Cadastros

Contas, chaves PIX, carteiras, cartões, maquininhas e taxas aceitam POST na coleção para criar, PATCH /{id} para alterar, DELETE /{id} para arquivar e POST /{id}/restore para restaurar. Escrita exige plano full, módulo habilitado e escopo :write do recurso. O cadastro global de bancos permanece somente leitura.

Em disputa de atualização de um cadastro, 409 resource_conflict pode informar que a transação foi desfeita. Nesse caso específico, releia o cadastro e repita com uma nova Idempotency-Key. Essa resposta é terminal no mecanismo de idempotência dos cadastros; não se aplica aos comandos monetários abaixo, que recuperam o resultado pelo mesmo UUID.

Saldo inicial de contas/carteiras é informado somente na criação. Saldos calculados e limite disponível não aceitam edição direta. Cartões expõem somente os últimos quatro dígitos. Alterar ciclo ou conta de um cartão com faturas em aberto retorna 409 resource_conflict.

Alterar ou restaurar uma taxa cria outra versão e devolve um novo id. A versão anterior mantém sua vigência; recebimentos confirmados conservam os termos aplicados. PIX arquivado tem is_active=false e continua legível no histórico.

Registrar e reverter

Todas as escritas abaixo exigem UUID em Idempotency-Key. Repetições retornam o mesmo recibo em meta.command_id, após verificar novamente as permissões. Valores usam centavos inteiros: 10000 representa R$ 100,00. Informe a data real em effective_date, no formato YYYY-MM-DD.

Operação	Caminho POST	Escopo
Receber parcela	/v1/sales/installments/{id}/receipts	sales:write
Estornar recebimento	/v1/sales/receipts/{id}/reversals	sales:write
Baixar parcela de despesa	/v1/expenses/installments/{id}/settlements	expenses:write
Estornar baixa	/v1/expenses/settlements/{id}/reversals	expenses:write
Pagar fatura	/v1/credit-cards/invoices/{id}/payments	credit-cards:write
Estornar pagamento de fatura	/v1/credit-cards/invoice-payments/{id}/reversals	credit-cards:write
Transferir entre contas/carteiras	/v1/transfers	transfers:write
Estornar transferência	/v1/transfers/{id}/reversals	transfers:write

Recebimentos, baixas, pagamentos e reversões podem ser parciais. O total não pode ultrapassar o restante a pagar ou o valor original ainda não revertido. Estornos exigem reason, conservam a conta histórica e não aceitam data anterior à operação. Não é possível apagar ou editar diretamente um movimento confirmado.

Baixa de R$ 40,00:

{
  "amount_cents": 4000,
  "payer_kind": "bank_account",
  "payer_id": "86000000-0000-4000-8000-000000000001",
  "effective_date": "2026-10-05",
  "payment_method": "pix"
}

Em recebimentos, use destination_kind e destination_id. A taxa da maquininha é calculada a partir dos termos da venda; não envie taxas no corpo. O recibo informa bruto, taxa e líquido. Despesa em cartão é liquidada pela fatura, evitando duas saídas de caixa para a mesma compra.

Transferência de R$ 100,00:

{
  "source_kind": "bank_account",
  "source_id": "86000000-0000-4000-8000-000000000001",
  "destination_kind": "wallet",
  "destination_id": "86000000-0000-4000-8000-000000000002",
  "amount_cents": 10000,
  "effective_date": "2026-10-05",
  "description": "Suprimento da carteira"
}

Histórico e saldo operacional

Consulte GET /v1/sales/{id}/receipts, /v1/expenses/{id}/settlements, /v1/credit-cards/invoices/{id}/payments e /v1/transfers. Esses históricos incluem estornos e aceitam limit de 1 a 100 e o cursor UUID retornado.

Para contas e carteiras, use POST /v1/{recurso}/{id}/cash-opening uma única vez com opening_balance_cents e cutoff_date. A abertura deve representar saldo já reconciliado e cobre os movimentos registrados até aquele momento. O sistema não reconstrói histórico ausente a partir de status antigos.

GET /v1/{recurso}/{id}/cash-projection informa opened, balance_cents, metadados da abertura e a base explicit_opening_plus_recorded_commands. Antes da abertura, o saldo é nulo. Depois, soma recebimentos líquidos e entradas de transferência, subtrai baixas, pagamentos de fatura e transferências de saída, e considera suas reversões. Saldos negativos são permitidos neste registro.

GET /v1/{recurso}/{id}/cash-statement lista os movimentos da mesma projeção. A resposta contém data, pagination, opening e meta. Seu cursor é uma sequência decimal em texto: repasse-o sem converter em número. Novas operações em contas abertas não podem ter data anterior ao corte.

Os GETs anteriores de contas/carteiras conservam current_balance e balance_basis=initial_balance_plus_paid_sales. Essa interpretação não mudou. As leituras anteriores de faturas e parcelas continuam em /v1/credit-cards/{credit_card_id}/invoices.

Veja Contas bancárias e PIX, Vendas, Despesas e Idempotência.