Usando o Reporter

Use este guia para o workflow recorrente do Reporter: gerencie um template, gere um relatório, verifique o resultado e baixe o arquivo finalizado.

Pré-requisitos

Antes de começar, confirme que:

O Reporter está em execução e você consegue se autenticar na API dele.
Um operador configurou pelo menos uma fonte de dados para os dados que seu template consulta.
Você tem um arquivo .tpl que corresponde ao formato de saída pretendido. Para saída em PDF, escreva o template como HTML. Veja Exemplos de template e a referência de template.

Gerenciar templates

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

Enviar um template

Chame Enviar um template como uma requisição multipart com 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ê usa ao gerar relatórios.

Manter templates existentes

Use os endpoints de template para:

Excluir um template é uma exclusão lógica. O Reporter o exclui 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 quando você enviou o 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. Armazene esse valor como REPORT_ID para verificar o status da geração e obter a saída. Veja Filtragem avançada para os operadores aceitos e a estrutura de filtro.

Descobrir esquemas de fontes de dados

Inspecione as fontes de dados configuradas antes de criar templates ou interfaces de filtro dinâmicas:

Listar fontes de dados retorna uma página de conexões registradas sem credenciais.
Consultar uma fonte de dados retorna a configuração de uma conexão pelo dataSourceId. As credenciais permanecem ocultas.
GET /v1/data-sources/{dataSourceId}/schema inspeciona as tabelas ou coleções ativas e seus campos tipados.

A API controla o ciclo de vida do registro: criar uma fonte de dados, atualizá-la parcialmente, testar a conexão, inspecionar seu esquema ou excluí-la de forma lógica. O Reporter recusa a exclusão enquanto um Template ativo ainda referencia a fonte. Deployments single-tenant também podem popular entradas a partir das variáveis DATASOURCE_* na inicialização. Deployments multi-tenant criam entradas por tenant através da API.

Interpretar status e erros dos relatórios

Chame Verificar status do relatório com REPORT_ID.

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

Trate apenas Finished como disponível para download. Um resultado Partial exige investigação mesmo quando o Reporter produziu alguns dados.

Verificar e baixar o relatório

Quando o status for Finished:

Chame Baixar um relatório com REPORT_ID.
Confirme que 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 atende apenas relatórios com status Finished.

Solução de problemas

Sintoma	Verificação
O envio do template é rejeitado	Envie `template`, `outputFormat` e `description`, e confirme que o arquivo usa a extensão `.tpl`.
A criação do relatório é rejeitada	Envie `templateId` e `filters`. Use `"filters": {}` quando não precisar de filtros de linha.
O relatório permanece em `Processing`	Verifique a saúde do Worker, a conectividade com o RabbitMQ e as fontes de dados referenciadas.
O relatório termina como `Partial`	Inspecione quais seções de dados falharam e verifique a fonte, a tabela, o campo e os nomes de filtro delas.
O relatório termina como `Error`	Verifique o erro retornado, a sintaxe do template, os valores de filtro, a conectividade da fonte de dados e o object storage.
O download é rejeitado	Verifique o status mais recente. Os downloads estão disponíveis apenas quando o status é `Finished`.

Configuração para operadores

As configurações de deploy a seguir são para operadores. Os usuários da aplicação não precisam delas para o workflow de geração de relatórios.

Configurar object storage

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

Variável	Descrição	Padrão
`OBJECT_STORAGE_ENDPOINT`	Endpoint compatível com S3. Deixe 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-style. Normalmente exigido pelo MinIO e pelo SeaweedFS.	`false`
`OBJECT_STORAGE_DISABLE_SSL`	Usa HTTP em vez de HTTPS quando `OBJECT_STORAGE_ENDPOINT` não tem scheme. Um scheme explícito `http://` ou `https://` tem precedência.	`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 abaixo usam HTTP apenas para desenvolvimento local. Deployments 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 oferece suporte a TTL por objeto. Configure as políticas de ciclo de vida de bucket do S3 se os relatórios gerados precisarem expirar automaticamente.

Configurar fontes de dados externas

Defina DATASOURCE_CRED_ENC_KEY com uma chave AES hexadecimal persistente antes de o Reporter iniciar. Gere uma chave de 32 bytes com openssl rand -hex 32. O Manager falha a inicialização quando a chave está ausente ou malformada. Mantenha a mesma chave disponível para cada runtime do Reporter que lê o registro, porque as senhas armazenadas são criptografadas com ela. Use a API para o ciclo de vida normal da fonte de dados. No modo multi-tenant, o Reporter ignora o povoamento via variáveis de ambiente e cada tenant cria suas próprias entradas através da API. No modo single-tenant, você pode popular entradas do PostgreSQL ou do MongoDB na inicialização com as variáveis 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.	Apenas quando o banco de dados exige autenticação de usuário
`DATASOURCE_<NAME>_PASSWORD`	Senha do banco de dados.	Apenas quando o banco de dados exige autenticação por senha
`DATASOURCE_<NAME>_DATABASE`	Nome do banco de dados.	Sim
`DATASOURCE_<NAME>_TYPE`	`postgresql` ou `mongodb`, em 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 o SSL do 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`	Esquemas do PostgreSQL a expor, separados por vírgula. 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 em um template pelo CONFIG_NAME:

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

Para múltiplos esquemas do PostgreSQL, derive a variável de esquema a partir de CONFIG_NAME. Por exemplo, external_db mapeia para 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 a chave de tabela do filtro:

{% 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 esquema não está definida, o Reporter usa o esquema public. O Manager carrega a configuração da fonte de dados e conecta sob demanda. O Worker conecta durante a inicialização e faz novas tentativas para fontes indisponíveis. Ele pode continuar com funcionalidade reduzida quando uma fonte permanece indisponível.

Visão geral

Conceitos

Guias

Integração

Console

Operações

Usando o Reporter

Pré-requisitos

Gerenciar templates

Enviar um template

Manter templates existentes

Gerar um relatório com filtros

Descobrir esquemas de fontes de dados

Interpretar status e erros dos relatórios

Verificar e baixar o relatório

Solução de problemas

Configuração para operadores

Configurar object storage

Configurar fontes de dados externas

Tarefas relacionadas

​Pré-requisitos

​Gerenciar templates

​Enviar um template

​Manter templates existentes

​Gerar um relatório com filtros

​Descobrir esquemas de fontes de dados

​Interpretar status e erros dos relatórios

​Verificar e baixar o relatório

​Solução de problemas

​Configuração para operadores

​Configurar object storage

​Configurar fontes de dados externas

​Tarefas relacionadas

Pré-requisitos

Gerenciar templates

Enviar um template

Manter templates existentes

Gerar um relatório com filtros

Descobrir esquemas de fontes de dados

Interpretar status e erros dos relatórios

Verificar e baixar o relatório

Solução de problemas

Configuração para operadores

Configurar object storage

Configurar fontes de dados externas

Tarefas relacionadas