Módulo Finance - Biblioteca HedHog

Este documento técnico detalha o módulo financeiro @hed-hog/finance do monorepo HedHog, cobrindo sua visão geral, escopo, endpoints, regras de autenticação, estruturas de dados, erros comuns, banco de dados, regras de negócio e guia rápido de uso.

1. Visão geral do módulo

O módulo financeiro gerencia o ciclo completo da gestão financeira corporativa, incluindo cadastro, planejamento, execução, conciliação bancária, governança e projeções futuras. Ele suporta contas a pagar e receber, liquidações, conciliações, auditoria e fechamento de períodos, além de cenários de fluxo de caixa e agenda de recebíveis.

2. Escopo e responsabilidades

• Cadastro de entidades financeiras: filiais, categorias, centros de custo, contas bancárias, meios de pagamento.
• Planejamento financeiro: títulos financeiros e suas parcelas.
• Execução financeira: liquidação e baixa real de parcelas.
• Conciliação bancária: importação e associação de extratos bancários.
• Governança: auditoria de ações e fechamento operacional de períodos.
• Projeções financeiras: cenários, fluxo projetado e agenda de recebíveis.
• Gestão de transferências entre contas.
• Gestão de cobranças e acordos.

3. Endpoints

FinanceAuditLogsController

| Método | Path | Auth | Descrição | Parâmetros/Query | Resposta | Erros Comuns | |--------|--------------------|------|-------------------------------|-------------------------------------------------------------------------------------------------|---------------------------|-------------------| | GET | /finance/audit-logs | Sim | Lista logs de auditoria financeira | Query: search, action, entity_table, actor_user_id, from, to, paginação | Lista paginada de logs | 401 Unauthorized |

FinanceBankAccountsController

| Método | Path | Auth | Descrição | Parâmetros/Body | Resposta | Erros Comuns | |--------|---------------------------|------|-------------------------|-------------------------------------------------------------------------------------------------|--------------------|----------------------| | GET | /finance/bank-accounts | Sim | Lista contas bancárias | - | Lista de contas | 401 Unauthorized | | POST | /finance/bank-accounts | Sim | Cria nova conta bancária| Body: { bank: string; branch?: string; account?: string; type: string; description?: string; initial_balance?: number } | Conta criada | 400 Validação | | PATCH | /finance/bank-accounts/:id | Sim | Atualiza conta bancária | Body: { bank?: string; branch?: string; account?: string; type?: string; description?: string; status?: 'active' | 'inactive' } | Conta atualizada | 400 Validação, 404 | | DELETE | /finance/bank-accounts/:id | Sim | Remove conta bancária | - | Confirmação | 404 Not Found |

FinanceCategoriesController

| Método | Path | Auth | Descrição | Parâmetros/Body | Resposta | Erros Comuns | |--------|---------------------------|------|---------------------------|-------------------------------------------------------------------------------------------------|--------------------|----------------------| | GET | /finance/categories | Sim | Lista categorias financeiras | - | Lista de categorias | 401 Unauthorized | | POST | /finance/categories | Sim | Cria categoria financeira | Body: { name: string; kind: string; parent_id?: number } | Categoria criada | 400 Validação | | PATCH | /finance/categories/:id | Sim | Atualiza categoria financeira | Body: { name?: string; kind?: string; parent_id?: number; status?: 'active' | 'inactive' } | Categoria atualizada | 400 Validação, 404 | | PATCH | /finance/categories/:id/move | Sim | Move categoria na hierarquia | Body: { parent_id?: number; position?: number } | Categoria movida | 400 Validação, 404 | | DELETE | /finance/categories/:id | Sim | Remove categoria financeira | - | Confirmação | 404 Not Found |

FinanceCollectionsController

