API — Contabilidade

Base: GET /t/:slug/accounting/...

Todos os endpoints requerem autenticação JWT (manage_accounting permission — Admin ou Superadmin).

---

Plano de Contas

GET /t/:slug/accounting/chart

Lista todas as contas do plano (defaults do sistema + contas do tenant).

Resposta: ChartAccount[]

[
  {
    "_id": "...",
    "code": "1.1.1.01",
    "name": "Caixa",
    "nature": "ativo",
    "type": "analitica",
    "normalBalance": "debit",
    "parent": null,
    "dreGroup": null,
    "tenant": null,
    "active": true
  }
]

Campos nature: ativo | passivo | receita | despesa | custo | patrimonio_liquido

Campos type: sintetica | analitica

Campos normalBalance: debit | credit

---

POST /t/:slug/accounting/chart

Cria nova conta no plano do tenant.

Body:

{
  "code": "1.1.2.05",
  "name": "Contas a Receber – Vouchers",
  "nature": "ativo",
  "type": "analitica",
  "normalBalance": "debit",
  "parent": "optional-parent-id",
  "dreGroup": null
}

---

DELETE /t/:slug/accounting/chart/:id

Desativa uma conta do tenant (soft delete — active: false). Contas do sistema (tenant: null) não podem ser desativadas.

---

POST /t/:slug/accounting/chart/seed/defaults

Popula o plano de contas com os defaults do sistema brasileiro para restaurantes (~40 contas). Contas já existentes não são duplicadas.

Permissão: Superadmin only.

---

Diário de Lançamentos

GET /t/:slug/accounting/journal

Lista lançamentos paginados.

Query params:

Param	Tipo	Descrição
page	number	Página (default: 1)
limit	number	Por página (default: 20)
status	string	Filtrar por `draft

Resposta: JournalEntry[]

[
  {
    "_id": "...",
    "entryNumber": "JE-2026-00042",
    "competenceDate": "2026-04-07T00:00:00Z",
    "description": "Venda Pedido #20260407-0012",
    "status": "posted",
    "totalAmount": 150.00,
    "lines": [
      { "accountId": "...", "accountCode": "1.1.1.01", "accountName": "Caixa", "debit": 150.00, "credit": 0, "memo": null },
      { "accountId": "...", "accountCode": "3.1.1.01", "accountName": "Receita de Vendas", "debit": 0, "credit": 150.00, "memo": null }
    ]
  }
]

---

POST /t/:slug/accounting/journal

Cria lançamento manual em estado draft.

Body:

{
  "competenceDate": "2026-04-07",
  "description": "Ajuste manual de estoque",
  "lines": [
    { "accountId": "...", "debit": 500.00, "credit": 0, "memo": "Perda de insumo" },
    { "accountId": "...", "debit": 0, "credit": 500.00, "memo": null }
  ]
}

Validação: Soma de débitos deve ser igual à soma de créditos.

---

POST /t/:slug/accounting/journal/:id/post

Lança um rascunho (draft → posted). Após postado, o lançamento não pode ser editado.

---

POST /t/:slug/accounting/journal/:id/reverse

Estorna um lançamento postado — cria contra-lançamento automático com o prefixo [ESTORNO] na descrição.

Body:

{ "reason": "Estorno manual" }

---

Razão Geral & Balancete

GET /t/:slug/accounting/ledger/balancete

Balancete de verificação para um período.

Query params:

Param	Tipo	Obrigatório
year	number	✓
month	number	✓

Resposta: BalanceteRow[]

[
  {
    "accountId": "...",
    "accountCode": "1.1.1.01",
    "accountName": "Caixa",
    "nature": "ativo",
    "totalDebit": 5000.00,
    "totalCredit": 2000.00,
    "balance": 3000.00
  }
]

---

GET /t/:slug/accounting/ledger/razao

Razão de uma conta analítica (histórico de movimentos com saldo acumulado).

Query params:

Param	Tipo	Descrição
accountId	string	ID da conta analítica
startDate	string	Data inicial (YYYY-MM-DD)
endDate	string	Data final (YYYY-MM-DD)

Resposta: RazaoLine[]

[
  {
    "entryNumber": "JE-2026-00042",
    "competenceDate": "2026-04-07T00:00:00Z",
    "description": "Venda #0012",
    "debit": 150.00,
    "credit": 0,
    "runningBalance": 3150.00
  }
]

---

GET /t/:slug/accounting/ledger/periods

Lista todos os períodos mensais com lançamentos.

Resposta: PeriodClosing[]

---

POST /t/:slug/accounting/ledger/close

Fecha uma competência — congela lançamentos e captura snapshot do balancete.

Body: { "year": 2026, "month": 3 }

---

POST /t/:slug/accounting/ledger/reopen

Reabre um período fechado para correções.

Body: { "year": 2026, "month": 3 }

---

Contas a Receber

GET /t/:slug/accounting/receivables

Lista contas a receber com filtros opcionais.

Query params:

Param	Tipo	Valores
status	string	`open

---

GET /t/:slug/accounting/receivables/aging

Aging report — agrupa recebíveis em buckets de vencimento.

Resposta:

{
  "grandTotal": 4500.00,
  "buckets": [
    { "label": "Vencidos >90d", "total": 500.00, "count": 2 },
    { "label": "Vencidos 60-90d", "total": 800.00, "count": 3 },
    { "label": "Vencidos 30-60d", "total": 1200.00, "count": 5 },
    { "label": "Vencidos até 30d", "total": 700.00, "count": 4 },
    { "label": "A Vencer", "total": 1300.00, "count": 6 }
  ]
}

---

POST /t/:slug/accounting/receivables/:id/settle

Registra recebimento (total ou parcial).

Body:

{ "amount": 150.00, "paymentMethod": "cash" }

---

POST /t/:slug/accounting/receivables/:id/write-off

Baixa um recebível (perdas, acordos).

Body:

{ "reason": "Baixa manual — acordo" }

---

Contas Bancárias

GET /t/:slug/accounting/bank

Lista contas bancárias cadastradas.

---

POST /t/:slug/accounting/bank

Cadastra nova conta bancária.

Body:

{
  "name": "Conta Corrente Itaú",
  "bank": "Itaú",
  "agency": "1234",
  "account": "56789-0",
  "type": "checking"
}

---

GET /t/:slug/accounting/bank/:id/statement

Lista linhas do extrato importado para uma conta.

Query: ?status=unmatched|matched|ignored

---

POST /t/:slug/accounting/bank/:id/import

Importa extrato OFX ou CSV.

Body: multipart/form-data com campo file.

---

POST /t/:slug/accounting/bank/:id/auto-match

Executa conciliação automática: pareia linhas do extrato com lançamentos por valor + janela de 3 dias.

---

Tipos TypeScript

Ver frontend-react/src/types/index.ts:

• ChartAccount, AccountNature, AccountType, BalanceSide
• JournalEntry, JournalEntryLine, JournalEntryStatus
• AccountsReceivable, ReceivableStatus, AgingReport, AgingBucket
• BankAccount, BankStatementLine
• PeriodClosing, BalanceteRow, RazaoLine