API Reference: Financeiro

Base URL: /api/financeiro. Controle financeiro do nucleo com lancamentos de receitas e despesas, resumo consolidado e portal de transparencia.

Resumo de Endpoints

POST /api/financeiro

Cria um novo lancamento financeiro manual no nucleo.

Permissao: COORDENADOR / ADMINISTRADOR

Body

Response 200

{
  "id": "uuid",
  "tipo": "DESPESA",
  "valor": 350.00,
  "categoria": "EVENTO",
  "data": "2026-04-01"
}

GET /api/financeiro

Lista lancamentos do nucleo com paginacao e filtros. Inclui campos origem e asaas_payment_id no select para rastreabilidade de lancamentos automaticos.

Permissao: COORDENADOR / ADMINISTRADOR

Query Params

Response 200

{
  "data": [
    {
      "id": "uuid",
      "tipo": "RECEITA",
      "valor": 150.00,
      "categoria": "PLANO",
      "descricao": "Plano Premium - sync Asaas",
      "comprovante_url": null,
      "data": "2026-04-01",
      "criado_em": "2026-04-01T12:00:00Z",
      "origem": "ASAAS_SYNC",
      "asaas_payment_id": "pay_abc123",
      "usuarios": { "nome": "Admin Silva" },
      "projetos": null
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 83, "totalPages": 5 }
}

Notas sobre origem e asaas_payment_id

• origem: indica se o lancamento foi criado manualmente ou via integracao (ex: ASAAS_SYNC, MANUAL).
• asaas_payment_id: ID do pagamento no Asaas quando o lancamento foi criado automaticamente pelo sync de pagamentos. Null para lancamentos manuais.

GET /api/financeiro/resumo

Retorna o resumo financeiro consolidado do nucleo, com filtro opcional por periodo.

Permissao: COORDENADOR / ADMINISTRADOR

Query Params

Response 200

{
  "totalReceitas": 12500.00,
  "totalDespesas": 4300.00,
  "saldo": 8200.00,
  "despesasPorCategoria": {
    "EVENTO": 2000.00,
    "ADMINISTRATIVO": 1500.00,
    "PROJETO": 800.00
  }
}

Notas

• Sem filtros de data: retorna totais de todos os lancamentos do nucleo.
• Com dataInicio e/ou dataFim: filtra por periodo. Util para relatorio mensal/trimestral.
• saldo = totalReceitas - totalDespesas.
• despesasPorCategoria agrupa apenas DESPESAS; receitas nao aparecem nesse campo.

DELETE /api/financeiro/:id

Remove um lancamento financeiro permanentemente (hard delete).

Permissao: ADMINISTRADOR

Response 200

{ "message": "Lancamento excluido" }

GET /api/financeiro/transparencia

Retorna dados financeiros publicos do nucleo para qualquer membro autenticado. Nao exige cargo especial.

Comportamento

• Verifica o master toggle transparencia_financeira no nucleo. Se desativado, retorna { "habilitado": false }.
• Cada secao e controlada por sub-toggles independentes no nucleo:
  • transparencia_fin_receitas → inclui totalReceitas
  • transparencia_fin_despesas → inclui totalDespesas
  • transparencia_fin_saldo → inclui saldo
  • transparencia_fin_categorias → inclui despesasPorCategoria
• Resumo e calculado a partir do inicio do mes corrente.
• Inclui lista dos ultimos 50 lancamentos (ordenados por data desc).

Sanitizacao de dados pessoais

Os lancamentos retornados NAO incluem dados pessoais (nome do autor, email, etc.). O campo descricao e sanitizado:

• Descricoes com formato Plano X - Nome Completo - ... sao truncadas para exibir apenas o tipo de plano.
• Emails no formato <email@dominio> sao removidos.
• Se a descricao ficar vazia apos sanitizacao, usa-se label generica baseada na categoria (ex: Receita de plano).

Response 200 (exemplo com todos os toggles ativos)

{
  "habilitado": true,
  "totalReceitas": 12500.00,
  "totalDespesas": 4300.00,
  "saldo": 8200.00,
  "despesasPorCategoria": { "EVENTO": 2000.00, "ADMINISTRATIVO": 1500.00 },
  "lancamentos": [
    {
      "id": "uuid",
      "tipo": "RECEITA",
      "valor": 150.00,
      "categoria": "PLANO",
      "data": "2026-04-01",
      "criado_em": "2026-04-01T12:00:00Z",
      "descricao": "Plano Premium"
    }
  ]
}

Categorias de Lancamento

Nota sobre categoria PLANO

Lancamentos com categoria PLANO sao frequentemente gerados automaticamente pela integracao com Asaas (sync de pagamentos de planos). Nesse caso, o campo origem indica a origem automatica e asaas_payment_id contem o ID do pagamento para rastreabilidade.

Enum: origem_lancamento

O campo origem nos lancamentos indica como o registro foi criado:

Notas de Arquitetura

• Todas as queries filtram por nucleo_id — multi-tenant com RLS ativo.
• O campo autor_id registra quem criou o lancamento manual (JOIN com usuarios no select).
• O campo projeto_id permite associar lancamentos a projetos do nucleo (JOIN com projetos no select).
• Hard delete: a exclusao via DELETE e permanente. Nao ha soft delete para lancamentos financeiros.