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/report

A URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/report.

Escopos necessários

EscopoOperações permitidas
report:readGET /activities/v2, GET /conversor, GET /conversor/relatorios, GET /dominio, GET /geral, GET /geral/export
report:writeReservado; 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âmetroTipoLocalObrigatórioDescrição
data_iniciodatequerynãoInício do período (compara com data_inicio da atividade).
data_fimdatequerynãoFim do período (compara com data_inicio da atividade).
statusstrquerynãoFiltra pelo status da atividade (busca parcial, sem diferenciar caixa).
cliente_idintquerynãoFiltra por cliente.
usuario_idintquerynãoFiltra por usuário.
tipo_automacaostrquerynãoFiltra 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âmetroTipoLocalObrigatórioDescrição
data_iniciodatequerynãoInício do período (sobre data_processamento).
data_fimdatequerynãoFim do período (sobre data_processamento).
statusstrquerynãoFiltra pelo status do processamento (busca parcial).
cliente_idintquerynãoFiltra 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âmetroTipoLocalObrigatórioDescrição
data_iniciodatequerynãoInício do período (sobre data_processamento).
data_fimdatequerynãoFim do período (sobre data_processamento).
statusstrquerynãoFiltra pelo status do processamento (busca parcial).
cliente_idintquerynãoFiltra 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âmetroTipoLocalObrigatórioDescrição
data_iniciodatequerynãoInício do período (sobre data_processamento).
data_fimdatequerynãoFim do período (sobre data_processamento).
statusstrquerynãoFiltra pelo status do processamento (busca parcial).
cliente_idintquerynãoFiltra 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âmetroTipoLocalObrigatórioDescrição
data_iniciodatequerysimInício do período (inclusivo).
data_fimdatequerysimFim do período (inclusivo).
id_clienteintquerynãoRecorta por cliente (> 0).
id_usuariointquerynãoRecorta por usuário executor (> 0).
dominiosstrquerynãoLista CSV de domínios (ex: activity,worker). Ausente = todos.
incluir_itensboolquerynãoInclui 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âmetroTipoLocalObrigatórioDescrição
data_iniciodatequerysimInício do período (inclusivo).
data_fimdatequerysimFim do período (inclusivo).
id_clienteintquerynãoRecorta por cliente (> 0).
id_usuariointquerynãoRecorta por usuário executor (> 0).
dominiosstrquerynãoLista CSV de domínios. Ausente = todos.
formatostrquerynãocsv 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).

FormatoContent-Type
csvtext/csv; charset=utf-8
xlsxapplication/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,200

As 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

CampoTipoObrigatórioNotas
idintsimIdentificador da atividade.
titulostrsimTítulo da atividade.
descricaostrnãoDescrição (pode ser null).
statusstrsimConcluído, Falha ou Pendência Fiscal.
data_iniciodatetimesimInício da atividade.
data_fimdatetimenãoFim da atividade (pode ser null).
tipostrnãoTipo da atividade (pode ser null).
usuario_idintnãoID do usuário (pode ser null).
cliente_idintsimID do cliente.
usuario_nomestrnãoNome do usuário (enriquecido).
cliente_nomestrnãoRazão social do cliente (enriquecido).
total_errosintnão1 se a atividade está em Falha, senão 0. Default 0.

ConversorReportDTO

CampoTipoObrigatórioNotas
idintsimIdentificador do registro.
usuario_idintsimUsuário responsável.
cliente_idintsimCliente relacionado.
usuario_nomestrnãoNome do usuário (enriquecido).
cliente_nomestrnãoNome do cliente (enriquecido).
arquivostrnãoNome do arquivo processado.
bancostrnãoBanco do extrato (pode ser null).
data_processamentodatetimesimMomento do processamento.
statusstrnãoStatus do processamento.
detalhesstrnãoDetalhes/observações (pode ser null).

ConversorRelatorioReportDTO

CampoTipoObrigatórioNotas
idintsimIdentificador do registro.
data_processamentodatetimesimMomento do processamento.
usuario_idintsimUsuário responsável.
cliente_idintsimCliente relacionado.
usuario_nomestrnãoNome do usuário (enriquecido).
cliente_nomestrnãoNome do cliente (enriquecido).
arquivostrnãoNome do arquivo processado.
tipo_estruturastrnãoTipo de estrutura do relatório.
statusstrnãoStatus do processamento.
detalhesstrnãoDetalhes/observações (pode ser null).

DominioReportDTO

CampoTipoObrigatórioNotas
idintsimIdentificador do registro.
usuario_idintsimUsuário responsável.
cliente_idintsimCliente relacionado.
usuario_nomestrnãoNome do usuário (enriquecido).
cliente_nomestrnãoNome do cliente (enriquecido).
arquivostrnãoNome do arquivo processado.
data_processamentodatetimesimMomento do processamento.
statusstrnãoStatus do processamento.
detalhesstrnãoDetalhes/observações (pode ser null).

Relatório geral (data de GET /report/geral)

CampoTipoNotas
periodoobjectdata_inicio e data_fim (ISO) e dias (inclusivo nas duas pontas: 01/07 a 01/07 = 1 dia).
dominiosdict[str, Agregado]Um agregado por domínio pedido, na ordem canônica.
itensdict[str, list[Item]]Só com incluir_itens=true. Até 100 registros mais recentes por domínio.

Agregado (por domínio):

CampoTipoNotas
totalintTotal real do domínio no período (sempre igual à soma dos baldes).
por_statusdict[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, /dominio e /conversor/relatorios estruturam o data como { resumo, itens } e têm todos os filtros opcionais (ausentes, consideram todo o conjunto). Essas rotas usam cliente_id/usuario_id; o relatório geral usa id_cliente/id_usuario e exige data_inicio/data_fim.
  • No relatório geral, worker e agendamento gravam 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. Em agendamento, 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 GET e exigem apenas o escopo report: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.