| Método | Path | Auth | Descrição | Parâmetros/Body | Resposta | Erros Comuns | |--------|----------------------------------------------------|------|----------------------------------|-------------------------------------------------------------------------------------------------|------------------------|----------------------| | GET | /finance/accounts-receivable/collections-default | Sim | Obtém configurações padrão de cobrança | - | Configurações padrão | 401 Unauthorized | | POST | /finance/accounts-receivable/collections-default/:personId/send | Sim | Envia mensagem de cobrança para pessoa | Body: { message: string; subject?: string } | Confirmação de envio | 400 Validação, 404 | | POST | /finance/accounts-receivable/collections-default/:personId/agreements | Sim | Registra acordo de cobrança para pessoa | Body: { amount: number; installments: number; first_due_date: string; notes?: string } | Acordo registrado | 400 Validação, 404 |

FinanceCostCentersController

| Método | Path | Auth | Descrição | Parâmetros/Body | Resposta | Erros Comuns | |--------|---------------------------|------|------------------------|-------------------------------------------------------------------------------------------------|--------------------|----------------------| | GET | /finance/cost-centers | Sim | Lista centros de custo | - | Lista de centros | 401 Unauthorized | | POST | /finance/cost-centers | Sim | Cria centro de custo | Body: { name: string } | Centro criado | 400 Validação | | PATCH | /finance/cost-centers/:id | Sim | Atualiza centro de custo| Body: { name?: string; status?: 'active' | 'inactive' } | Centro atualizado | 400 Validação, 404 | | DELETE | /finance/cost-centers/:id | Sim | Remove centro de custo | - | Confirmação | 404 Not Found |

FinanceDataController

| Método | Path | Auth | Descrição | Parâmetros/Query | Resposta | Erros Comuns | |--------|-----------------------|------|-------------------------------|-------------------------------------------------------------------------------------------------|------------------------|----------------------| | GET | /finance/data | Sim | Obtém dados financeiros com filtros | Query: horizonte (dias), cenario (nome do cenário) | Dados financeiros | 401 Unauthorized | | PATCH | /finance/scenarios/:cenario | Sim | Atualiza configurações do cenário | Body: { atrasoMedio: number; taxaInadimplencia: number; crescimentoReceita: number; setAsDefault?: boolean } | Cenário atualizado | 400 Validação, 404 |

FinanceInstallmentsController

