> ## 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 centrais do Reporter > O modelo do Reporter em um só lugar: templates, fontes de dados, relatórios, prazos, os quatro estados de um relatório e a fronteira de tenant que os separa. O Reporter tem um modelo pequeno. Você sobe um **template** que descreve um documento. Um operador configura as **fontes de dados** que o Reporter pode ler. Você pede um **relatório** contra um template, e o Reporter renderiza um artefato que você baixa. Um **prazo** registra quando um relatório vence e se alguém o entregou. Esta página define cada substantivo e as regras que os conectam. ## O modelo em resumo *** | Conceito | Definição | | -------------- | ------------------------------------------------------------------------------------------------ | | Template | Uma definição de documento em texto puro, enviada como arquivo, que declara um formato de saída. | | Fonte de dados | Um banco de dados somente leitura que um operador registra por configuração. | | Relatório | Uma renderização de um template, sob os filtros que você pediu. | | Artefato | O arquivo que um relatório concluído produz, guardado em object storage. | | 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 ligada a um template. | | Tenant | A fronteira de isolamento. Toda operação resolve exatamente um. | ## Templates *** Um template é um arquivo `.tpl` de texto puro que você envia como `multipart/form-data`, junto com o formato de saída que ele produz e uma descrição curta. O Reporter guarda o arquivo em object storage e os metadados dele no MongoDB. A linguagem de template é a Pongo2, então um template mistura texto literal do documento com variáveis, laços, condicionais, filtros e tags de agregação. Um template declara um único formato de saída: `PDF`, `HTML`, `XML`, `TXT` ou `CSV`. O PDF é renderizado primeiro como HTML e depois convertido por um pool de workers com navegador headless. Um template endereça os dados por `configName`, o nome estável de uma fonte de dados, e por tabela: `{{ midaz_onboarding.accounts }}`. Quando há mais de um esquema em jogo, qualifique assim: `{{ 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 confere cada tabela e cada campo referenciado contra o esquema ao vivo daquela fonte de dados. Uma fonte de dados inalcançável produz um aviso em vez de uma recusa, então um template ainda sobe enquanto um banco de dados está fora do ar. Leia [Referência de templates](/pt/reporter/template-reference) para as tags, os filtros e as expressões que a linguagem oferece. ## Fontes de dados *** Uma fonte de dados é um banco de dados que o Reporter lê, registrado inteiramente por configuração de ambiente. O Reporter se conecta a PostgreSQL e a MongoDB. O acesso é somente leitura por construção: o caminho de extração emite comandos `SELECT` e buscas no MongoDB, e não existe caminho de escrita para uma fonte de dados. `DATASOURCE__CONFIG_NAME` é a variável que faz uma fonte de dados existir. O valor dela é o `configName` que templates e filtros usam, e ele permanece estável enquanto hosts e credenciais mudam ao redor. O resto do bloco fornece a conexão em si. A superfície de API sobre as fontes de dados também é somente leitura. Você pode listar as fontes configuradas e obter uma pelo identificador, que é como você confirma que uma implantação enxerga a fonte que um template espera. Não há operação de criação, atualização ou exclusão, porque essa decisão pertence ao ambiente. Leia [Conectar o Reporter ao Midaz](/pt/reporter/connecting-reporter-to-midaz) para uma configuração trabalhada. ## 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 guarda a própria cópia do formato de saída e da descrição que o template carregava quando o relatório foi criado. Esse snapshot é o motivo pelo qual um artefato continua disponível para download no formato original depois que o template segue adiante. Relatórios são criados e retidos. Existem quatro operações: criar um, obtê-lo pelo identificador, listá-los e baixar o artefato de um concluído. Um relatório e o artefato dele permanecem no lugar depois de criados; a retenção é uma política de ciclo de vida no bucket de object storage, definida por quem opera a implantação. ### Os quatro estados de um relatório A criação é síncrona apenas até o ponto em que o trabalho entra na fila. O `POST` responde `201 Created` com um relatório já em `Processing`, e um worker assume dali em diante. | Estado | Significado | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `Processing` | Aceito e enfileirado. O worker ainda não terminou. | | `Finished` | Todas as seções de dados tiveram 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` | Todas as seções tentadas falharam, ou a requisição nunca chegou ao worker. | `Processing` é o único estado de entrada, e nada volta para ele depois que o worker acomoda o relatório. Uma fila pode entregar o mesmo comando duas vezes, então o worker lê o relatório antes de começar uma execução: um que já ficou em `Finished` ou `Error` é deixado como está, em vez de gerado de novo. A operação de download serve o artefato quando um relatório está em `Finished`. Consulte `GET /v1/reports/{id}` periodicamente até o estado se acomodar, ou assine os eventos terminais que o Reporter emite e dispense a consulta repetida. ## Prazos *** Um prazo modela uma obrigação: uma data de vencimento, uma regra de recorrência e, opcionalmente, o template que a cumpre. O `type` dele é `regulatory` ou `custom`. A `frequency` dele é `once`, `daily`, `weekly`, `monthly`, `semiannual` ou `annual`, e as regras semestral e anual também carregam os meses em que caem. O status é derivado, nunca armazenado. Um prazo fica `delivered` assim que alguém o marca como tal, `overdue` assim que a data de vencimento passa sem entrega, e `pending` nos demais casos. Um prazo recorrente avança na primeira leitura depois de a data de vencimento passar, e só se ele tiver sido marcado como entregue. Esse avanço limpa a marca de entrega, então o registro volta para `pending` na próxima ocorrência e um único registro carrega a série inteira. A notificação é por consulta. Uma única operação retorna os prazos que estão dentro da janela de alerta deles, ordenados primeiro os vencidos, depois os de aviso e depois os informativos. O Reporter não envia e-mail nem chama nenhum endpoint seu. Leia [Gerenciando prazos](/pt/reporter/managing-deadlines) para o ciclo de vida completo. ## Tenants *** O tenant é a fronteira de isolamento no Reporter. O Reporter o resolve a partir da própria requisição autenticada — o token bearer que autoriza a chamada carrega o tenant na claim `tenantId` dele. Nenhuma operação da API toma um tenant de um cabeçalho 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 o próprio banco de metadados, o próprio virtual host no broker de mensagens, os próprios pools de conexão e o próprio outbox de eventos. A resolução é fail-closed: uma requisição cujo tenant não pode ser resolvido é recusada, e nada cai de volta para um pool compartilhado. A operação com um único tenant é o padrão e não precisa de nenhuma configuração de tenant. Veja [Multi-tenancy](/pt/multi-tenancy) para o modelo de toda a 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, os filtros e as expressões disponíveis para um template. Crie, acompanhe e entregue uma obrigação de reporte.