> ## 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. # Usar o Reporter > Gerencie templates, gere relatórios, acompanhe o status e baixe arquivos concluídos com 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](/pt/reporter/template-examples) e a [referência de templates](/pt/reporter/template-reference). *** ## 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](/pt/reference/reporter/upload-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: * [Listar templates](/pt/reference/reporter/list-templates). * [Consultar os detalhes de um template](/pt/reference/reporter/retrieve-template-details). * [Atualizar um template](/pt/reference/reporter/update-templates). * [Excluir um template](/pt/reference/reporter/delete-template). 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](/pt/reference/reporter/create-report) 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: ```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`. Guarde esse valor como `REPORT_ID` para consultar o status da geração e recuperar o resultado. Consulte [Filtragem avançada](/pt/reporter/template-reference#filtragem-avancada) 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](/pt/reference/reporter/list-data-sources) retorna as fontes disponíveis, seus schemas e suas tabelas. * [Consultar uma fonte de dados](/pt/reference/reporter/retrieve-data-source) 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](/pt/reference/reporter/check-report-status) 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`: 1. Chame [Baixar um relatório](/pt/reference/reporter/download-report) com `REPORT_ID`. 2. Confirme se 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 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` | ```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 a seguir usam HTTP apenas para desenvolvimento local. Deploys 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 é compatível com TTL por objeto. Configure [políticas de ciclo de vida do bucket 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 cada fonte PostgreSQL ou MongoDB com variáveis de ambiente `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. | Somente quando o banco exige autenticação por usuário | | `DATASOURCE__PASSWORD` | Senha do banco de dados. | Somente quando o banco exige autenticação por senha | | `DATASOURCE__DATABASE` | Nome do banco de dados. | Sim | | `DATASOURCE__TYPE` | `postgresql` ou `mongodb`, em letras 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 SSL no 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` | 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`: ```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 fonte em um template pelo `CONFIG_NAME`: ```django theme={null} {% 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`: ```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 chave da tabela nos filtros: ```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 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. *** ## Tarefas relacionadas * [Começar a usar o Reporter](/pt/reporter/reporter-quick-start) * [Conectar o Reporter ao Midaz](/pt/reporter/connecting-reporter-to-midaz) * [Criar templates](/pt/reporter/template-reference) * [Consultar exemplos de templates](/pt/reporter/template-examples)