Report

Endpoints da WebApiAlcance para relatórios consolidados da plataforma - visões agregadas de atividades, erros e das automações (Conversor de extratos, Conversor de relatórios e Domínio Web). São rotas somente-leitura que consolidam dados operacionais em resumos e listagens detalhadas, com filtros opcionais 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. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/report

Escopos necessários

report:read - todos os endpoints deste domínio (resumo, atividades, erros e relatórios de automação)
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/summary`

Resumo geral consolidado - contadores de atividades, conclusões, erros, usuários e clientes. Rota somente-leitura sem filtros.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. A resposta traz em data um ReportSummaryDTO.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Resumo do relatório gerado com sucesso",
  "data": {
    "total_atividades": 1280,
    "total_atividades_concluido": 1104,
    "total_errors": 96,
    "total_usuarios": 14,
    "total_clientes": 210
  }
}

Escopo: report:read

`GET /report/activities`

Relatório detalhado de atividades (sem filtros). Retorna a lista completa de atividades enriquecida com nome do usuário, nome do cliente e total de erros por atividade.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. A resposta traz em data um array de ActivityReportDTO.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Relatório de atividades gerado com sucesso",
  "data": [
    {
      "id": 501,
      "titulo": "Emissão de CND Federal",
      "descricao": "Lote mensal",
      "status": "concluido",
      "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
    }
  ]
}

Escopo: report:read

`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).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`data_inicio`	`date`	query	não	Início do período.
`data_fim`	`date`	query	não	Fim do período.
`status`	`str`	query	não	Filtra pelo status da atividade.
`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.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "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": "concluido",
        "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
      }
    ]
  }
}

Escopo: report:read

`GET /report/errors`

Relatório de erros detalhado (sem filtros). Retorna a lista completa de erros registrados, com nome do usuário, nome da atividade e nome do cliente.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. A resposta traz em data um array de ErrorReportDTO.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Relatório de erros gerado com sucesso",
  "data": [
    {
      "id": 90,
      "atividade_id": 501,
      "usuario_id": 7,
      "data_hora": "2026-06-01T08:02:44",
      "tipo_automacao": "certidao",
      "titulo": "Timeout no portal",
      "detalhes": "Conexão expirou ao acessar o e-CAC.",
      "usuario_nome": "Maria Souza",
      "atividade_nome": "Emissão de CND Federal",
      "cliente_nome": "Padaria Central LTDA"
    }
  ]
}

Escopo: report:read

`GET /report/errors/v2`

Relatório de erros com filtros e um bloco de resumo (total de erros e distribuição por tipo de automação). O data é um objeto com resumo e itens (lista de ErrorReportDTO).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`data_inicio`	`date`	query	não	Início do período.
`data_fim`	`date`	query	não	Fim do período.
`cliente_id`	`int`	query	não	Filtra por cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Relatório de erros gerado com sucesso",
  "data": {
    "resumo": {
      "total_erros": 12,
      "erros_por_tipo_automacao": {
        "certidao": 8,
        "scraping": 4
      }
    },
    "itens": [
      {
        "id": 90,
        "atividade_id": 501,
        "usuario_id": 7,
        "data_hora": "2026-06-01T08:02:44",
        "tipo_automacao": "certidao",
        "titulo": "Timeout no portal",
        "detalhes": "Conexão expirou ao acessar o e-CAC.",
        "usuario_nome": "Maria Souza",
        "atividade_nome": "Emissão de CND Federal",
        "cliente_nome": "Padaria Central LTDA"
      }
    ]
  }
}

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).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`data_inicio`	`date`	query	não	Início do período.
`data_fim`	`date`	query	não	Fim do período.
`status`	`str`	query	não	Filtra pelo status do processamento.
`cliente_id`	`int`	query	não	Filtra por cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "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, 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/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).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`data_inicio`	`date`	query	não	Início do período.
`data_fim`	`date`	query	não	Fim do período.
`status`	`str`	query	não	Filtra pelo status do processamento.
`cliente_id`	`int`	query	não	Filtra por cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "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/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).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`data_inicio`	`date`	query	não	Início do período.
`data_fim`	`date`	query	não	Fim do período.
`status`	`str`	query	não	Filtra pelo status do processamento.
`cliente_id`	`int`	query	não	Filtra por cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "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
      }
    ]
  }
}

Escopo: report:read

Schemas

`ReportSummaryDTO`

Campo	Tipo	Notas
`total_atividades`	`int`	Total de atividades registradas.
`total_atividades_concluido`	`int`	Total de atividades concluídas.
`total_errors`	`int`	Total de erros registrados.
`total_usuarios`	`int`	Total de usuários envolvidos.
`total_clientes`	`int`	Total de clientes envolvidos.

`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	Status atual da atividade.
`data_inicio`	`datetime`	sim	Início da atividade.
`data_fim`	`datetime`	não	Fim da atividade (pode ser `null`).
`tipo`	`str`	não	Tipo de automação (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	Nome do cliente (enriquecido).
`total_erros`	`int`	não	Total de erros da atividade. Default `0`.

`ErrorReportDTO`

Campo	Tipo	Obrigatório	Notas
`id`	`int`	sim	Identificador do erro.
`atividade_id`	`int`	sim	Atividade relacionada.
`usuario_id`	`int`	sim	Usuário relacionado.
`data_hora`	`datetime`	sim	Momento do erro.
`tipo_automacao`	`str`	não	Tipo de automação (pode ser `null`).
`titulo`	`str`	não	Título do erro (pode ser `null`).
`detalhes`	`str`	não	Detalhes do erro (pode ser `null`).
`usuario_nome`	`str`	não	Nome do usuário (enriquecido).
`atividade_nome`	`str`	não	Nome da atividade (enriquecido).
`cliente_nome`	`str`	não	Nome do cliente (enriquecido).

`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`).

`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`).

`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`).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro). Nenhum endpoint deste domínio retorna binário/arquivo (Excel/CSV) nem dispara tasks Celery - todos entregam JSON de forma síncrona.
As rotas .../v2, /conversor, /dominio e /conversor/relatorios estruturam o data como { resumo, itens }; as versões básicas (/activities, /errors) retornam data como um array direto de itens; e /summary retorna um objeto único de contadores.
Os filtros de período (data_inicio, data_fim), status, cliente_id, usuario_id e tipo_automacao são todos opcionais - ausentes, o relatório considera todo o conjunto de dados.
Nos relatórios de Conversor (extratos e relatórios), o resumo.arquivos_por_status inclui contadores derivados do campo detalhes (invalidos e regras), além dos status diretos do processamento.
Todas as rotas são GET e exigem apenas o escopo report:read.