Pular para o conteúdo principal
O Reporter auxilia os usuários do Midaz Ledger na criação de relatórios dinâmicos e orientados a dados sem necessidade de conhecimento em SQL. Você define domínios, tabelas e campos usando placeholders simples em vez de construir consultas complexas.

​
Uso típico

​
Passo 1 — Crie o arquivo .tpl

Escreva um template correspondente ao formato de saída desejado (HTML, XML, CSV ou TXT). O template deve incorporar blocos do Reporter e seguir a sintaxe apropriada para o formato de saída escolhido. Consulte os Exemplos de templates para orientação.
O arquivo deve ser salvo com a extensão .tpl. Isso é obrigatório para o processamento correto.

​
Passo 2 — Faça o upload do template

Quando estiver pronto, faça o upload do arquivo .tpl usando o endpoint Upload a Template. Defina o campo outputFormat para especificar o formato do relatório. O sistema atribui um nome de arquivo UUID (por exemplo, 0196159b-4f26-7300-b3d9-f4f68a7c85f3.tpl). Endpoints de gerenciamento de templates:

​
Passo 3 — Gere o relatório

Use o endpoint Create a Report para iniciar a geração. Envie um templateId e, opcionalmente, filters no corpo da requisição: 
{
  "templateId": "0196159b-4f26-7300-b3d9-f4f68a7c85f3",
  "filters": {
    "midaz_transaction": {
      "transaction": {
        "id": { "eq": ["0196d983-a2c2-7d5a-a5b7-029fe0dcb710"] }
      }
    }
  }
}
A API retorna um reportId para acompanhamento e recuperação do resultado.

​
Passo 4 — Verifique o status do relatório

O endpoint Check Report Status monitora o progresso, exibindo se o relatório está em processing ou finished.

​
Passo 5 — Baixe o relatório

Quando estiver finished, baixe o relatório usando o endpoint Download a Report. O arquivo aparece no corpo da resposta com os headers Content-Disposition apropriados.

​
Mapeamento de fontes de dados para filtros dinâmicos

Dois endpoints auxiliares possibilitam a filtragem dinâmica:
Esses endpoints são opcionais e projetados para casos de uso avançados, como a construção de interfaces personalizadas ou a automação de fluxos de trabalho de relatórios com base em dados de schema.

​
Configurando o armazenamento

O Reporter armazena templates e relatórios gerados em armazenamento de objetos compatível com S3. Ele suporta AWS S3, MinIO e SeaweedFS nativamente. Todos os arquivos são armazenados em um único bucket com prefixos internos:
  • templates/ — para arquivos de template enviados
  • reports/ — para arquivos de relatório gerados

​
Variáveis de ambiente de armazenamento

VariávelDescriçãoPadrão
OBJECT_STORAGE_ENDPOINTURL do endpoint compatível com S3. Deixe vazio para AWS S3.—
OBJECT_STORAGE_REGIONRegião da AWSus-east-1
OBJECT_STORAGE_ACCESS_KEY_IDChave de acesso para autenticação—
OBJECT_STORAGE_SECRET_KEYChave secreta para autenticação—
OBJECT_STORAGE_USE_PATH_STYLEUsar URLs no estilo path. Obrigatório para MinIO e SeaweedFS.false
OBJECT_STORAGE_DISABLE_SSLDesabilitar verificação SSL. Use apenas para desenvolvimento local.false
OBJECT_STORAGE_BUCKETNome do bucketreporter-storage

​
Exemplos de configuração por provedor

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

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

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 suporta TTL por objeto. Para expirar automaticamente os relatórios gerados, configure políticas de ciclo de vida do bucket S3 no seu bucket.

​
Configurando fontes de dados externas

O Reporter se conecta a bancos de dados externos (PostgreSQL e MongoDB) como fontes de dados para seus templates. Cada fonte de dados é configurada por meio de variáveis de ambiente seguindo o padrão DATASOURCE_<NAME>_*.

​
Variáveis de ambiente de fontes de dados

