> ## 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. # Conceitos essenciais do Reporter > O modelo do Reporter em um só lugar: templates, fontes de dados, relatórios, prazos, os quatro estados de relatório e o limite de tenant que os separa. O Reporter tem um modelo pequeno. Você envia um **template** que descreve um documento. Um operador configura as **fontes de dados** que o Reporter pode ler. Você solicita um **relatório** com base em um template, e o Reporter renderiza um artefato que você baixa. Um **prazo** acompanha quando um relatório vence e se alguém o entregou. Esta página define cada termo e as regras que os conectam. ## O modelo em resumo *** | Conceito | Definição | | -------------- | ------------------------------------------------------------------------------------------------------------------------- | | Template | Uma definição de documento em texto simples, enviada como arquivo, que declara um formato de saída. | | Fonte de dados | Uma conexão de banco de dados persistente e somente leitura que um operador gerencia pela API ou popula na inicialização. | | Relatório | Uma renderização de um template, segundo os filtros solicitados. | | Artefato | O arquivo que um relatório concluído produz, armazenado no armazenamento de objetos. | | Filtro | Uma condição por campo que restringe as linhas que um relatório lê. | | Prazo | Uma data de vencimento e uma regra de recorrência, opcionalmente vinculada a um template. | | Tenant | O limite de isolamento. Cada operação resolve exatamente um. | ## Templates *** Um template é um arquivo `.tpl` em texto simples que você envia como `multipart/form-data`, junto com o formato de saída que ele produz e uma breve descrição. O Reporter guarda o arquivo no armazenamento de objetos e seus metadados no MongoDB. A linguagem do template é Pongo2, então um template mistura texto literal do documento com variáveis, loops, condicionais, filtros e tags de agregação. Um template declara um formato de saída: `PDF`, `HTML`, `XML`, `TXT` ou `CSV`. O PDF é renderizado primeiro como HTML e depois convertido por um pool de navegadores headless. Um template endereça dados pelo `configName`, o nome estável de uma fonte de dados, e pela tabela: `{{ midaz_onboarding.accounts }}`. Quando mais de um schema está em jogo, qualifique como `{{ midaz_onboarding:public.accounts }}`. No envio, o Reporter lê o texto do template e deriva os campos que ele toca, por fonte de dados e por tabela. Em seguida, verifica cada tabela e campo referenciados contra o schema ativo dessa fonte de dados. Uma fonte de dados inacessível gera um aviso em vez de uma rejeição, então um template ainda é enviado enquanto um banco de dados está fora do ar. Leia [Referência de template](/pt/products/reporter/template-reference) para as tags, filtros e expressões que a linguagem oferece. ## Fontes de dados *** Uma fonte de dados é uma conexão PostgreSQL ou MongoDB armazenada no registro do Reporter. A API cria e gerencia as entradas do registro. Um deployment single-tenant também pode populá-las a partir de variáveis `DATASOURCE_*` na inicialização. A extração de dados permanece somente leitura por construção: o Reporter emite instruções `SELECT` e finds do MongoDB, e não tem caminho de escrita para o banco de dados de origem. Cada entrada tem dois identificadores. O `dataSourceId` é o UUID que as operações do registro usam. O `configName` é o nome estável que templates e filtros usam, então mantenha-o estável enquanto hosts e credenciais mudam. O Reporter criptografa senhas em repouso com `DATASOURCE_CRED_ENC_KEY` e nunca as retorna. O registro expõe sete operações: listar, criar, obter, atualizar parcialmente, fazer exclusão reversível, inspecionar o schema ativo e testar a conexão. O Reporter recusa a exclusão enquanto um template ativo ainda referenciar a fonte. Leia [Conectando o Reporter ao Midaz](/pt/products/reporter/connecting-reporter-to-midaz) para uma configuração completa. ## Relatórios *** Uma requisição de relatório nomeia um template e, opcionalmente, os filtros que restringem os dados por trás dele. Os filtros aninham três níveis (fonte de dados, depois tabela, depois campo), e cada campo carrega uma condição: ```json theme={null} { "templateId": "0198c0f6-6d4d-7a34-a9ba-2c2b3ad2f1a0", "filters": { "midaz_onboarding": { "accounts": { "status": { "in": ["ACTIVE"] }, "type": { "nin": ["internal"] } } } } } ``` Existem oito operadores: `eq`, `gt`, `gte`, `lt`, `lte`, `between`, `in` e `nin`. Um relatório mantém sua própria cópia do formato de saída e da descrição que o template carregava no momento da criação. Esse snapshot é o motivo pelo qual um artefato continua disponível para download no formato original depois que o template muda. Relatórios seguem o modelo criar-e-reter. Existem quatro operações: criar um, obtê-lo pelo identificador, listá-los e baixar o artefato de um relatório concluído. Um relatório e seu artefato permanecem no lugar depois de criados. A retenção é uma política de ciclo de vida no bucket de armazenamento de objetos, definida por quem opera o deployment. ### Os quatro estados de um relatório A criação é síncrona apenas até o trabalho chegar à fila. A operação `POST` responde `201 Created` com um relatório já em `Processing`, e um worker assume a partir daí. | Estado | Significado | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `Processing` | Aceito e enfileirado. O worker ainda não terminou. | | `Finished` | Toda seção de dados teve sucesso e o artefato está armazenado. | | `Partial` | Algumas seções de dados falharam. O relatório registra quais, por seção, para que você corrija essas fontes de dados e gere o relatório de novo. | | `Error` | Toda seção tentada falhou, ou a requisição nunca chegou ao worker. | `Processing` é o único estado de entrada, e nada retorna a ele depois que o worker consolida o relatório. Uma fila pode entregar o mesmo comando duas vezes, então o worker lê o relatório antes de iniciar uma execução. O worker pula um relatório que já se consolidou como `Finished` ou `Error`, e não o gera de novo. A operação de download serve o artefato assim que um relatório está `Finished`. Faça polling em `GET /v1/reports/{id}` até o estado se consolidar, ou inscreva-se nos eventos terminais que o Reporter emite e dispense o polling. ## Prazos *** Um prazo modela uma obrigação: uma data de vencimento, uma regra de recorrência e, opcionalmente, o template que a cumpre. Seu `type` é `regulatory` ou `custom`. Sua `frequency` é `once`, `daily`, `weekly`, `monthly`, `semiannual` ou `annual`, e as regras semianual e anual também carregam os meses em que caem. O Reporter deriva o status e nunca o armazena. Um prazo fica `delivered` assim que alguém o marca assim, `overdue` assim que a data de vencimento passa sem entrega, e `pending` nos demais casos. Um prazo recorrente avança na primeira leitura depois que sua data de vencimento passa. Ele avança apenas quando carrega a marca de entrega. Esse avanço limpa a marca de entrega, então o registro volta a `pending` para a próxima ocorrência, e um único registro carrega toda a série. A notificação é por consulta. Uma única operação retorna os prazos dentro da janela de alerta deles, ordenados com os vencidos primeiro, depois os de aviso, depois os informativos. O Reporter não envia e-mail nem chama nenhum endpoint seu. Leia [Gerenciando prazos](/pt/products/reporter/managing-deadlines) para o ciclo de vida completo. ## Tenants *** O tenant é o limite de isolamento no Reporter. O Reporter o resolve a partir da própria requisição autenticada. O bearer token que autoriza a chamada carrega o tenant na claim `tenantId`. Nenhuma operação da API obtém o tenant de um header de requisição, e nenhum valor fornecido pelo cliente pode ampliar o escopo de uma chamada. O isolamento percorre toda a profundidade da stack. Cada tenant recebe seu próprio banco de dados de metadados, seu próprio virtual host do message broker, seus próprios pools de conexão e seu próprio outbox de eventos. A resolução é fail-closed. O Reporter rejeita uma requisição quando não consegue resolver o tenant, e nada recorre a um pool compartilhado. A operação single-tenant é o padrão e não exige nenhuma configuração de tenant. Veja [Multi-tenancy](/pt/platform/multi-tenancy) para o modelo da plataforma. ## Próximos passos *** Um binário, duas superfícies e a fila entre elas. Envie um template e gere seu primeiro relatório. As tags, filtros e expressões disponíveis para um template. Crie, acompanhe e entregue uma obrigação de relatório.