Report
Endpoints da WebApiAlcance para relatórios consolidados da plataforma - visões agregadas de atividades, das automações (Conversor de extratos, Conversor de relatórios e Domínio Web) e o relatório geral, que agrega os 12 domínios de automação do período em uma única chamada (com export CSV/XLSX). São rotas somente-leitura, com filtros por período, status, cliente, usuário e tipo de automação.
Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.
Base path
/api/v1/reportA URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/report.
Escopos necessários
| Escopo | Operações permitidas |
|---|---|
report:read | GET /activities/v2, GET /conversor, GET /conversor/relatorios, GET /dominio, GET /geral, GET /geral/export |
report:write | Reservado; nenhum endpoint atual de Report exige escrita. |
O escopo é derivado da rota: o prefixo /report vira o recurso report, e o método HTTP define a ação (read para GET). Como todas as rotas são GET, na prática o domínio é consumido apenas com report:read.
Endpoints
GET /report/activities/v2
Relatório de atividades com filtros e um bloco de resumo agregado. O data é um objeto com resumo (contadores) e itens (lista de ActivityReportDTO). Só entram atividades de clientes ativos e com usuário vinculado.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
data_inicio | date | query | não | Início do período (compara com data_inicio da atividade). |
data_fim | date | query | não | Fim do período (compara com data_inicio da atividade). |
status | str | query | não | Filtra pelo status da atividade (busca parcial, sem diferenciar caixa). |
cliente_id | int | query | não | Filtra por cliente. |
usuario_id | int | query | não | Filtra por usuário. |
tipo_automacao | str | query | não | Filtra pelo tipo de automação (aplicado sobre o título da atividade). |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Relatório de atividades gerado com sucesso",
"data": {
"resumo": {
"total_atividades": 320,
"total_atividades_concluido": 288,
"total_errors": 12,
"total_usuarios": 6,
"total_clientes": 54
},
"itens": [
{
"id": 501,
"titulo": "Emissão de CND Federal",
"descricao": "Lote mensal",
"status": "Concluído",
"data_inicio": "2026-06-01T08:00:00",
"data_fim": "2026-06-01T08:03:12",
"tipo": "certidao",
"usuario_id": 7,
"cliente_id": 42,
"usuario_nome": "Maria Souza",
"cliente_nome": "Padaria Central LTDA",
"total_erros": 0
}
]
}
}No resumo, total_atividades_concluido conta as atividades com status Concluído e total_errors as com status Falha. Em cada item, total_erros é 1 quando a própria atividade está em Falha e 0 caso contrário; cliente_nome é a razão social.
Escopo: report:read
GET /report/conversor
Relatório de dados de automação do Conversor (extratos bancários), com filtros e resumo agregado. O data traz resumo (arquivos por mês, total de bancos distintos, arquivos por status e total de arquivos) e itens (lista de ConversorReportDTO). Só entram registros de clientes ativos.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
data_inicio | date | query | não | Início do período (sobre data_processamento). |
data_fim | date | query | não | Fim do período (sobre data_processamento). |
status | str | query | não | Filtra pelo status do processamento (busca parcial). |
cliente_id | int | query | não | Filtra por cliente. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Relatório de conversor gerado com sucesso",
"data": {
"resumo": {
"arquivos_por_mes": { "2026-05": 120, "2026-06": 143 },
"total_bancos_distintos": 9,
"arquivos_por_status": {
"convertido": 240,
"invalidos": 15,
"regras": 8
},
"total_arquivos": 263
},
"itens": [
{
"id": 3120,
"usuario_id": 7,
"cliente_id": 42,
"usuario_nome": "Maria Souza",
"cliente_nome": "Padaria Central LTDA",
"arquivo": "extrato_maio.ofx",
"banco": "Banco do Brasil",
"data_processamento": "2026-05-12T14:20:00",
"status": "convertido",
"detalhes": null
}
]
}
}Contadores derivados de detalhes
Além dos status diretos (em minúsculas), o resumo.arquivos_por_status deriva duas categorias a partir do campo detalhes: invalidos (quando começa com "Arquivo não convertido, erro durante o processamento do arquivo.") e regras (quando começa com "Arquivo não convertido, contem regras não encontradas no extrato.").
Escopo: report:read
GET /report/conversor/relatorios
Relatório de dados de automação do Conversor: relatórios (estruturas de relatório), com filtros e resumo agregado. O data traz resumo (arquivos por mês, total de estruturas distintas, arquivos por status e total de arquivos) e itens (lista de ConversorRelatorioReportDTO). Só entram registros de clientes ativos.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
data_inicio | date | query | não | Início do período (sobre data_processamento). |
data_fim | date | query | não | Fim do período (sobre data_processamento). |
status | str | query | não | Filtra pelo status do processamento (busca parcial). |
cliente_id | int | query | não | Filtra por cliente. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Relatório de conversor gerado com sucesso",
"data": {
"resumo": {
"arquivos_por_mes": { "2026-05": 40, "2026-06": 52 },
"total_estruturas_distintos": 5,
"arquivos_por_status": {
"convertido": 80,
"invalidos": 7,
"regras": 5
},
"total_arquivos": 92
},
"itens": [
{
"id": 4410,
"data_processamento": "2026-05-18T09:12:00",
"usuario_id": 7,
"cliente_id": 42,
"usuario_nome": "Maria Souza",
"cliente_nome": "Padaria Central LTDA",
"arquivo": "relatorio_maio.pdf",
"tipo_estrutura": "balancete",
"status": "convertido",
"detalhes": null
}
]
}
}Os contadores derivados invalidos e regras seguem a mesma regra de GET /report/conversor.
Escopo: report:read
GET /report/dominio
Relatório de dados de automação da Domínio Web, com filtros e resumo agregado. O data traz resumo (arquivos por mês, arquivos por status e total de arquivos) e itens (lista de DominioReportDTO). Só entram registros de clientes ativos.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
data_inicio | date | query | não | Início do período (sobre data_processamento). |
data_fim | date | query | não | Fim do período (sobre data_processamento). |
status | str | query | não | Filtra pelo status do processamento (busca parcial). |
cliente_id | int | query | não | Filtra por cliente. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Relatório de Domínio Web gerado com sucesso",
"data": {
"resumo": {
"arquivos_por_mes": { "2026-05": 80, "2026-06": 95 },
"arquivos_por_status": { "importado": 160, "erro": 15 },
"total_arquivos": 175
},
"itens": [
{
"id": 812,
"usuario_id": 7,
"cliente_id": 42,
"usuario_nome": "Maria Souza",
"cliente_nome": "Padaria Central LTDA",
"arquivo": "lancamentos_maio.txt",
"data_processamento": "2026-05-30T10:05:00",
"status": "importado",
"detalhes": null
}
]
}
}Escopo: report:read
GET /report/geral
Relatório geral: todos os domínios de automação do período em uma chamada. Cada domínio é agregado em contagens, então o payload tem tamanho previsível. Por padrão traz só contagens; com incluir_itens=true, acrescenta até 100 registros por domínio.
Os 12 domínios, na ordem canônica do payload: activity, situacao_fiscal, certidao_negativa, alvara_funcionamento, dctfweb_guias, dctfweb_recibo, iss_guias, tff_salvador, conversor, dominio_web, worker, agendamento.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
data_inicio | date | query | sim | Início do período (inclusivo). |
data_fim | date | query | sim | Fim do período (inclusivo). |
id_cliente | int | query | não | Recorta por cliente (> 0). |
id_usuario | int | query | não | Recorta por usuário executor (> 0). |
dominios | str | query | não | Lista CSV de domínios (ex: activity,worker). Ausente = todos. |
incluir_itens | bool | query | não | Inclui até 100 registros por domínio. Default false (só contagens). |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Relatório geral gerado com sucesso",
"data": {
"periodo": {
"data_inicio": "2026-06-01",
"data_fim": "2026-06-30",
"dias": 30
},
"dominios": {
"activity": {
"total": 320,
"por_status": { "Concluído": 288, "Falha": 20, "Pendência Fiscal": 12 },
"por_tipo": { "certidao": 200, "desconhecido": 120 }
},
"conversor": {
"total": 143,
"por_status": { "convertido": 135, "erro": 8 },
"por_banco": { "Banco do Brasil": 90, "Itaú": 53 }
},
"dominio_web": {
"total": 95,
"por_status": { "importado": 95 }
}
},
"itens": {
"activity": [
{
"id": 501,
"data": "2026-06-30T08:00:00",
"status": "Concluído",
"dimensao": "certidao",
"id_cliente": 42,
"id_usuario": 7
}
]
}
}
}O exemplo está resumido: sem dominios, a chave dominios traz os 12 domínios. A chave itens só existe quando incluir_itens=true. Os valores de por_status e das dimensões são os valores crus de cada domínio (cada um tem vocabulário próprio).
data_inicio posterior a data_fim, janela maior que 366 dias entre as datas, id_cliente/id_usuario não positivos ou domínio desconhecido em dominios retornam 422 Unprocessable Entity.
Escopo: report:read
GET /report/geral/export
Exporta os agregados do relatório geral como arquivo CSV ou XLSX (nunca os itens). O formato é longo: uma linha por métrica, com as colunas Dominio, Metrica, Valor e Quantidade. Para cada domínio sai uma linha total e uma linha por valor de por_status e da dimensão do domínio.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
data_inicio | date | query | sim | Início do período (inclusivo). |
data_fim | date | query | sim | Fim do período (inclusivo). |
id_cliente | int | query | não | Recorta por cliente (> 0). |
id_usuario | int | query | não | Recorta por usuário executor (> 0). |
dominios | str | query | não | Lista CSV de domínios. Ausente = todos. |
formato | str | query | não | csv ou xlsx. Default csv. |
Request
Sem corpo de requisição.
Response 200 OK
Corpo binário (não usa o envelope JSON), com o header Content-Disposition: attachment; filename="report_geral_{data_inicio}_{data_fim}.csv" (ou .xlsx).
| Formato | Content-Type |
|---|---|
csv | text/csv; charset=utf-8 |
xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
Dominio,Metrica,Valor,Quantidade
Atividades,total,,320
Atividades,por_status,Concluído,288
Atividades,por_status,Falha,20
Atividades,por_tipo,certidao,200As linhas seguem a ordem canônica dos domínios, então a mesma consulta gera sempre a mesma planilha. formato fora de csv/xlsx retorna 422 Unprocessable Entity, além das mesmas validações de período e domínios de GET /report/geral.
Escopo: report:read
Schemas
ActivityReportDTO
| Campo | Tipo | Obrigatório | Notas |
|---|---|---|---|
id | int | sim | Identificador da atividade. |
titulo | str | sim | Título da atividade. |
descricao | str | não | Descrição (pode ser null). |
status | str | sim | Concluído, Falha ou Pendência Fiscal. |
data_inicio | datetime | sim | Início da atividade. |
data_fim | datetime | não | Fim da atividade (pode ser null). |
tipo | str | não | Tipo da atividade (pode ser null). |
usuario_id | int | não | ID do usuário (pode ser null). |
cliente_id | int | sim | ID do cliente. |
usuario_nome | str | não | Nome do usuário (enriquecido). |
cliente_nome | str | não | Razão social do cliente (enriquecido). |
total_erros | int | não | 1 se a atividade está em Falha, senão 0. Default 0. |
ConversorReportDTO
| Campo | Tipo | Obrigatório | Notas |
|---|---|---|---|
id | int | sim | Identificador do registro. |
usuario_id | int | sim | Usuário responsável. |
cliente_id | int | sim | Cliente relacionado. |
usuario_nome | str | não | Nome do usuário (enriquecido). |
cliente_nome | str | não | Nome do cliente (enriquecido). |
arquivo | str | não | Nome do arquivo processado. |
banco | str | não | Banco do extrato (pode ser null). |
data_processamento | datetime | sim | Momento do processamento. |
status | str | não | Status do processamento. |
detalhes | str | não | Detalhes/observações (pode ser null). |
ConversorRelatorioReportDTO
| Campo | Tipo | Obrigatório | Notas |
|---|---|---|---|
id | int | sim | Identificador do registro. |
data_processamento | datetime | sim | Momento do processamento. |
usuario_id | int | sim | Usuário responsável. |
cliente_id | int | sim | Cliente relacionado. |
usuario_nome | str | não | Nome do usuário (enriquecido). |
cliente_nome | str | não | Nome do cliente (enriquecido). |
arquivo | str | não | Nome do arquivo processado. |
tipo_estrutura | str | não | Tipo de estrutura do relatório. |
status | str | não | Status do processamento. |
detalhes | str | não | Detalhes/observações (pode ser null). |
DominioReportDTO
| Campo | Tipo | Obrigatório | Notas |
|---|---|---|---|
id | int | sim | Identificador do registro. |
usuario_id | int | sim | Usuário responsável. |
cliente_id | int | sim | Cliente relacionado. |
usuario_nome | str | não | Nome do usuário (enriquecido). |
cliente_nome | str | não | Nome do cliente (enriquecido). |
arquivo | str | não | Nome do arquivo processado. |
data_processamento | datetime | sim | Momento do processamento. |
status | str | não | Status do processamento. |
detalhes | str | não | Detalhes/observações (pode ser null). |
Relatório geral (data de GET /report/geral)
| Campo | Tipo | Notas |
|---|---|---|
periodo | object | data_inicio e data_fim (ISO) e dias (inclusivo nas duas pontas: 01/07 a 01/07 = 1 dia). |
dominios | dict[str, Agregado] | Um agregado por domínio pedido, na ordem canônica. |
itens | dict[str, list[Item]] | Só com incluir_itens=true. Até 100 registros mais recentes por domínio. |
Agregado (por domínio):
| Campo | Tipo | Notas |
|---|---|---|
total | int | Total real do domínio no período (sempre igual à soma dos baldes). |
por_status | dict[str, int] | Contagem por status. Valor ausente/vazio cai no balde desconhecido. Ordenado por contagem decrescente. |
| dimensão extra (quando houver) | dict[str, int] | por_tipo (activity, certidao_negativa, dctfweb_guias, dctfweb_recibo, iss_guias), por_banco (conversor) ou por_automacao (worker, agendamento). |
Item (quando incluir_itens=true): id, data (ISO), status, dimensao (só em domínios com dimensão extra), id_cliente e id_usuario. Sem nomes e sem arquivos/PDF - para o artefato, use a rota específica do domínio. Para saber se a lista foi cortada, compare len(itens[dominio]) com dominios[dominio].total.
Notas
- Toda resposta JSON segue o envelope
{ "status": "success", "message": ..., "data": ... }. A exceção éGET /report/geral/export, que devolve o arquivo binário. Nenhuma rota roda em segundo plano - tudo é síncrono. /activities/v2,/conversor,/dominioe/conversor/relatoriosestruturam odatacomo{ resumo, itens }e têm todos os filtros opcionais (ausentes, consideram todo o conjunto). Essas rotas usamcliente_id/usuario_id; o relatório geral usaid_cliente/id_usuarioe exigedata_inicio/data_fim.- No relatório geral,
workereagendamentogravam a data em UTC; o período informado (horário de Brasília) é convertido internamente, então as bordas do dia batem nos dois tipos de tabela. Emagendamento, a data considerada é a de criação do agendamento. - O relatório geral não inclui
/report/conversor/relatorios(fora do contrato do endpoint). - Todas as rotas são
GETe exigem apenas o escoporeport:read.
Rotas removidas
As rotas GET /report/summary, GET /report/activities (v1), GET /report/errors e GET /report/errors/v2 não existem mais na API. Use GET /report/activities/v2 para atividades (erro de automação é atividade com status Falha) e GET /report/geral para a visão consolidada.