VariávelDescriçãoObrigatório
DATASOURCE_<NAME>_CONFIG_NAMEIdentificador único usado nos templates (por exemplo, midaz_onboarding)Sim
DATASOURCE_<NAME>_HOSTHost do banco de dadosSim
DATASOURCE_<NAME>_PORTPorta do banco de dadosSim
DATASOURCE_<NAME>_USERUsuário do banco de dadosSim
DATASOURCE_<NAME>_PASSWORDSenha do banco de dadosSim
DATASOURCE_<NAME>_DATABASENome do banco de dadosSim
DATASOURCE_<NAME>_TYPETipo do banco de dados: postgresql ou mongodbSim
DATASOURCE_<NAME>_SSLMODEModo SSL para PostgreSQL (disable, require)Apenas PostgreSQL
DATASOURCE_<NAME>_SSLROOTCERTCaminho do certificado raiz SSL para PostgreSQLApenas PostgreSQL
DATASOURCE_<NAME>_SSLHabilitar SSL para MongoDB (true ou false)Apenas MongoDB
DATASOURCE_<NAME>_SSLCACaminho do arquivo de certificado CA para MongoDBApenas MongoDB
DATASOURCE_<NAME>_OPTIONSOpções adicionais de URI para MongoDBApenas MongoDB
DATASOURCE_<NAME>_SCHEMASLista de schemas separados por vírgula para exporApenas PostgreSQL

​
Exemplo com uma única fonte de dados

DATASOURCE_ONBOARDING_CONFIG_NAME=midaz_onboarding
DATASOURCE_ONBOARDING_HOST=midaz-postgres-replica
DATASOURCE_ONBOARDING_PORT=5702
DATASOURCE_ONBOARDING_USER=midaz
DATASOURCE_ONBOARDING_PASSWORD=lerian
DATASOURCE_ONBOARDING_DATABASE=onboarding
DATASOURCE_ONBOARDING_TYPE=postgresql
DATASOURCE_ONBOARDING_SSLMODE=disable
Nos templates, você referencia essa fonte de dados como midaz_onboarding: 
{% for account in midaz_onboarding.account %}
  {{ account.id }} - {{ account.name }}
{% endfor %}

​
Fonte de dados com múltiplos schemas

Para consultar tabelas em múltiplos schemas do PostgreSQL, defina a variável DATASOURCE_<NAME>_SCHEMAS com uma lista separada por vírgulas: 
DATASOURCE_EXTERNAL_CONFIG_NAME=external_db
DATASOURCE_EXTERNAL_HOST=external-postgres
DATASOURCE_EXTERNAL_PORT=5432
DATASOURCE_EXTERNAL_USER=db_user
DATASOURCE_EXTERNAL_PASSWORD=db_password
DATASOURCE_EXTERNAL_DATABASE=external_database
DATASOURCE_EXTERNAL_TYPE=postgresql
DATASOURCE_EXTERNAL_SSLMODE=disable
DATASOURCE_EXTERNAL_SCHEMAS=sales,inventory,reporting
Nos templates, use a sintaxe explícita de schema database:schema.table: 
{% for order in external_db:sales.orders %}
  {{ order.id }} - {{ order.total }}

  {% for item in external_db:inventory.items|where:"order_id:{{ order.id }}" %}
    Item: {{ item.name }} ({{ item.quantity }} em estoque)
  {% endfor %}
{% endfor %}
Ao gerar um relatório com filtros, use schema.table como chave da tabela: 
{
  "templateId": "00000000-0000-0000-0000-000000000000",
  "filters": {
    "external_db": {
      "sales.orders": {
        "created_at": { "gte": ["2025-01-01"] }
      }
    }
  }
}
Quando DATASOURCE_<NAME>_SCHEMAS não está definido, o Reporter utiliza apenas o schema public por padrão.

​
Comportamento de conexão