| Método | Path | Auth | Descrição | Parâmetros/Body/Query | Resposta | Erros Comuns | |--------|-------------------------------------------------------------|------|----------------------------------|-------------------------------------------------------------------------------------------------------|---------------------------|----------------------| | GET | /finance/accounts-payable/installments | Sim | Lista parcelas contas a pagar | Query: status, paginação | Lista paginada | 401 Unauthorized | | GET | /finance/accounts-payable/installments/:id | Sim | Detalha parcela contas a pagar | Path param: id | Detalhes da parcela | 404 Not Found | | GET | /finance/titles/:id/settlements-history | Sim | Histórico de liquidações do título| Path param: id | Histórico de liquidações | 404 Not Found | | POST | /finance/accounts-payable/installments | Sim | Cria título contas a pagar | Body: CreateFinancialTitleDto | Título criado | 400 Validação | | PATCH | /finance/accounts-payable/installments/:id | Sim | Atualiza título contas a pagar | Body: CreateFinancialTitleDto | Título atualizado | 400 Validação, 404 | | PATCH | /finance/accounts-payable/installments/:id/approve | Sim | Aprova título contas a pagar | - | Título aprovado | 404 Not Found | | PATCH | /finance/accounts-payable/installments/:id/reject | Sim | Rejeita título contas a pagar | Body: { reason?: string } | Título rejeitado | 400 Validação, 404 | | PATCH | /finance/accounts-payable/installments/:id/cancel | Sim | Cancela título contas a pagar | Body: { reason?: string } | Título cancelado | 400 Validação, 404 | | POST | /finance/accounts-payable/installments/:id/settlements | Sim | Registra liquidação parcela | Body: SettleInstallmentDto | Liquidação registrada | 400 Validação, 404 | | PATCH | /finance/accounts-payable/installments/:id/settlements/:settlementId/reverse | Sim | Estorna liquidação parcela | Body: { reason?: string; memo?: string } | Liquidação estornada | 400 Validação, 404 | | PATCH | /finance/settlements/:id/reverse | Sim | Estorna liquidação por id | Body: { reason?: string; memo?: string } | Liquidação estornada | 400 Validação, 404 | | DELETE | /finance/bank-reconciliations/:id | Sim | Desfaz conciliação bancária | - | Conciliação desfeita | 404 Not Found | | PATCH | /finance/accounts-payable/installments/:id/tags | Sim | Atualiza tags da parcela | Body: { tag_ids?: number[] } | Tags atualizadas | 400 Validação, 404 | | POST | /finance/accounts-payable/installments/extract-from-file | Sim | Extrai dados de título de arquivo | Multipart file + Body: { file_id?: number } | Dados extraídos | 400 Validação | | GET | /finance/accounts-receivable/installments | Sim | Lista parcelas contas a receber | Query: status, paginação | Lista paginada | 401 Unauthorized | | GET | /finance/accounts-receivable/installments/:id | Sim | Detalha parcela contas a receber | Path param: id | Detalhes da parcela | 404 Not Found | | POST | /finance/accounts-receivable/installments | Sim | Cria título contas a receber | Body: CreateFinancialTitleDto | Título criado | 400 Validação | | PATCH | /finance/accounts-receivable/installments/:id | Sim | Atualiza título contas a receber | Body: CreateFinancialTitleDto | Título atualizado | 400 Validação, 404 | | PATCH | /finance/accounts-receivable/installments/:id/approve | Sim | Aprova título contas a receber | - | Título aprovado | 404 Not Found | | PATCH | /finance/accounts-receivable/installments/:id/cancel | Sim | Cancela título contas a receber | Body: { reason?: string } | Título cancelado | 400 Validação, 404 | | POST | /finance/accounts-receivable/installments/:id/settlements | Sim | Registra liquidação parcela | Body: SettleInstallmentDto | Liquidação registrada | 400 Validação, 404 | | PATCH | /finance/accounts-receivable/installments/:id/settlements/:settlementId/reverse | Sim | Estorna liquidação parcela | Body: { reason?: string; memo?: string } | Liquidação estornada | 400 Validação, 404 | | PATCH | /finance/accounts-receivable/installments/:id/tags | Sim | Atualiza tags da parcela | Body: { tag_ids?: number[] } | Tags atualizadas | 400 Validação, 404 | | POST | /finance/tags | Sim | Cria tag financeira | Body: { name: string; color?: string } | Tag criada | 400 Validação | | POST | /finance/accounts-receivable/installments/extract-from-file | Sim | Extrai dados de título de arquivo | Multipart file + Body: { file_id?: number } | Dados extraídos | 400 Validação |

FinancePeriodCloseController

| Método | Path | Auth | Descrição | Parâmetros/Body | Resposta | Erros Comuns | |--------|-------------------|------|---------------------------|-------------------------------------------------------------------------------------------------|--------------------|----------------------| | GET | /finance/period-close | Sim | Lista fechamentos de períodos | Query: search, status, user, from, to, paginação | Lista paginada | 401 Unauthorized | | POST | /finance/period-close | Sim | Cria fechamento de período | Body: { period_start: string; period_end: string; notes?: string; status?: 'open' | 'closed' } | Fechamento criado | 400 Validação |

FinanceStatementsController

| Método | Path | Auth | Descrição | Parâmetros/Query/Body | Resposta | Erros Comuns | |--------|-------------------------------|------|-------------------------------|-------------------------------------------------------------------------------------------------------|------------------------|----------------------| | GET | /finance/statements | Sim | Lista extratos bancários | Query: bank_account_id, search | Lista de extratos | 400 BadRequest, 401 | | GET | /finance/bank-reconciliation/summary | Sim | Resumo da conciliação bancária | Query: bank_account_id (obrigatório) | Resumo da conciliação | 400 BadRequest, 401 | | POST | /finance/bank-reconciliations | Sim | Cria conciliação bancária | Body: { title_id: number; installment_id: number; bank_statement_line_id: number; payment_channel?: string; description?: string } | Conciliação criada | 400 Validação, 401 | | GET | /finance/statements/export | Sim | Exporta extratos em CSV | Query: bank_account_id (obrigatório), search | CSV para download | 400 BadRequest, 401 | | POST | /finance/statements/import | Sim | Importa extrato bancário | Multipart file + Body: bank_account_id (obrigatório) | Importação realizada | 400 BadRequest, 401 | | POST | /finance/statements/adjustments | Sim | Cria ajuste em extrato bancário | Body: { bank_account_id: number; amount: number; date?: string; type: string; description?: string } | Ajuste criado | 400 Validação, 401 |

