Dashboard

Endpoints read-only da WebApiAlcance que produzem as agregações e indicadores consumidos pelo dashboard do frontend do Hub Alcance. Reúnem KPIs gerais, série temporal de movimentação, lançamentos por status, resumo de importações, saldos por conta e grupo, resumo e ranking de clientes, o monitoramento mensal do ciclo de importação (com exportação em CSV/XLSX) e o Mapa do Mês (pendências do pipeline por cliente).

Todos os cálculos são agregações ORG-WIDE (toda a organização), com filtro opcional por cliente. Nenhum endpoint escreve dados.

Base path

/api/v1/dashboard

Escopos necessários

• dashboard:read - todas as rotas de agregação e a exportação

Como o domínio é read-only, na prática apenas o escopo dashboard:read é exigido (todas as rotas são GET). O escopo dashboard:write existe por convenção (recurso dashboard + ação de escrita), mas não há rotas de escrita neste domínio.

Endpoints

GET /dashboard/kpis

KPIs gerais do período, com valores do período anterior (para variação) e sparklines diários.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

Envelope com data = KpisData.

{
  "success": true,
  "message": "KPIs gerados com sucesso",
  "data": {
    "total_movimentado": 1250340.75,
    "total_movimentado_anterior": 1180200.10,
    "qtd_lancamentos": 8421,
    "qtd_lancamentos_anterior": 7930,
    "pct_regra_pendente": 4.2,
    "pct_erro": 1.1,
    "clientes_ativos": 312,
    "clientes_ativos_anterior": 305,
    "sparkline_movimentado": [40100.0, 38220.5, 51230.0],
    "sparkline_lancamentos": [280, 265, 340]
  }
}

Escopo: dashboard:read

GET /dashboard/movimentacao-diaria

Série temporal diária de débito, crédito e quantidade de lançamentos no período.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

Envelope com data = MovimentacaoDiariaData.

{
  "success": true,
  "message": "Movimentacao diaria gerada com sucesso",
  "data": {
    "serie": [
      { "data": "2026-06-01", "debito": 40100.0, "credito": 39800.0, "qtd": 280 },
      { "data": "2026-06-02", "debito": 38220.5, "credito": 38220.5, "qtd": 265 }
    ]
  }
}

Escopo: dashboard:read

GET /dashboard/lancamentos-status

Lançamentos agrupados por status e ranking das contas mais movimentadas (top contas).

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

Envelope com data = LancamentosStatusData.

{
  "success": true,
  "message": "Lancamentos por status gerados com sucesso",
  "data": {
    "por_status": [
      { "status": "conciliado", "qtd": 6100, "valor": 980200.0 },
      { "status": "pendente", "qtd": 340, "valor": 51230.0 }
    ],
    "top_contas": [
      {
        "id_conta": 1201,
        "codigo_dominio": "1.1.01.001",
        "descricao": "Caixa Geral",
        "tipo": "D",
        "qtd": 1200,
        "valor": 340500.0
      }
    ]
  }
}

Escopo: dashboard:read

GET /dashboard/importacoes-resumo

KPIs de importação, quebra por tipo de arquivo e histórico recente de importações.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

Envelope com data = ImportacoesResumoData.

{
  "success": true,
  "message": "Resumo de importacoes gerado com sucesso",
  "data": {
    "kpis": {
      "total": 128,
      "pct_sucesso": 96.1,
      "registros_processados": 41230,
      "pendentes": 5
    },
    "por_tipo": [
      { "tipo": "extrato_bancario", "qtd": 80, "ultimo_status": "concluido", "ultima_data": "2026-06-28" }
    ],
    "historico_recente": [
      {
        "id": 5521,
        "tipo": "extrato_bancario",
        "status": "concluido",
        "qtd_lancamentos_criados": 320,
        "data_hora_criacao": "2026-06-28T14:20:00",
        "cliente_nome": "ACME SERVICOS LTDA"
      }
    ]
  }
}

Escopo: dashboard:read

GET /dashboard/saldos

Saldos agregados por grupo, maiores contas por saldo e contas sem movimento no período.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

Envelope com data = SaldosData.

{
  "success": true,
  "message": "Saldos gerados com sucesso",
  "data": {
    "por_grupo": [
      { "grupo": "Ativo Circulante", "saldo": 540200.0 }
    ],
    "maiores_contas": [
      { "id_conta": 1201, "codigo_dominio": "1.1.01.001", "descricao": "Caixa Geral", "saldo": 120400.0 }
    ],
    "contas_sem_movimento": [
      { "id_conta": 3105, "codigo_dominio": "3.1.05.000", "descricao": "Despesas Diversas" }
    ]
  }
}

