Usar o Reporter

Use este guia para o fluxo recorrente do Reporter: gerenciar um template, gerar um relatório, verificar o resultado e baixar o arquivo concluído.

Pré-requisitos

Antes de começar, verifique se:

O Reporter está em execução e você consegue se autenticar na API.
Um operador configurou pelo menos uma fonte para os dados consultados pelo seu template.
Você tem um arquivo .tpl correspondente ao formato de saída esperado. Consulte os exemplos de templates e a referência de templates.

Gerenciar templates

O Reporter usa arquivos .tpl enviados para definir o conteúdo e o layout dos relatórios.

Enviar um template

Chame Enviar um template com uma requisição multipart que contenha os três campos obrigatórios:

template: o arquivo .tpl.
outputFormat: o formato do arquivo gerado, como HTML, PDF, XML, CSV ou TXT.
description: uma descrição legível do template.

O Reporter retorna o identificador do template que você usará para gerar relatórios.

Manter templates existentes

Use os endpoints de templates para:

A exclusão de um template é lógica. O Reporter o remove das consultas padrão, mas preserva os relatórios já criados a partir dele.

Gerar um relatório com filtros

Chame Criar um relatório com os dois campos obrigatórios:

templateId: o identificador retornado no envio do template.
filters: as condições agrupadas por fonte de dados, tabela e campo.

A requisição a seguir limita o relatório a uma transação:

{
  "templateId": "0196159b-4f26-7300-b3d9-f4f68a7c85f3",
  "filters": {
    "midaz_transaction": {
      "transaction": {
        "id": {
          "eq": ["0196d983-a2c2-7d5a-a5b7-029fe0dcb710"]
        }
      }
    }
  }
}

Para gerar um relatório sem filtrar linhas, envie um objeto vazio. Não omita o campo:

{
  "templateId": "0196159b-4f26-7300-b3d9-f4f68a7c85f3",
  "filters": {}
}

O Reporter retorna o identificador do relatório no campo id. Guarde esse valor como REPORT_ID para consultar o status da geração e recuperar o resultado. Consulte Filtragem avançada para conhecer os operadores compatíveis e a estrutura dos filtros.

Descobrir schemas das fontes de dados

Examine as fontes configuradas antes de criar templates ou interfaces de filtros dinâmicos:

Listar fontes de dados retorna as fontes disponíveis, seus schemas e suas tabelas.
Consultar uma fonte de dados retorna as tabelas e os campos de uma fonte.

Esses endpoints são somente leitura. Os operadores configuram as fontes no deploy; a API não as cria nem as atualiza.

Interpretar status e erros

Chame Consultar o status do relatório com REPORT_ID.

Status	Significado	O que fazer
`Processing`	O Reporter está gerando o arquivo.	Continue consultando o status em um intervalo razoável.
`Finished`	A geração foi concluída com sucesso.	Baixe o relatório.
`Partial`	O Reporter gerou apenas parte do resultado solicitado.	Examine os detalhes da resposta e corrija as seções de dados que falharam antes de gerar novamente.
`Error`	A geração falhou.	Examine os detalhes do erro, o template, os filtros e a disponibilidade das fontes de dados.

Considere apenas Finished como disponível para download. Um resultado Partial exige investigação mesmo que o Reporter tenha gerado alguns dados.

Verificar e baixar o relatório

Quando o status for Finished:

Chame Baixar um relatório com REPORT_ID.
Confirme se a resposta tem o tipo de conteúdo esperado e o header Content-Disposition.
Abra o arquivo e verifique se os dados e o layout correspondem ao template e aos filtros.

O endpoint de download entrega apenas relatórios com status Finished.

Solução de problemas

Sintoma	O que verificar
O envio do template é rejeitado	Envie `template`, `outputFormat` e `description` e confirme se o arquivo usa a extensão `.tpl`.
A criação do relatório é rejeitada	Envie `templateId` e `filters`. Use `"filters": {}` quando não precisar filtrar linhas.
O relatório permanece em `Processing`	Verifique a saúde do Worker, a conexão com o RabbitMQ e as fontes de dados usadas.
O relatório termina como `Partial`	Examine quais seções falharam e verifique os nomes da fonte, da tabela, do campo e dos filtros.
O relatório termina como `Error`	Verifique o erro retornado, a sintaxe do template, os valores dos filtros, as conexões com as fontes de dados e o armazenamento de objetos.
O download é rejeitado	Consulte o status mais recente. O download só está disponível quando o status é `Finished`.