FinanceTransfersController

| Método | Path | Auth | Descrição | Parâmetros/Query/Body | Resposta | Erros Comuns | |--------|-------------------|------|----------------------------|-------------------------------------------------------------------------------------------------------|------------------------|----------------------| | GET | /finance/transfers | Sim | Lista transferências | Query: search, bank_account_id | Lista de transferências | 401 Unauthorized | | POST | /finance/transfers | Sim | Cria transferência entre contas | Body: { source_account_id: number; destination_account_id: number; date: string; amount: number; description?: string } | Transferência criada | 400 Validação |

4. Regras de autenticação e autorização

• Todos os endpoints requerem autenticação via token válido.
• O decorator @Role() indica que o acesso é restrito a usuários autenticados.
• Controle de permissões específicas deve ser implementado na camada de serviço conforme regras de negócio.
• Usuários são identificados via decorator @User() para rastreabilidade.

5. Estruturas de request/response

CreateBankAccountDto

{
  bank: string; // obrigatório
  branch?: string;
  account?: string;
  type: string; // obrigatório
  description?: string;
  initial_balance?: number; // >= 0
}

UpdateBankAccountDto

{
  bank?: string;
  branch?: string;
  account?: string;
  type?: string;
  description?: string;
  status?: 'active' | 'inactive';
}

CreateFinancialTitleDto

{
  document_number: string; // obrigatório, não vazio
  person_id: number; // obrigatório
  competence_date?: string (ISO date);
  issue_date?: string (ISO date);
  due_date: string (ISO date); // obrigatório
  total_amount: number; // obrigatório, >= 0.01
  finance_category_id?: number;
  cost_center_id?: number;
  payment_channel?: string;
  description?: string;
  installments?: [
    {
      installment_number?: number; // >= 1
      due_date: string (ISO date);
      amount: number; // >= 0.01
    }
  ];
  attachment_file_ids?: number[];
}

SettleInstallmentDto

{
  installment_id: number; // obrigatório
  amount: number; // obrigatório, >= 0.01
  settled_at?: string (ISO date);
  bank_account_id?: number;
  bank_statement_line_id?: number;
  payment_channel?: string;
  discount?: number; // >= 0
  interest?: number; // >= 0
  penalty?: number; // >= 0
  description?: string;
}

RejectTitleDto

{
  reason?: string;
}

ReverseSettlementDto

{
  reason?: string;
  memo?: string;
}

CreateBankReconciliationDto

{
  title_id: number; // obrigatório
  installment_id: number; // obrigatório
  bank_statement_line_id: number; // obrigatório
  payment_channel?: string;
  description?: string;
}

CreateBankStatementAdjustmentDto

{
  bank_account_id: number; // obrigatório
  amount: number; // obrigatório, >= 0.01
  date?: string (ISO date);
  type: string; // obrigatório
  description?: string;
}

CreateCostCenterDto

{
  name: string; // obrigatório
}

UpdateCostCenterDto

{
  name?: string;
  status?: 'active' | 'inactive';
}

CreateFinanceCategoryDto

{
  name: string; // obrigatório
  kind: string; // obrigatório
  parent_id?: number; // opcional
}

UpdateFinanceCategoryDto

{
  name?: string;
  kind?: string;
  parent_id?: number;
  status?: 'active' | 'inactive';
}

MoveFinanceCategoryDto

{
  parent_id?: number;
  position?: number;
}

SendCollectionDto