Escopo: dashboard:read

GET /dashboard/clientes-resumo

Resumo e ranking de clientes: KPIs de clientes, ranking por valor movimentado e concentração dos top 5.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

Envelope com data = ClientesResumoData.

{
  "success": true,
  "message": "Resumo de clientes gerado com sucesso",
  "data": {
    "kpis": { "ativos": 312, "novos": 0, "sem_movimento": 18 },
    "ranking": [
      { "id_cliente": 1234, "nome": "ACME SERVICOS LTDA", "valor": 340500.0, "qtd": 1200 }
    ],
    "concentracao_top5": [
      { "id_cliente": 1234, "nome": "ACME SERVICOS LTDA", "percentual": 27.2, "valor": 340500.0 }
    ]
  }
}

Escopo: dashboard:read

GET /dashboard/monitoramento-mensal

Painel mensal do ciclo de importação por cliente (Relatório → Monitoramento). Os três status de cliente (concluido, pendente, sem_movimento) particionam o total de clientes ativos. Retorna resumo, comparativo com o mês anterior, lista de clientes e o breakdown opcional por categoria (lancamentos, regras, contas).

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

Envelope com data = MonitoramentoMensalData.

{
  "success": true,
  "message": "Monitoramento mensal gerado com sucesso",
  "data": {
    "ano": 2026,
    "mes": 6,
    "resumo": {
      "total_clientes": 312,
      "bancos_cadastrados": 540,
      "importacoes_concluidas": 280,
      "importacoes_pendentes": 22,
      "importacoes_com_erro": 4,
      "total_lancamentos": 8421,
      "total_atualizados": 0,
      "total_ignorados": 0,
      "clientes_concluidos": 260,
      "clientes_pendentes": 34,
      "clientes_sem_movimento": 18,
      "pct_concluidos": 83.3
    },
    "comparativo_mes_anterior": {
      "clientes_concluidos": 251,
      "pct_concluidos": 81.0,
      "total_lancamentos": 7930,
      "importacoes_concluidas": 265
    },
    "clientes": [
      {
        "id_cliente": 1234,
        "nome": "ACME SERVICOS LTDA",
        "status": "concluido",
        "qtd_bancos": 2,
        "qtd_importacoes": 8,
        "qtd_importacoes_erro": 0,
        "qtd_lancamentos": 320,
        "qtd_atualizados": 0,
        "qtd_ignorados": 0,
        "ultimo_arquivo": "extrato_062026.ofx",
        "ultima_data": "2026-06-28T14:20:00",
        "dias_sem_importar": 5
      }
    ],
    "por_categoria": null
  }
}

Escopo: dashboard:read

GET /dashboard/monitoramento-mensal/export

Exporta o monitoramento mensal como arquivo CSV ou XLSX. Aceita os mesmos parâmetros de GET /dashboard/monitoramento-mensal, mais formato e categoria. A resposta é um arquivo binário (Content-Disposition: attachment) - não segue o envelope JSON.

Parâmetros

Além destes, aceita ano, mes, id_cliente, status, data_inicio, data_fim, sort e order, com a mesma semântica da rota monitoramento-mensal. formato fora de csv/xlsx (ou categoria inválida) retorna 422.

Request

Sem corpo de requisição.

GET /api/v1/dashboard/monitoramento-mensal/export?ano=2026&mes=6&formato=xlsx&categoria=lancamentos

Response 200 OK

Corpo binário do arquivo (text/csv ou planilha XLSX) com header Content-Disposition: attachment; filename="...". Esta rota não usa o envelope JSON.

Escopo: dashboard:read

GET /dashboard/mapa-mes

Mapa do Mês (Início): central de pendências do pipeline Importar → Regrar → Exportar → Entregue por cliente. As quatro etapas particionam o total de clientes ativos. Diferente das demais rotas, filtra por ano/mes e por grupo de carteira (não por data_inicio/data_fim).

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

Envelope com data = MapaMesData.

