NFS-e/Repasse: Dashboard Repasse

Endpoints da WebApiAlcance que entregam os indicadores agregados do produto Repasse Médico. Este é um domínio de agregação puro - não possui tabelas nem CRUD próprios: ele move para o servidor os cálculos que antes eram feitos no cliente (hooks useDashboardData, useEvolucaoFinanceira, useIndicadoresFinanceiros). São todos endpoints de leitura, disponíveis a qualquer usuário autenticado.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Escopo compartilhado do domínio nfse-repasse

O primeiro segmento da rota é nfse-repasse, compartilhado por todos os módulos do produto (dashboard, notas, repasses). Por isso o recurso derivado é nfse_repasse - e não dashboard_repasse. Uma API Key com nfse_repasse:read habilita todos os endpoints de leitura do produto NFS-e/Repasse, não apenas este dashboard. Emita chaves com o menor conjunto de escopos possível.

Base path

/api/v1/nfse-repasse/dashboard-repasse

Escopos necessários

nfse_repasse:read - indicadores e evolução financeira (todos os endpoints deste dashboard)
nfse_repasse:write - não usado aqui; este domínio é somente leitura (não há endpoints de escrita)

O escopo é derivado da rota: o primeiro segmento /nfse-repasse vira o recurso nfse_repasse (hífen → underscore) e o método HTTP define a ação (read para GET). Como não há rotas POST/PUT/DELETE, o escopo nfse_repasse:write nunca é exigido por este dashboard.

Endpoints

`GET /nfse-repasse/dashboard-repasse/indicadores`

Retorna os KPIs centrais do dashboard de repasse para o período: faturamento bruto, total de notas emitidas, ticket médio e valor total de repasses. É um endpoint de agregação, somente leitura.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`competencia`	`str`	query	não	Filtro por competência, ex.: `2026-06`. Sem filtro = todas. Máx. 20 chars.
`status`	`str`	query	não	Filtro por status da nota, ex.: `emitida`. Máx. 30 chars.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Indicadores gerados com sucesso!",
  "data": {
    "faturamento_bruto": 128450.75,
    "total_notas_emitidas": 342,
    "ticket_medio": 375.59,
    "valor_total_repasses": 96338.06
  }
}

O campo valor_total_repasses pode vir null quando a tabela repasse ainda não está disponível no ambiente. Escopo: nfse_repasse:read

`GET /nfse-repasse/dashboard-repasse/evolucao-financeira`

Retorna a série temporal mensal (uma entrada por competência) com faturamento bruto e total de notas, agrupada a partir de nota_fiscal. Útil para gráficos de evolução.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`status`	`str`	query	não	Filtro por status da nota, ex.: `emitida`. Máx. 30 chars.
`limite_competencias`	`int`	query	não	Quantidade de competências mais recentes na série. Faixa `1..36`, default `12`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Evolução financeira gerada com sucesso!",
  "data": {
    "serie": [
      { "competencia": "2026-01", "faturamento_bruto": 98120.0, "total_notas": 271 },
      { "competencia": "2026-02", "faturamento_bruto": 104300.5, "total_notas": 289 },
      { "competencia": "2026-06", "faturamento_bruto": 128450.75, "total_notas": 342 }
    ]
  }
}

Escopo: nfse_repasse:read

Schemas

`IndicadoresData`

KPIs centrais do dashboard de repasse para um período (competência).

Campo	Tipo	Notas
`faturamento_bruto`	`float`	Somatório do faturamento das notas (origem: `nota_fiscal`).
`total_notas_emitidas`	`int`	Quantidade de notas no período.
`ticket_medio`	`float`	Faturamento bruto médio por nota.
`valor_total_repasses`	`float \| null`	Total de repasses (origem: `repasse`). `null` quando a tabela indisponível.

Precisão monetária

Valores monetários são expostos como float apenas para transporte (o front consome número). A precisão contábil real vive nas colunas Numeric(15, 2) das tabelas-fonte.

`EvolucaoFinanceiraData`

Série temporal por competência.

Campo	Tipo	Notas
`serie`	`List[EvolucaoFinanceiraItem]`	Pontos da série, um por competência.

Schema `EvolucaoFinanceiraItem`

Um ponto da série mensal (uma competência).

Campo	Tipo	Notas
`competencia`	`str`	Competência no formato `AAAA-MM`, ex.: `2026-06`.
`faturamento_bruto`	`float`	Faturamento bruto da competência.
`total_notas`	`int`	Total de notas na competência.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Domínio de agregação puro: não há tabelas, CRUD nem path dinâmico /{id}. Todas as rotas são estáticas e somente leitura - qualquer staff autenticado acessa.
O teto de competências da série é 36 (_MAX_COMPETENCIAS); pedidos acima desse limite são rejeitados pela validação do parâmetro limite_competencias.
Relaciona-se com os demais módulos do produto NFS-e/Repasse, que compartilham o escopo nfse_repasse (primeiro segmento da rota).