O Reporter utiliza duas estratégias de inicialização:
  • Componente Manager (lazy): Carrega a configuração sem conectar. Conecta sob demanda quando um template referencia a fonte de dados. Isso proporciona uma inicialização mais rápida.
  • Componente Worker (eager): Tenta conectar na inicialização com retry de backoff exponencial (até 5 tentativas). Continua com funcionalidade degradada se uma fonte de dados estiver indisponível.

​
Referência completa de variáveis de ambiente

​
Aplicação

VariávelDescriçãoPadrão
ENV_NAMENome do ambientedevelopment
LOG_LEVELNível de log (debug, info, warn, error)debug
SERVER_PORTPorta HTTP do Manager4005
SERVER_ADDRESSEndereço de bind do Manager:4005

​
Armazenamento de objetos (compatível com S3)

VariávelDescriçãoPadrão
OBJECT_STORAGE_ENDPOINTURL do endpoint S3—
OBJECT_STORAGE_REGIONRegião da AWSus-east-1
OBJECT_STORAGE_ACCESS_KEY_IDChave de acesso—
OBJECT_STORAGE_SECRET_KEYChave secreta—
OBJECT_STORAGE_USE_PATH_STYLEURLs no estilo pathfalse
OBJECT_STORAGE_DISABLE_SSLDesabilitar SSLfalse
OBJECT_STORAGE_BUCKETNome do bucketreporter-storage

​
MongoDB

VariávelDescriçãoPadrão
MONGO_URIEsquema de URI (mongodb ou mongodb+srv)—
MONGO_HOSTHost do MongoDB—
MONGO_NAMENome do banco de dados—
MONGO_USERUsuário do banco de dados—
MONGO_PASSWORDSenha do banco de dados—
MONGO_PORTPorta do banco de dados—
MONGO_MAX_POOL_SIZETamanho do pool de conexões1000
MONGO_PARAMETERSParâmetros adicionais de URI—

​
RabbitMQ

VariávelDescriçãoPadrão
RABBITMQ_URIEsquema de URI (amqp)—
RABBITMQ_HOSTHost do RabbitMQ—
RABBITMQ_PORT_AMQPPorta AMQP—
RABBITMQ_PORT_HOSTPorta de gerenciamento—
RABBITMQ_DEFAULT_USERUsuário—
RABBITMQ_DEFAULT_PASSSenha—
RABBITMQ_GENERATE_REPORT_QUEUENome da fila para geração de relatórios—
RABBITMQ_NUMBERS_OF_WORKERSNúmero de workers consumidores (apenas worker)5

​
Redis / Valkey

VariávelDescriçãoPadrão
REDIS_HOSTHost do Redis com porta (por exemplo, host:6379)—
REDIS_PASSWORDSenha do Redis—
REDIS_DBNúmero do banco de dados0
REDIS_PROTOCOLVersão do protocolo Redis3
REDIS_MASTER_NAMENome do master Sentinel (se usando Sentinel)—
REDIS_TLSHabilitar TLSfalse

​
Geração de PDF (apenas worker)

VariávelDescriçãoPadrão
PDF_POOL_WORKERSNúmero de workers paralelos para geração de PDF2
PDF_TIMEOUT_SECONDSTimeout por geração de PDF em segundos90

​
Telemetria (OpenTelemetry)

VariávelDescriçãoPadrão
OTEL_RESOURCE_SERVICE_NAMENome do serviço para traces—
OTEL_LIBRARY_NAMENome da biblioteca de instrumentação—
OTEL_RESOURCE_SERVICE_VERSIONVersão do serviço—
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENTAmbiente de deploy—
OTEL_EXPORTER_OTLP_ENDPOINTEndpoint do exportador OTLP—
ENABLE_TELEMETRYHabilitar coleta de telemetriafalse

​
Autenticação

VariávelDescriçãoPadrão
PLUGIN_AUTH_ADDRESSURL do serviço de autenticação—
PLUGIN_AUTH_ENABLEDHabilitar autenticaçãofalse

​
Licença

VariávelDescriçãoPadrão
LICENSE_KEYChave de licença do Reporter—
ORGANIZATION_IDSIDs de organização para validação de licença—