Relatórios

Visao geral

Rotas para obter indicadores e tabelas do dashboard, com suporte a exportacao CSV/PDF.

• Base: https://api.ascendteam.cloud/api/v1/reports
• Autenticacao: requer sessao/credenciais validas do Better Auth (ver /docs/api/auth).

Conceitos

• mode:
  • TRANSACTIONS_ONLY: baseado apenas em lancamentos (Transaction).
  • FULL: inclui dados de faturamento, alocacoes e clientes.
• Datas:
  • from e to aceitam ISO 8601.
  • Se omitidos: from = primeiro dia do mes atual; to = agora.

Endpoints

GET /summary

Resumo financeiro do periodo.

Query

• mode (TRANSACTIONS_ONLY | FULL, opcional, default TRANSACTIONS_ONLY)
• from (date ISO 8601, opcional)
• to (date ISO 8601, opcional)

Resposta 200 (TRANSACTIONS_ONLY)

• from, to
• incomeTotal
• expenseTotal
• netTotal

Resposta 200 (FULL)

• Todos os campos do modo transactions-only, mais:
• receivedAllocatedTotal
• billedTotal
• openBalanceTotal
• unallocatedReceivedTotal

Respostas

• 200: resumo calculado
• 400: intervalo de datas invalido

GET /time-series

Serie temporal de recebimentos e gastos.

Query

• mode (TRANSACTIONS_ONLY | FULL, opcional, default TRANSACTIONS_ONLY)
• granularity (day | week | month, opcional, default month)
• from (date ISO 8601, opcional)
• to (date ISO 8601, opcional)

Resposta 200 Array de pontos:

• period (date)
• income
• expense
• net

Respostas

• 200: serie calculada
• 400: intervalo de datas invalido

GET /top-categories

Top categorias por valor.

Query

• type (INCOME | EXPENSE, obrigatorio)
• from (date ISO 8601, opcional)
• to (date ISO 8601, opcional)

Resposta 200 Array de itens:

• categoryId
• categoryName
• total

GET /top-clients

Top clientes por recebimento.

Query

• from (date ISO 8601, opcional)
• to (date ISO 8601, opcional)

Resposta 200 Array de itens:

• debtorId
• debtorName
• total

GET /billed-by-region

Faturamento por cidade/UF.

Query

• from (date ISO 8601, opcional)
• to (date ISO 8601, opcional)

Resposta 200 Array de itens:

• city
• state
• total

GET /received-by-region

Recebido por cidade/UF.

Query

• from (date ISO 8601, opcional)
• to (date ISO 8601, opcional)

Resposta 200 Array de itens:

• city
• state
• total

GET /received-by-service

Recebido por tipo de servico.

Query

• from (date ISO 8601, opcional)
• to (date ISO 8601, opcional)

Resposta 200 Array de itens:

• serviceCategoryId
• serviceCategoryName
• total

GET /export

Exporta relatorio CSV ou PDF.

Query

• mode (TRANSACTIONS_ONLY | FULL, opcional, default TRANSACTIONS_ONLY)
• format (csv | pdf, opcional, default csv)
• sections (summary,timeSeries,topCategories,topClients,billedByRegion,receivedByRegion,receivedByService, opcional)
• from (date ISO 8601, opcional)
• to (date ISO 8601, opcional)

Resposta 200

• Buffer do arquivo
• Content-Type: text/csv ou application/pdf
• Content-Disposition: attachment; filename="relatorio-..."

Respostas

• 200: relatorio exportado
• 400: intervalo de datas invalido

Observacoes

• mode afeta diretamente /summary e /export.
• Top clientes, faturamento e recebido por servico dependem de alocacoes e faturamento (modo PJ).