> ## 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](https://docs.lerian.studio/pt/products/reporter/template-examples.md) e a [referência de template](https://docs.lerian.studio/pt/products/reporter/template-reference.md). *** ## 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](https://docs.lerian.studio/pt/reference/products/reporter/upload-template.md) como uma requisição multipart com os quatro 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. * `category`: a família do relatório, como `cadoc`. Use letras minúsculas, dígitos, sublinhados e hifens, com até 100 caracteres. 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](https://docs.lerian.studio/pt/reference/products/reporter/list-templates.md). * [Consultar detalhes do template](https://docs.lerian.studio/pt/reference/products/reporter/retrieve-template-details.md). * [Atualizar um template](https://docs.lerian.studio/pt/reference/products/reporter/update-templates.md). * [Excluir um template](https://docs.lerian.studio/pt/reference/products/reporter/delete-template.md). 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](https://docs.lerian.studio/pt/reference/products/reporter/create-report.md) 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](https://docs.lerian.studio/pt/products/reporter/template-reference.md#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](https://docs.lerian.studio/pt/reference/products/reporter/list-data-sources.md) retorna uma página de conexões registradas sem credenciais. * [Consultar uma fonte de dados](https://docs.lerian.studio/pt/reference/products/reporter/retrieve-data-source.md) retorna a configuração de uma conexão pelo `dataSourceId`. As credenciais permanecem ocultas. * [Obter o esquema de uma fonte de dados](https://docs.lerian.studio/pt/reference/products/reporter/get-data-source-schema.md) 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. Um deploy self-hosted também pode popular entradas a partir das variáveis `DATASOURCE_*` na inicialização. *** ## Interpretar status e erros dos relatórios Chame [Verificar status do relatório](https://docs.lerian.studio/pt/reference/products/reporter/check-report-status.md) 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 relatórios `Finished` e `Final`, e um `Draft` sem campo obrigatório em branco, como disponíveis 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](https://docs.lerian.studio/pt/reference/products/reporter/download-report.md) 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. *** ## Solução de problemas | Sintoma | Verificação | | - | - | | O envio do template é rejeitado | Envie `template`, `outputFormat`, `description` e `category`, 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 para relatórios `Finished` e `Final`, e para um `Draft` sem campo obrigatório em branco. | *** ## 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` | > [accordion] AWS S3 > > ```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 > ``` > [!WARNING] > > Os exemplos de MinIO e SeaweedFS abaixo usam HTTP apenas para desenvolvimento local. Deployments de produção exigem HTTPS e TLS. > [accordion] MinIO (desenvolvimento local) > > ```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 > ``` > [accordion] SeaweedFS (desenvolvimento local) > > ```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 > ``` > [!NOTE] > > 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 e o Worker falham na 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. Em um deploy self-hosted, você também 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__SSLCA_BASE64` | Base64 padrão de um pacote CA em PEM, como alternativa ao caminho de um arquivo de certificado. Para PostgreSQL, defina `SSLMODE` como `verify-ca` ou `verify-full`, ou deixe-o vazio para `verify-full`. | Não | | `DATASOURCE__OPTIONS` | Opções adicionais da URI do MongoDB. | Apenas MongoDB | | `DATASOURCE__ROW_CEILING` | Linhas que uma tabela pode retornar. O padrão é `DATASOURCE_DEFAULT_ROW_CEILING`. | Não | | `DATASOURCE__QUERY_TIMEOUT_SEC` | Timeout da consulta, em segundos. O padrão é `DATASOURCE_DEFAULT_QUERY_TIMEOUT_SEC`. | Não | | `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 e o Worker conectam a uma fonte de dados sob demanda, quando uma requisição precisa dela. *** ## Tarefas relacionadas * [Comece com o Reporter](https://docs.lerian.studio/pt/products/reporter/reporter-quick-start.md) * [Conecte o Reporter ao Midaz](https://docs.lerian.studio/pt/products/reporter/connecting-reporter-to-midaz.md) * [Crie templates](https://docs.lerian.studio/pt/products/reporter/template-reference.md) * [Revise exemplos de template](https://docs.lerian.studio/pt/products/reporter/template-examples.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.