O ciclo de vida de relatórios
Cada relatório no Reporter segue o mesmo ciclo de quatro etapas:
Projetar uma template
Escrever um arquivo
.tpl que define a estrutura e o conteúdo do seu relatório.Fazer upload da template
Registrar a template no Reporter para que possa ser reutilizada em múltiplas gerações.
Gerar um relatório
Enviar uma requisição com filtros opcionais para produzir um relatório a partir da template.
Projetar uma template
Uma template é um arquivo de texto simples com extensão
.tpl que define como seu relatório aparece e quais dados ele inclui. As templates espelham a estrutura do resultado final — se você quer um relatório XML, você escreve XML dentro do arquivo .tpl; se quer HTML, escreve HTML.
Em vez de escrever consultas SQL, você referencia dados através de placeholders que seguem uma sintaxe de caminho simples:
{{ midaz_onboarding.account.name }} obtém o nome da conta do banco de dados de onboarding do Midaz.
O que você pode fazer nas templates
| Capacidade | Descrição |
|---|---|
| Loops | Iterar sobre coleções de registros |
| Condições | Mostrar ou ocultar conteúdo com base em valores dos dados |
| Agregações | Calcular somas, médias, contagens, mínimos e máximos |
| Aritmética | Realizar cálculos em campos numéricos |
| Filtros | Transformar valores inline (formatar números, substituir strings, extrair substrings) |
| Contadores | Rastrear e exibir totais acumulados entre iterações |
Formatos de saída suportados
| Conteúdo da template | Formato de saída |
|---|---|
.tpl com estrutura CSV | Arquivo CSV |
.tpl com estrutura XML | Arquivo XML |
.tpl com estrutura HTML | Arquivo HTML ou PDF |
.tpl com estrutura TXT | Arquivo TXT |
Fazer upload da template
Uma vez que seu arquivo
.tpl está pronto, faça upload para o Reporter. Durante o upload, você especifica:
- O arquivo de template — seu arquivo
.tpl - Formato de saída — o formato que o Reporter deve gerar (CSV, XML, HTML, PDF ou TXT)
- Descrição — um rótulo opcional para ajudar a identificar a template posteriormente
As templates são reutilizáveis. Faça upload uma vez e gere relatórios a partir da mesma template quantas vezes precisar com filtros diferentes.
Gerar um relatório
Para gerar um relatório, envie uma requisição com o ID da template e filtros opcionais que restringem os dados.
Como os filtros funcionam
Os filtros seguem um caminho estruturado: fonte de dados > tabela > campo. Você pode filtrar por igualdade, intervalos, maior/menor que e pertencimento a listas. Por exemplo, para gerar um relatório para um intervalo de datas e status de conta específicos:| Filtro | O que faz |
|---|---|
createdAt: between ["2024-01-01", "2024-01-31"] | Inclui apenas registros de janeiro de 2024 |
status: in ["active", "pending"] | Inclui apenas contas ativas ou pendentes |
id: eq ["123", "456"] | Inclui apenas IDs de conta específicos |
Operadores de filtro suportados
| Operador | Descrição |
|---|---|
eq | Igual a |
gt / gte | Maior que / maior ou igual a |
lt / lte | Menor que / menor ou igual a |
between | O valor está dentro de um intervalo |
in / nin | O valor está / não está em uma lista |
Processamento
A geração de relatórios é assíncrona. Após enviar uma requisição, o Reporter retorna um ID de relatório que você usa para verificar o progresso. Os relatórios passam por dois status:| Status | Significado |
|---|---|
processing | O Reporter está consultando dados e renderizando a template |
finished | O relatório está pronto para download |
Baixar o resultado
Quando um relatório atinge o status
finished, faça o download. O arquivo é retornado no formato especificado durante o upload da template — CSV, XML, HTML, PDF ou TXT.
Fontes de dados
O Reporter se conecta aos seus bancos de dados e extrai dados com base no que suas templates referenciam. Ele suporta:
| Banco de dados | Caso de uso |
|---|---|
| PostgreSQL | Dados relacionais — contas, transações, lançamentos contábeis |
| MongoDB | Dados de documentos — metadados, esquemas flexíveis |
midaz_onboarding ou midaz_transaction).
Suporte multi-esquema
Para bancos de dados PostgreSQL com múltiplos esquemas, as templates podem consultar entre esquemas usando sintaxe explícita:sales, inventory e reporting dentro de um mesmo banco de dados.
Cenário de exemplo
Uma fintech precisa gerar um resumo diário de contas para seu time de operações. Configuração:
- Um designer de templates escreve uma template HTML com saldos de contas, contagens de transações e totais diários usando as tags de agregação do Reporter
- A template é carregada uma vez com formato de saída configurado como PDF
- Um job automatizado envia uma requisição de relatório com um filtro de data para o dia atual.
- O Reporter consulta o banco de dados do Midaz, aplica a lógica da template e renderiza o resultado.
- O relatório atinge o status
finishedem segundos. - O time de operações baixa o PDF e revisa o resumo diário.
- A mesma template é reutilizada todos os dias — apenas o filtro de data muda.
Relatórios regulatórios brasileiros
O Reporter inclui templates prontas para uso para relatórios regulatórios do Banco Central do Brasil (BACEN):
| Template | Finalidade |
|---|---|
| CADOC 4010 / 4016 | Balancete de verificação e relatórios de balanço patrimonial |
| CADOC 4111 | Relatórios detalhados de transações |
| CCS | Relatórios de cadastro de clientes e contas |
Próximos passos
O que é o Reporter?
Visão completa da arquitetura e capacidades do Reporter.
Formatos de templates
Exemplos práticos para templates HTML, XML e TXT.
Relatório de balancete
Guia completo para gerar balancetes com Midaz e Reporter.
Templates BACEN
Templates prontas para uso para relatórios regulatórios brasileiros.