> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Usando o Reporter > Gerencie templates do Reporter, gere relatórios regulatórios sob demanda, acompanhe o status deles e baixe os arquivos concluídos. 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](/pt/products/reporter/template-examples) e a [referência de template](/pt/products/reporter/template-reference). *** ## 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](/pt/reference/products/reporter/upload-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: * [Listar templates](/pt/reference/products/reporter/list-templates). * [Consultar detalhes do template](/pt/reference/products/reporter/retrieve-template-details). * [Atualizar um template](/pt/reference/products/reporter/update-templates). * [Excluir um template](/pt/reference/products/reporter/delete-template). 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](/pt/reference/products/reporter/create-report) 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: ```json theme={null} { "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: ```json theme={null} { "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](/pt/products/reporter/template-reference#advanced-filtering) 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](/pt/reference/products/reporter/list-data-sources) retorna uma página de conexões registradas sem credenciais. * [Consultar uma fonte de dados](/pt/reference/products/reporter/retrieve-data-source) 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](/pt/reference/products/reporter/check-report-status) 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`: 1. Chame [Baixar um relatório](/pt/reference/products/reporter/download-report) com `REPORT_ID`. 2. Confirme que a resposta tem o tipo de conteúdo esperado e o header `Content-Disposition`. 3. 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` | ```env theme={null} 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. ```env theme={null} 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 ``` ```env theme={null} 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) 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__*`: | Variável | Descrição | Obrigatória | | ---------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | `DATASOURCE__CONFIG_NAME` | Identificador usado nos templates, como `midaz_onboarding`. | Sim | | `DATASOURCE__HOST` | Host do banco de dados. | Sim | | `DATASOURCE__PORT` | Porta do banco de dados. | Sim | | `DATASOURCE__USER` | Usuário do banco de dados. | Apenas quando o banco de dados exige autenticação de usuário | | `DATASOURCE__PASSWORD` | Senha do banco de dados. | Apenas quando o banco de dados exige autenticação por senha | | `DATASOURCE__DATABASE` | Nome do banco de dados. | Sim | | `DATASOURCE__TYPE` | `postgresql` ou `mongodb`, em minúsculas. | Sim | | `DATASOURCE__SSLMODE` | Modo SSL do PostgreSQL, como `disable` ou `require`. | Apenas PostgreSQL | | `DATASOURCE__SSLROOTCERT` | Caminho do certificado raiz do PostgreSQL. | Apenas PostgreSQL | | `DATASOURCE__SSL` | Habilita o SSL do MongoDB. | Apenas MongoDB | | `DATASOURCE__SSLCA` | Caminho do certificado CA do MongoDB. | Apenas MongoDB | | `DATASOURCE__OPTIONS` | Opções adicionais da URI do MongoDB. | Apenas MongoDB | | `DATASOURCE__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`: ```env theme={null} 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`: ```django theme={null} {% 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`: ```env theme={null} 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: ```django theme={null} {% for order in external_db:sales.orders %} {{ order.id }} - {{ order.total }} {% endfor %} ``` ```json theme={null} { "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. *** ## Tarefas relacionadas * [Comece com o Reporter](/pt/products/reporter/reporter-quick-start) * [Conecte o Reporter ao Midaz](/pt/products/reporter/connecting-reporter-to-midaz) * [Crie templates](/pt/products/reporter/template-reference) * [Revise exemplos de template](/pt/products/reporter/template-examples)