{
  message: string; // obrigatório, min 5 e max 2000 caracteres
  subject?: string; // opcional, max 255 caracteres
}

RegisterCollectionAgreementDto

{
  amount: number; // obrigatório, min 0.01
  installments: number; // obrigatório, entre 1 e 120
  first_due_date: string; // obrigatório, ISO date
  notes?: string; // opcional
}

UpdateInstallmentTagsDto

{
  tag_ids?: number[]; // opcional, array de números únicos e >= 1
}

CreatePeriodCloseDto

{
  period_start: string; // obrigatório, ISO date
  period_end: string; // obrigatório, ISO date
  notes?: string; // opcional
  status?: 'open' | 'closed'; // opcional
}

ExtractFinancialTitleFromFileDto

{
  file_id?: number; // opcional
}

CreateTransferDto

{
  source_account_id: number; // obrigatório
  destination_account_id: number; // obrigatório
  date: string; // obrigatório
  amount: number; // obrigatório, >= 0.01
  description?: string;
}

CreateFinanceTagDto

{
  name: string; // obrigatório, string não vazia
  color?: string; // opcional, cor hexadecimal válida
}

UpdateFinanceScenarioSettingsDto

{
  atrasoMedio: number;
  taxaInadimplencia: number;
  crescimentoReceita: number;
  setAsDefault?: boolean;
}

6. Erros comuns

• 400 Bad Request: dados inválidos ou ausentes conforme validações dos DTOs.
• 401 Unauthorized: ausência ou invalidez do token de autenticação.
• 404 Not Found: recurso não encontrado (ex.: id inválido).
• 409 Conflict: tentativas de duplicidade em tabelas com unicidade (ex.: tags, rateios).
• 422 Unprocessable Entity: violações de regras de negócio (ex.: saldo insuficiente, período fechado).

7. Banco de dados (tabelas YAML)

company_profile

• Finalidade: Configurações globais financeiras (status, moeda, timezone).
• Colunas:
  • id (PK)
  • code (string, único, não nulo)
  • status (enum: active, inactive, default active)
  • default_currency (string, não nulo, ex: BRL)
  • timezone (string, não nulo, ex: America/Sao_Paulo)
  • created_at, updated_at (timestamps)
• Integridade: PK em id
• Indices: índice único em code
• Enums: status

finance_category

• Finalidade: Categorias financeiras hierárquicas.
• Colunas:
  • id (PK)
  • parent_id (FK para self, nullable)
  • code (string)
  • name (string)
  • kind (enum: revenue, expense, transfer, adjustment, other)
  • status (enum: active, inactive, default active)
  • created_at, updated_at
• Integridade: FK para parent_id
• Indices: índice em code
• Enums: kind, status

cost_center

• Finalidade: Centros de custo para rateio.
• Colunas:
  • id (PK)
  • code (string)
  • name (string)
  • status (enum: active, inactive, default active)
  • created_at, updated_at
• Integridade: PK em id
• Indices: índice em code
• Enums: status

payment_method

• Finalidade: Meios de pagamento configuráveis.
• Colunas:
  • id (PK)
  • code (string)
  • name (string)
  • type (enum: pix, boleto, ted, doc, card, cash, other)
  • status (enum: active, inactive, default active)
  • created_at, updated_at
• Integridade: PK em id
• Indices: índice em code
• Enums: type, status

bank_account

• Finalidade: Contas bancárias e caixas.
• Colunas:
  • id (PK)
  • code (string)
  • name (string)
  • bank_name (string, nullable)
  • bank_code (string, nullable)
  • agency (string, nullable)
  • account_number (string, nullable)
  • account_type (enum: checking, savings, investment, cash, other)
  • status (enum: active, inactive, default active)
  • created_at, updated_at
• Integridade: PK em id
• Indices: índice em code
• Enums: account_type, status

financial_title