Configuração para operadores

As opções de deploy a seguir são destinadas a operadores. Você não precisa delas para o fluxo de geração de relatórios.

Configurar o armazenamento de objetos

O Reporter armazena templates e relatórios gerados em um bucket compatível com S3. Ele usa os prefixos templates/ e reports/. O Reporter é compatível com AWS S3, MinIO e SeaweedFS.

Variável	Descrição	Padrão
`OBJECT_STORAGE_ENDPOINT`	Endpoint compatível com S3. Deixe-o vazio para AWS S3.	—
`OBJECT_STORAGE_REGION`	Região da AWS.	`us-east-1`
`OBJECT_STORAGE_ACCESS_KEY_ID`	Chave de acesso.	—
`OBJECT_STORAGE_SECRET_KEY`	Chave secreta.	—
`OBJECT_STORAGE_USE_PATH_STYLE`	Usa URLs no estilo path. MinIO e SeaweedFS geralmente exigem essa opção.	`false`
`OBJECT_STORAGE_DISABLE_SSL`	Usa HTTP em vez de HTTPS quando `OBJECT_STORAGE_ENDPOINT` não contém um esquema. Um esquema `http://` ou `https://` explícito tem prioridade.	`false`
`OBJECT_STORAGE_BUCKET`	Nome do bucket.	`reporter-storage`

AWS S3

OBJECT_STORAGE_ENDPOINT=
OBJECT_STORAGE_REGION=us-west-2
OBJECT_STORAGE_ACCESS_KEY_ID=AKIA...
OBJECT_STORAGE_SECRET_KEY=your-secret-key
OBJECT_STORAGE_USE_PATH_STYLE=false
OBJECT_STORAGE_DISABLE_SSL=false
OBJECT_STORAGE_BUCKET=reporter-prod-bucket

Os exemplos de MinIO e SeaweedFS a seguir usam HTTP apenas para desenvolvimento local. Deploys de produção exigem HTTPS e TLS.

MinIO (desenvolvimento local)

OBJECT_STORAGE_ENDPOINT=http://minio:9000
OBJECT_STORAGE_REGION=us-east-1
OBJECT_STORAGE_ACCESS_KEY_ID=minioadmin
OBJECT_STORAGE_SECRET_KEY=minioadmin
OBJECT_STORAGE_USE_PATH_STYLE=true
OBJECT_STORAGE_DISABLE_SSL=true
OBJECT_STORAGE_BUCKET=reporter-storage

SeaweedFS (desenvolvimento local)

OBJECT_STORAGE_ENDPOINT=http://reporter-seaweedfs:8333
OBJECT_STORAGE_REGION=us-east-1
OBJECT_STORAGE_ACCESS_KEY_ID=any
OBJECT_STORAGE_SECRET_KEY=any
OBJECT_STORAGE_USE_PATH_STYLE=true
OBJECT_STORAGE_DISABLE_SSL=true
OBJECT_STORAGE_BUCKET=reporter-storage

O S3 não é compatível com TTL por objeto. Configure políticas de ciclo de vida do bucket S3 se os relatórios gerados precisarem expirar automaticamente.

Configurar fontes de dados externas

Defina cada fonte PostgreSQL ou MongoDB com variáveis de ambiente DATASOURCE_<NAME>_*.

