> ## 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. # API REST do Reporter > Oriente-se na API do Reporter: o caminho base /v1, a autenticação bearer, as 28 operações agrupadas por função, idempotência, paginação e o formato de erro RFC 9457. O Reporter oferece uma única API HTTP. Toda operação fica sob o caminho base `/v1`, sem nenhum segmento de produto antes dele. Uma listagem de templates é `GET /v1/templates`. A API contém **28 operações** distribuídas em sete áreas: templates, o construtor de templates, relatórios, fontes de dados, prazos, métricas e o manifesto de streaming. Todas as 28 são renderizadas sob a âncora **Reporter** na [Referência da API](/pt/reference/introduction). Esta página cobre o que as operações têm em comum e indica a página de referência de cada uma. Os documentos OpenAPI deste portal são fontes de renderização para as páginas de referência. Eles não são contratos com o cliente, e não são uma base para geração de SDK. ## Autenticação *** O Reporter aceita um token bearer JWT. Um único esquema de segurança se aplica a toda operação: ```http theme={null} Authorization: Bearer ``` O Reporter autoriza cada requisição em relação à aplicação `reporter`, um recurso e uma ação. O recurso segue a área: `templates`, `reports`, `deadlines`, `data-source`, `metrics` ou `streaming`. A ação é o método HTTP em minúsculas, então `POST /v1/reports` autoriza como a ação `post` em `reports`. `PLUGIN_AUTH_ENABLED` ativa o middleware, e `PLUGIN_AUTH_ADDRESS` aponta para o Access Manager. As rotas de probe ficam fora da autenticação, para que um orquestrador as alcance sem um token: `/health`, `/readyz` e `/version`. A identidade do tenant viaja dentro do token. O Reporter resolve o tenant a partir da claim `tenantId` do JWT. Nenhuma das operações acima obtém o tenant de um header de requisição, e nenhum valor fornecido pelo cliente o sobrepõe. Consulte [Multi-tenancy](/pt/platform/multi-tenancy). ## As operações por função *** ### Templates Cinco operações controlam o ciclo de vida do template: [listar](/pt/reference/products/reporter/list-templates), [enviar](/pt/reference/products/reporter/upload-template), [obter](/pt/reference/products/reporter/retrieve-template-details), [atualizar](/pt/reference/products/reporter/update-templates) e [excluir](/pt/reference/products/reporter/delete-template). Um template é um arquivo `.tpl` em texto simples, além do seu formato de saída e descrição. Excluir um template também remove os prazos que apontam para ele. ### Construtor de templates Quatro operações sustentam um editor visual sem persistir nada. [Listar definições de bloco](/pt/reference/products/reporter/list-block-definitions) e [listar definições de filtro](/pt/reference/products/reporter/list-filter-definitions) retornam o catálogo do qual um editor se baseia. [Validar blocos](/pt/reference/products/reporter/validate-template-blocks) verifica uma árvore de blocos e relata erros por bloco. [Gerar código](/pt/reference/products/reporter/generate-template-code) transforma essa árvore em código-fonte de template que você pode então enviar. ### Relatórios Quatro operações: [criar](/pt/reference/products/reporter/create-report), [obter](/pt/reference/products/reporter/check-report-status), [listar](/pt/reference/products/reporter/retrieve-reports) e [baixar](/pt/reference/products/reporter/download-report). O ciclo de vida é **criar e reter**. `POST /v1/reports` responde `201` com um relatório em `Processing` e passa o trabalho para um worker em segundo plano. O relatório então chega a `Finished`, `Partial` ou `Error`. Consulte repetidamente a operação de obtenção, ou inscreva-se nos eventos descritos em [Eventos](/pt/products/reporter/reporter-events). O download serve um relatório em `Finished`. Todo relatório que você cria permanece endereçável pelo seu identificador enquanto a política de retenção do seu armazenamento de objetos mantiver o artefato. ### Fontes de dados Sete operações gerenciam o registro persistido em `/v1/data-sources` (note o hífen). Você pode listar ou criar entradas, obter, atualizar parcialmente ou excluir de forma lógica uma por `dataSourceId`, inspecionar seu schema ativo e testar sua conexão. As senhas são apenas para escrita, criptografadas em repouso e ausentes de toda resposta. Uma exclusão é recusada enquanto um template ativo ainda referenciar a fonte de dados. Deploys single-tenant podem popular entradas do registro a partir de variáveis `DATASOURCE_*` na inicialização. Deploys multi-tenant as criam por tenant através da API. ### Prazos Seis operações modelam uma obrigação de entrega com uma data de vencimento e uma regra de recorrência: [listar](/pt/reference/products/reporter/retrieve-deadlines), [criar](/pt/reference/products/reporter/create-deadline), [atualizar](/pt/reference/products/reporter/update-deadline), [excluir](/pt/reference/products/reporter/delete-deadline), [entregar](/pt/reference/products/reporter/deliver-deadline) e [notificações](/pt/reference/products/reporter/retrieve-deadline-notifications). O status é derivado da data de vencimento e da marca de entrega, nunca enviado por um cliente. As notificações são apenas por consulta: a operação retorna os prazos dentro da sua janela de alerta, ordenados com os vencidos primeiro. ### Métricas e streaming [Métricas](/pt/reference/products/reporter/get-metrics) retorna contadores do deploy: templates, relatórios, fontes de dados e erros de relatório da janela atual em comparação com a anterior. `errorPeriodDays` define essa janela e usa 7 como padrão. [Eventos de streaming](/pt/reference/products/reporter/get-streaming-events) retorna o manifesto de eventos abordado em [Eventos](/pt/products/reporter/reporter-events). ## Tipos de conteúdo *** A criação e a atualização de template são `multipart/form-data`: uma parte de arquivo `template`, além de `outputFormat` e `description`. Todo o restante que carrega um corpo é `application/json`. O download responde com os bytes e um nome de arquivo `Content-Disposition`. O tipo de mídia segue o formato de saída do relatório: `application/pdf`, `application/xml`, `text/csv`, `text/html` ou `text/plain`. ## Idempotência *** A criação de template e a criação de relatório aceitam um header de requisição `X-Idempotency`. Envie sua própria chave, ou omita o header e o Reporter deriva uma a partir de um hash do corpo da requisição. * Uma requisição que repete uma que ainda está em andamento é rejeitada em vez de duplicada. * Uma requisição que repete uma já concluída reproduz a resposta original e marca `X-Idempotency-Replayed: true` nela. ## Paginação *** As listagens de templates, prazos e fontes de dados usam paginação por offset com os mesmos dois parâmetros. | Parâmetro | Padrão | Regras | | --------- | ------ | --------------------------------------------------------------------------- | | `page` | `1` | Número da página. | | `limit` | `10` | Itens por página. O teto é `MAX_PAGINATION_LIMIT`, que usa 100 como padrão. | Um `limit` acima do teto é rejeitado com um erro de paginação, em vez de ser limitado automaticamente. A listagem de relatórios usa paginação por keyset: envie `limit` sem `page` e, em seguida, siga `nextCursor` ou `prevCursor` a partir da resposta. Um cursor fica ausente quando não há página naquela direção, e a resposta não inclui `page` nem `total`. A listagem de relatórios aceita `status`, `template_id`, `created_at` e `sort_order`. O cursor carrega a ordenação para o percurso. A listagem de templates filtra por `outputFormat`, e a listagem de prazos por `status`. ## Erros *** Todo erro responde `application/problem+json` e segue a [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457), carregando um `title`, um `status`, um `detail` e um `code` de domínio estável. Faça a correspondência pelo código, nunca pelo texto. A [lista de erros do Reporter](/pt/reference/products/reporter/reporter-error-list) mapeia cada código para seu status HTTP e sua correção. ## Lendo a especificação a partir de um serviço em execução *** `SWAGGER_ENABLED=true` monta uma referência navegável em `/swagger/docs`, com o documento OpenAPI 3.1 em `/swagger/openapi.json` e `/swagger/openapi.yaml`. Ela fica desativada a menos que você a ative. Mantenha-a desativada em produção. ## Próximos passos *** As 28 operações, com os formatos completos de requisição e resposta. Envie um template, gere um relatório e baixe-o com cURL. Inscreva-se em eventos de relatório e prazo em vez de consultar repetidamente. Templates, relatórios, fontes de dados e onde eles se encaixam.