• Finalidade: Documento pai de contas a pagar/receber.
• Colunas:
  • id (PK)
  • person_id (FK para person.id)
  • title_type (enum: payable, receivable)
  • status (enum: draft, open, partial, settled, canceled, overdue, default draft)
  • document_number (string, nullable)
  • description (string, nullable)
  • competence_date (date, nullable)
  • issue_date (date, nullable)
  • total_amount_cents (integer)
  • finance_category_id (FK para finance_category.id, nullable)
  • created_by_user_id (FK para user.id, nullable)
  • created_at, updated_at
• Integridade: FK para person, finance_category, user
• Indices: índice em document_number
• Enums: title_type, status

financial_installment

• Finalidade: Parcelas de títulos financeiros.
• Colunas:
  • id (PK)
  • title_id (FK para financial_title.id)
  • installment_number (integer)
  • competence_date (date)
  • due_date (date)
  • amount_cents (integer)
  • open_amount_cents (integer)
  • status (enum: open, partial, settled, canceled, overdue, default open)
  • notes (string, nullable)
  • created_at, updated_at
• Integridade: FK para financial_title
• Indices: índice composto em title_id, installment_number
• Enums: status

settlement

• Finalidade: Evento financeiro real (pagamento, recebimento, transferência, ajuste).
• Colunas:
  • id (PK)
  • person_id (FK para person.id, nullable)
  • bank_account_id (FK para bank_account.id, nullable)
  • payment_method_id (FK para payment_method.id, nullable)
  • settlement_type (enum: payable, receivable, transfer, adjustment)
  • status (enum: pending, confirmed, reversed, default pending)
  • settled_at (datetime)
  • amount_cents (integer)
  • description (string, nullable)
  • external_reference (string, nullable)
  • created_by_user_id (FK para user.id, nullable)
  • created_at, updated_at
• Integridade: FK para person, bank_account, payment_method, user
• Indices: índice em settled_at
• Enums: settlement_type, status

bank_statement

• Finalidade: Lote de importação de extrato bancário.
• Colunas:
  • id (PK)
  • bank_account_id (FK para bank_account.id)
  • source_type (enum: ofx, csv, manual)
  • idempotency_key (string, nullable)
  • period_start (date, nullable)
  • period_end (date, nullable)
  • imported_at (datetime)
  • imported_by_user_id (FK para user.id, nullable)
  • created_at, updated_at
• Integridade: FK para bank_account, user
• Enums: source_type

bank_statement_line

• Finalidade: Transações individuais do extrato.
• Colunas:
  • id (PK)
  • bank_statement_id (FK para bank_statement.id)
  • bank_account_id (FK para bank_account.id)
  • external_id (string, nullable)
  • posted_date (date)
  • amount_cents (integer)
  • description (string)
  • status (enum: imported, pending, reconciled, reversed, adjusted, default imported)
  • dedupe_key (string, único)
  • created_at, updated_at
• Integridade: FK para bank_statement, bank_account
• Indices: índice único em dedupe_key
• Enums: status

bank_reconciliation

• Finalidade: Associação entre linha de extrato e settlement.
• Colunas:
  • id (PK)
  • bank_statement_line_id (FK para bank_statement_line.id, único)
  • settlement_id (FK para settlement.id, único)
  • status (enum: pending, reconciled, reversed, adjusted, default pending)
  • matched_at (datetime, nullable)
  • matched_by_user_id (FK para user.id, nullable)
  • created_at, updated_at
• Integridade: FK para bank_statement_line, settlement, user
• Indices: unicidade em bank_statement_line_id e settlement_id
• Enums: status

audit_log

• Finalidade: Registro de auditoria funcional.
• Colunas:
  • id (PK)
  • actor_user_id (FK para user.id, nullable)
  • action (string)
  • entity_table (string)
  • entity_id (string)
  • summary (string, nullable)
  • before_data (json, nullable)
  • after_data (json, nullable)
  • ip_address (string, nullable)
  • created_at, updated_at
• Integridade: FK para user

period_close

• Finalidade: Controle de fechamento operacional de períodos.
• Colunas:
  • id (PK)
  • period_start (date)
  • period_end (date)
  • status (enum: open, closed, default open)
  • closed_at (datetime, nullable)
  • closed_by_user_id (FK para user.id, nullable)
  • notes (string, nullable)
  • created_at, updated_at