Variável	Descrição	Obrigatória
`DATASOURCE_<NAME>_CONFIG_NAME`	Identificador usado nos templates, como `midaz_onboarding`.	Sim
`DATASOURCE_<NAME>_HOST`	Host do banco de dados.	Sim
`DATASOURCE_<NAME>_PORT`	Porta do banco de dados.	Sim
`DATASOURCE_<NAME>_USER`	Usuário do banco de dados.	Somente quando o banco exige autenticação por usuário
`DATASOURCE_<NAME>_PASSWORD`	Senha do banco de dados.	Somente quando o banco exige autenticação por senha
`DATASOURCE_<NAME>_DATABASE`	Nome do banco de dados.	Sim
`DATASOURCE_<NAME>_TYPE`	`postgresql` ou `mongodb`, em letras minúsculas.	Sim
`DATASOURCE_<NAME>_SSLMODE`	Modo SSL do PostgreSQL, como `disable` ou `require`.	Apenas PostgreSQL
`DATASOURCE_<NAME>_SSLROOTCERT`	Caminho do certificado raiz do PostgreSQL.	Apenas PostgreSQL
`DATASOURCE_<NAME>_SSL`	Habilita SSL no MongoDB.	Apenas MongoDB
`DATASOURCE_<NAME>_SSLCA`	Caminho do certificado CA do MongoDB.	Apenas MongoDB
`DATASOURCE_<NAME>_OPTIONS`	Opções adicionais da URI do MongoDB.	Apenas MongoDB
`DATASOURCE_<CONFIG_NAME>_SCHEMAS`	Schemas PostgreSQL separados por vírgulas que serão expostos. O prefixo da variável deriva de `CONFIG_NAME`.	Apenas PostgreSQL

Para uma fonte cujo CONFIG_NAME é midaz_onboarding:

DATASOURCE_ONBOARDING_CONFIG_NAME=midaz_onboarding
DATASOURCE_ONBOARDING_HOST=midaz-postgres-replica
DATASOURCE_ONBOARDING_PORT=5702
DATASOURCE_ONBOARDING_USER=midaz
DATASOURCE_ONBOARDING_PASSWORD=CHANGE_ME
DATASOURCE_ONBOARDING_DATABASE=onboarding
DATASOURCE_ONBOARDING_TYPE=postgresql
DATASOURCE_ONBOARDING_SSLMODE=require

Referencie a fonte em um template pelo CONFIG_NAME:

{% for account in midaz_onboarding.account %}
  {{ account.id }} - {{ account.name }}
{% endfor %}

Para usar vários schemas do PostgreSQL, derive a variável de schemas do CONFIG_NAME. Por exemplo, external_db corresponde a DATASOURCE_EXTERNAL_DB_SCHEMAS:

DATASOURCE_EXTERNAL_CONFIG_NAME=external_db
DATASOURCE_EXTERNAL_HOST=external-postgres
DATASOURCE_EXTERNAL_PORT=5432
DATASOURCE_EXTERNAL_USER=db_user
DATASOURCE_EXTERNAL_PASSWORD=CHANGE_ME
DATASOURCE_EXTERNAL_DATABASE=external_database
DATASOURCE_EXTERNAL_TYPE=postgresql
DATASOURCE_EXTERNAL_SSLMODE=require
DATASOURCE_EXTERNAL_DB_SCHEMAS=sales,inventory,reporting

Use database:schema.table nos templates e schema.table como chave da tabela nos filtros:

{% for order in external_db:sales.orders %}
  {{ order.id }} - {{ order.total }}
{% endfor %}

{
  "templateId": "00000000-0000-0000-0000-000000000000",
  "filters": {
    "external_db": {
      "sales.orders": {
        "created_at": { "gte": ["2025-01-01"] }
      }
    }
  }
}

Quando a variável de schemas não está definida, o Reporter usa o schema public. O Manager carrega a configuração das fontes de dados e se conecta sob demanda. O Worker se conecta durante a inicialização e repete as tentativas para fontes indisponíveis. Ele pode continuar com funcionalidade reduzida se uma fonte continuar indisponível.

​Pré-requisitos

​Gerenciar templates

​Enviar um template

​Manter templates existentes

​Gerar um relatório com filtros

​Descobrir schemas das fontes de dados

​Interpretar status e erros

​Verificar e baixar o relatório

​Solução de problemas

​Configuração para operadores

​Configurar o armazenamento de objetos

​Configurar fontes de dados externas

​Tarefas relacionadas

Pré-requisitos

Gerenciar templates

Enviar um template

Manter templates existentes

Gerar um relatório com filtros

Descobrir schemas das fontes de dados

Interpretar status e erros

Verificar e baixar o relatório

Solução de problemas

Configuração para operadores

Configurar o armazenamento de objetos

Configurar fontes de dados externas

Tarefas relacionadas