Referência técnica do financeiro

Domínios Finance e Tax da pepper-api; telas em pepper-front/src/app/finance. Todas as rotas exigem x-access-token e o header requesting (perfil ativo), e usam o business = id do ProfileBusiness.

Entidades

Coleção	Campos principais
FinanceCategory	business, key (padrão), name, kind (income/expense), dreGroup, isDefault, active, order
FinanceEntry	kind, category, description, amount, competenceDate, dueDate, paidAt, status (pending/paid/canceled), source (manual/recurring/payroll/tax/vacation), sourceRef, counterparty, recurrenceGroup
FiscalProfile	taxRegime, activity, simplesAnnex, fatorR, cnae, issRate, issDueDay, icmsRate, ratFap, activityStartDate, openingBalance, openingDate
TaxObligation	tax, competence (AAAA-MM), dueDate, base, rate, estimatedAmount, amount (guia oficial), status (open/paid/canceled), source (apuration/payroll/manual), memory

Lançamentos automáticos são idempotentes por source + sourceRef: fechar a folha de novo não duplica.

Rotas

Método e rota	Uso
GET /finance/categories	Lista (cria as padrão se faltarem); includeInactive
POST /finance/categories · PUT /finance/categories/:id	Criar e editar
GET /finance/entries	Filtros kind, status (inclui overdue), category, from, to, dateField, search, source; devolve totals do filtro
POST /finance/entries	Cria; repeat { frequency, count } gera as parcelas
PUT /finance/entries/:id	Edita; applyToNext estende às próximas parcelas
PUT /finance/entries/:id/pay · /unpay · /cancel · DELETE /finance/entries/:id	Baixa, desfazer, cancelar, excluir
GET /finance/reports/summary	Painel (month)
GET /finance/reports/cash-flow	from, to, granularity (day/week/month)
GET /finance/reports/dre	from, to; inclui previous e unapuratedCompetences
GET · PUT /tax/profile	Perfil fiscal
POST /tax/apuration	competence, save (false = simulação)
GET /tax/obligations · PUT /tax/obligations/:id · /pay · /cancel	Guias

Permissões

• RBAC: recursos Finance e Tax.
• ProfileBusiness e ProfileAdmin: acesso total à própria empresa.
• ProfileCollaborator:
  • lê a empresa dele;
  • grava somente com papel Admin (isAdminCollaborator, na policy);
  • o RBAC do colaborador tem teto delete e a restrição fica na policy.

Regras de cálculo

• Fuso: datas no fuso de Brasília (−03:00). A competência "2026-10" vai de 01/10 00:00 até 01/11 00:00.
• DRE (statements.buildDre):
  • soma os valores assinados por grupo: receita +, despesa −;
  • a receita bruta inclui os pedidos (billedValue pela saleDate);
  • as guias em aberto entram na competência, pela categoria do tributo.
• Fluxo (statements.buildCashFlow):
  • realizado = pagos e pedidos pagos;
  • previsto = de hoje em diante;
  • vencidos ficam à parte.
• Tributos: utils/tax, com tabelas por ano. Ano sem tabela usa a mais recente e avisa TABLE_YEAR_FALLBACK.