• Integridade: FK para user
• Enums: status

forecast_scenario

• Finalidade: Cenários de planejamento financeiro.
• Colunas:
  • id (PK)
  • name (string)
  • status (enum: active, inactive, default active)
  • is_default (boolean, default false)
  • created_at, updated_at
• Enums: status

cashflow_projection

• Finalidade: Projeções de fluxo de caixa.
• Colunas:
  • id (PK)
  • scenario_id (FK para forecast_scenario.id)
  • projection_date (date)
  • projection_type (enum: inflow, outflow, net)
  • amount_cents (integer)
  • notes (string, nullable)
  • created_at, updated_at
• Enums: projection_type

receivable_schedule

• Finalidade: Agenda de recebíveis previstos.
• Colunas:
  • id (PK)
  • scenario_id (FK para forecast_scenario.id)
  • person_id (FK para person.id, nullable)
  • expected_date (date)
  • amount_cents (integer)
  • description (string, nullable)
  • created_at, updated_at

8. Regras de negócio relevantes

• Valores monetários são armazenados em centavos para evitar erros de precisão.
• Datas de competência e vencimento são separadas para análises corretas.
• Histórico financeiro é imutável; correções são feitas via estorno ou ajuste, nunca exclusão.
• Saldo aberto de parcelas (open_amount_cents) deve ser >= 0 e <= valor original.
• Rateios e alocações devem respeitar unicidade e somatórios coerentes.
• Períodos fechados bloqueiam operações diretas, permitindo apenas estornos sob regras.
• Conciliações bancárias são 1:1 entre linha de extrato e settlement.
• Auditoria é obrigatória para alterações relevantes.
• Importação de extratos deve usar chave de deduplicação estável para evitar duplicidade.

9. Guia rápido de uso (exemplos)

Criar conta bancária

POST /finance/bank-accounts
Authorization: Bearer <token>
Content-Type: application/json

{
  "bank": "Banco do Brasil",
  "branch": "1234",
  "account": "56789-0",
  "type": "checking",
  "description": "Conta principal",
  "initial_balance": 100000
}

Criar título contas a pagar com parcelas

POST /finance/accounts-payable/installments
Authorization: Bearer <token>
Content-Type: application/json

{
  "document_number": "FAT-2024-001",
  "person_id": 123,
  "due_date": "2024-07-31",
  "total_amount": 1500.00,
  "installments": [
    { "installment_number": 1, "due_date": "2024-07-31", "amount": 500.00 },
    { "installment_number": 2, "due_date": "2024-08-31", "amount": 500.00 },
    { "installment_number": 3, "due_date": "2024-09-30", "amount": 500.00 }
  ]
}

Registrar liquidação de parcela

POST /finance/accounts-payable/installments/456/settlements
Authorization: Bearer <token>
Content-Type: application/json

{
  "installment_id": 456,
  "amount": 500.00,
  "settled_at": "2024-07-31T10:00:00Z",
  "bank_account_id": 10,
  "payment_channel": "TED",
  "discount": 0,
  "interest": 0,
  "penalty": 0,
  "description": "Pagamento via TED"
}

Importar extrato bancário

POST /finance/statements/import
Authorization: Bearer <token>
Content-Type: multipart/form-data

Form-data:
- file: arquivo OFX ou CSV
- bank_account_id: 10

Criar conciliação bancária

POST /finance/bank-reconciliations
Authorization: Bearer <token>
Content-Type: application/json

{
  "title_id": 123,
  "installment_id": 456,
  "bank_statement_line_id": 789,
  "payment_channel": "PIX",
  "description": "Conciliação automática"
}

Estornar liquidação

PATCH /finance/accounts-payable/installments/456/settlements/789/reverse
Authorization: Bearer <token>
Content-Type: application/json

{
  "reason": "Pagamento duplicado",
  "memo": "Estorno realizado em 2024-08-01"
}

Este README foi atualizado para refletir a implementação atual do módulo financeiro @hed-hog/finance conforme código fonte e DTOs disponíveis.