> ## 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: a rota base /v1, a autenticação bearer, as 23 operações agrupadas por tarefa, a idempotência, a paginação e o formato de erro RFC 9457. O Reporter serve uma única API HTTP. Toda operação fica sob a rota base `/v1`, sem nenhum segmento de produto à frente. Uma listagem de templates é `GET /v1/templates`. A API reúne **23 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. As 23 são renderizadas sob a âncora **Reporter** da [Referência de API](/pt/reference/introduction). Esta página é o mapa, não o território. Ela cobre o que as operações têm em comum e aponta para 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 de cliente nem uma base para gerar SDK. ## Autenticação *** O Reporter aceita um token JWT bearer. Um único esquema de segurança se aplica a todas as operações: ```http theme={null} Authorization: Bearer ``` O Reporter autoriza cada requisição contra a aplicação `reporter`, um recurso e uma ação. O recurso acompanha 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` é autorizado como a ação `post` sobre `reports`. `PLUGIN_AUTH_ENABLED` liga o middleware, e `PLUGIN_AUTH_ADDRESS` o aponta para o Access Manager. As rotas de sondagem ficam fora da autenticação para que um orquestrador as alcance sem 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 toma um tenant de um cabeçalho de requisição, e nenhum valor enviado pelo cliente o sobrescreve. Veja [Multi-tenancy](/pt/multi-tenancy). ## As operações por tarefa *** ### Templates Cinco operações são donas do ciclo de vida de um template: [listar](/pt/reference/reporter/list-templates), [enviar](/pt/reference/reporter/upload-template), [obter](/pt/reference/reporter/retrieve-template-details), [atualizar](/pt/reference/reporter/update-templates) e [excluir](/pt/reference/reporter/delete-template). Um template é um arquivo `.tpl` de texto puro, mais o seu formato de saída e a sua descrição. Excluir um template remove também 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/reporter/list-block-definitions) e [listar definições de filtro](/pt/reference/reporter/list-filter-definitions) retornam o catálogo de que um editor se alimenta. [Validar blocos](/pt/reference/reporter/validate-template-blocks) confere uma árvore de blocos e reporta os erros de cada bloco. [Gerar código](/pt/reference/reporter/generate-template-code) transforma essa árvore em código-fonte de template que você pode enviar em seguida. ### Relatórios Quatro operações, e apenas quatro: [criar](/pt/reference/reporter/create-report), [obter](/pt/reference/reporter/check-report-status), [listar](/pt/reference/reporter/retrieve-reports) e [baixar](/pt/reference/reporter/download-report). O ciclo de vida é **criar e reter**. `POST /v1/reports` responde `201` com um relatório em `Processing` e entrega o trabalho a um worker em segundo plano. O relatório então chega a `Finished`, `Partial` ou `Error`. Consulte a operação de obtenção por sondagem, ou assine os eventos descritos em [Eventos](/pt/reporter/reporter-events). O download serve um relatório em `Finished`. Todo relatório que você cria continua endereçável pelo identificador dele enquanto a política de retenção do seu object storage guardar o artefato. ### Fontes de dados Duas operações de leitura: [listar](/pt/reference/reporter/list-data-sources) e [obter uma](/pt/reference/reporter/retrieve-data-source), ambas sob `/v1/data-sources` — repare no hífen. Um operador registra fontes de dados por variáveis de ambiente, então essas operações informam o que o deployment já tem e não expõem nenhum caminho de escrita. ### Prazos Seis operações modelam uma obrigação de entrega com uma data de vencimento e uma regra de recorrência: [listar](/pt/reference/reporter/retrieve-deadlines), [criar](/pt/reference/reporter/create-deadline), [atualizar](/pt/reference/reporter/update-deadline), [excluir](/pt/reference/reporter/delete-deadline), [entregar](/pt/reference/reporter/deliver-deadline) e [notificações](/pt/reference/reporter/retrieve-deadline-notifications). O status é derivado da data de vencimento e da marca de entrega, e nunca é enviado por um cliente. As notificações são apenas de consulta: a operação retorna os prazos que estão dentro da janela de alerta deles, ordenados com os vencidos primeiro. ### Métricas e streaming [Métricas](/pt/reference/reporter/get-metrics) retorna os contadores do deployment — templates, relatórios, fontes de dados e erros de relatório da janela atual em relação à anterior. `errorPeriodDays` define essa janela e vale 7 por padrão. [Eventos de streaming](/pt/reference/reporter/get-streaming-events) retorna o manifesto de eventos coberto em [Eventos](/pt/reporter/reporter-events). ## Tipos de conteúdo *** A criação e a atualização de templates usam `multipart/form-data`: uma parte de arquivo `template`, mais `outputFormat` e `description`. Todo o resto que carrega corpo usa `application/json`. O download responde com os bytes e um nome de arquivo em `Content-Disposition`. O tipo de mídia acompanha 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 cabeçalho de requisição `X-Idempotency`. Envie a sua própria chave, ou omita o cabeçalho e o Reporter deriva uma a partir de um hash do corpo da requisição. * Uma requisição que repete outra ainda em andamento é rejeitada em vez de duplicada. * Uma requisição que repete outra já concluída reproduz a resposta original e a marca com `X-Idempotency-Replayed: true`. ## Paginação *** As operações de listagem usam paginação por deslocamento 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 por padrão vale 100. | Um `limit` acima do teto é rejeitado com um erro de paginação, em vez de ser cortado. A lista de relatórios também aceita um parâmetro `cursor`, que carrega a posição da página anterior no lugar de um número de página. A listagem de relatórios acrescenta filtros por cima: `status`, `template_id`, `output_format`, `description`, `type`, `active`, uma janela `start_date`/`end_date` e `sort_order`, que vale `desc` por padrão. A listagem de templates filtra por `outputFormat`, e a de prazos por `status`. ## Erros *** Todo erro responde `application/problem+json` e segue a [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457), com um `title`, um `status`, um `detail` e um `code` de domínio estável. Faça a sua lógica casar com o código, nunca com o texto. A [lista de erros do Reporter](/pt/reference/reporter/reporter-error-list) mapeia cada código para o status HTTP dele e para a correção. ## Ler a especificação 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 desligada a menos que você a ligue. Mantenha-a desligada em produção. ## Próximos passos *** As 23 operações, com os formatos completos de requisição e resposta. Envie um template, gere um relatório e baixe-o com cURL. Assine os eventos de relatório e de prazo em vez de fazer sondagem. Templates, relatórios, fontes de dados e onde eles se encaixam.