{
  "success": true,
  "message": "Mapa do mes gerado com sucesso",
  "data": {
    "ano": 2026,
    "mes": 6,
    "resumo": {
      "total_clientes": 312,
      "importar": 40,
      "regrar": 22,
      "exportar": 10,
      "entregue": 240,
      "prontos_entrega": 240,
      "pct_prontos": 76.9
    },
    "comparativo_mes_anterior": { "entregue": 231, "delta_entregue": 9 },
    "funil": { "importado": 272, "regrado": 250, "exportado": 240 },
    "clientes": [
      {
        "id_cliente": 1234,
        "nome": "ACME SERVICOS LTDA",
        "etapa": "entregue",
        "sem_movimento": false,
        "qtd_bancos": 2,
        "qtd_lancamentos": 320,
        "qtd_regra_pendente": 0,
        "qtd_prontos": 320,
        "qtd_exportados": 320,
        "qtd_erros": 0,
        "ultima_data": "2026-06-28T14:20:00",
        "dias_sem_importar": 5
      }
    ]
  }
}

Escopo: dashboard:read

Schemas

KpisData

MovimentacaoDiariaData

data = { "serie": List[MovimentacaoDiariaItem] }.

MovimentacaoDiariaItem:

LancamentosStatusData

LancamentoPorStatusItem: status: str, qtd: int, valor: float.

TopContaItem:

ImportacoesResumoData

ImportacoesKpis: total: int, pct_sucesso: float, registros_processados: int, pendentes: int.

ImportacaoPorTipoItem: tipo: str, qtd: int, ultimo_status: str, ultima_data: str | null.

ImportacaoHistoricoItem:

SaldosData

SaldoGrupoItem: grupo: str, saldo: float.

MaiorContaItem: id_conta: int, codigo_dominio: str, descricao: str | null, saldo: float.

ContaSemMovimentoItem: id_conta: int, codigo_dominio: str, descricao: str | null.

ClientesResumoData

ClientesKpis: ativos: int, novos: int (sempre 0 - ver nota), sem_movimento: int.

ClienteRankingItem: id_cliente: int, nome: str, valor: float, qtd: int.

ClienteConcentracaoItem: id_cliente: int, nome: str, percentual: float, valor: float.

MonitoramentoMensalData

MonitoramentoMensalResumo: total_clientes, bancos_cadastrados, importacoes_concluidas, importacoes_pendentes, importacoes_com_erro, total_lancamentos, total_atualizados (default 0), total_ignorados (default 0), clientes_concluidos, clientes_pendentes, clientes_sem_movimento (todos int) e pct_concluidos (float).

MonitoramentoMensalComparativo: clientes_concluidos: int, pct_concluidos: float, total_lancamentos: int, importacoes_concluidas: int.

MonitoramentoMensalClienteItem:

MonitoramentoPorCategoria: objeto com lancamentos, regras e contas, cada um um MonitoramentoCategoriaBlock (resumo, comparativo_mes_anterior, clientes) calculado apenas com as importações daquela categoria. Para regras e contas, os lançamentos são sempre 0 (essas importações não geram lançamento contábil).

MapaMesData

MapaMesResumo: total_clientes, importar, regrar, exportar, entregue, prontos_entrega (== entregue) - todos int - e pct_prontos: float (round(entregue / total_clientes * 100, 1)).

MapaMesComparativo: entregue: int, delta_entregue: int (entregues atual − mês anterior).

MapaMesFunil: importado: int, regrado: int, exportado: int (== entregue).

MapaMesClienteItem:

Notas

• Toda resposta (exceto a exportação) segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
• Domínio read-only: todas as rotas são GET e nenhuma altera dados.
• Validação de período (rotas kpis, movimentacao-diaria, lancamentos-status, importacoes-resumo, saldos, clientes-resumo): data_inicio e data_fim obrigatórios; janela máxima de 366 dias; id_cliente opcional e > 0. Violações retornam 422.
• Em monitoramento-mensal, os overrides data_inicio/data_fim só têm efeito quando ambos são enviados; um sozinho é ignorado e o service usa o mês inteiro. O mesmo teto de 366 dias se aplica ao override.
• GET /dashboard/monitoramento-mensal/export retorna um arquivo binário (CSV/XLSX) e, por isso, não usa o envelope JSON - o corpo é o próprio conteúdo do arquivo com Content-Disposition: attachment.
• clientes-resumo.kpis.novos é sempre 0 (a tabela customer não tem coluna de data de criação).
• As janelas de período são limitadas por segurança: agregações e o loop dia-a-dia (sparkline/série) têm custo proporcional ao intervalo, e previews da Vercel batem no banco de produção.