> ## 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 61 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 61 operações distribuídas em nove áreas: templates, o construtor de templates, relatórios, fontes de dados, prazos, instituições, remessa regulatória, métricas e o manifesto de streaming. Todas as 61 são renderizadas sob a âncora **Reporter** na [Referência da API](https://docs.lerian.studio/pt/reference/introduction.md). Esta página cobre o que as operações têm em comum e indica a página de referência de cada uma. > [!NOTE] > > 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`, `institutions`, `regulatory`, `metrics` ou `streaming`. Aprovar um rascunho regulatório autoriza contra um recurso próprio, `regulatory-approval`. A ação é o método HTTP em minúsculas, então `POST /v1/reports` autoriza como a ação `post` em `reports`. Duas operações `POST` autorizam como a ação `put` em `regulatory`: o preview do mapeamento e o reinício do mapeamento. `PLUGIN_AUTH_ENABLED` ativa o middleware, e `PLUGIN_AUTH_ADDRESS` aponta para o Access Manager. A porta da API serve duas rotas de probe fora da autenticação, para que um orquestrador as alcance sem um token: `/health` e `/version`. A readiness fica na porta de health, `HEALTH_PORT`. 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. ## As operações por função *** ### Templates Nove operações controlam o ciclo de vida do template: [listar](https://docs.lerian.studio/pt/reference/products/reporter/list-templates.md), [enviar](https://docs.lerian.studio/pt/reference/products/reporter/upload-template.md), [obter](https://docs.lerian.studio/pt/reference/products/reporter/retrieve-template-details.md), [obter o conteúdo](https://docs.lerian.studio/pt/reference/products/reporter/get-template-content.md), [atualizar](https://docs.lerian.studio/pt/reference/products/reporter/update-templates.md), [excluir](https://docs.lerian.studio/pt/reference/products/reporter/delete-template.md) e [pré-visualizar](https://docs.lerian.studio/pt/reference/products/reporter/preview-template.md), além de [listar famílias de relatório](https://docs.lerian.studio/pt/reference/products/reporter/list-report-families.md) e [atribuir uma família de relatório](https://docs.lerian.studio/pt/reference/products/reporter/assign-report-family.md). Um template é um arquivo `.tpl` em texto simples, além do seu formato de saída, descrição e categoria. 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](https://docs.lerian.studio/pt/reference/products/reporter/list-block-definitions.md) e [listar definições de filtro](https://docs.lerian.studio/pt/reference/products/reporter/list-filter-definitions.md) retornam o catálogo do qual um editor se baseia. [Validar blocos](https://docs.lerian.studio/pt/reference/products/reporter/validate-template-blocks.md) verifica uma árvore de blocos e relata erros por bloco. [Gerar código](https://docs.lerian.studio/pt/reference/products/reporter/generate-template-code.md) transforma essa árvore em código-fonte de template que você pode então enviar. ### Relatórios Quatro operações: [criar](https://docs.lerian.studio/pt/reference/products/reporter/create-report.md), [obter](https://docs.lerian.studio/pt/reference/products/reporter/check-report-status.md), [listar](https://docs.lerian.studio/pt/reference/products/reporter/retrieve-reports.md) e [baixar](https://docs.lerian.studio/pt/reference/products/reporter/download-report.md). 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`, e uma remessa regulatória chega a `Draft` em vez de `Finished`. Consulte repetidamente a operação de obtenção, ou inscreva-se nos eventos descritos em [Eventos](https://docs.lerian.studio/pt/products/reporter/reporter-events.md). O download serve um relatório em `Finished` ou `Final`, e um `Draft` apenas quando nenhum campo obrigatório está em branco. O cabeçalho de resposta `X-Report-Status` indica o status que você recebeu. 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. Um deploy self-hosted também pode popular entradas do registro a partir de variáveis `DATASOURCE_*` na inicialização. ### Instituições Seis operações registram as instituições financeiras para as quais um tenant reporta: [listar](https://docs.lerian.studio/pt/reference/products/reporter/list-institutions.md), [criar](https://docs.lerian.studio/pt/reference/products/reporter/create-institution.md), [obter](https://docs.lerian.studio/pt/reference/products/reporter/get-institution.md), [substituir](https://docs.lerian.studio/pt/reference/products/reporter/replace-institution.md), [excluir](https://docs.lerian.studio/pt/reference/products/reporter/delete-institution.md) e [propor a partir do Midaz](https://docs.lerian.studio/pt/reference/products/reporter/propose-institutions.md). Uma instituição tem um CNPJ e um escopo que nomeia as linhas dela em cada fonte de dados. Uma requisição de relatório nomeia a instituição para a qual lê. Quando o tenant tem várias instituições, uma requisição que não nomeia nenhuma é recusada. Substituir exige `If-Match` com a versão que você leu. ### Remessa regulatória Vinte e três operações executam o ciclo de remessa dos documentos regulatórios curados que um deployment carrega: * **Catálogo**: [listar documentos](https://docs.lerian.studio/pt/reference/products/reporter/list-regulatory-documents.md), [obter um documento](https://docs.lerian.studio/pt/reference/products/reporter/get-regulatory-document.md) e [obter o contrato dele](https://docs.lerian.studio/pt/reference/products/reporter/get-document-contract.md), que lista todos os campos de que o arquivo precisa. * **Inscrições**: [listar](https://docs.lerian.studio/pt/reference/products/reporter/list-subscriptions.md), [criar](https://docs.lerian.studio/pt/reference/products/reporter/create-subscription.md), [obter](https://docs.lerian.studio/pt/reference/products/reporter/get-subscription.md), [desativar](https://docs.lerian.studio/pt/reference/products/reporter/deactivate-subscription.md), [reativar](https://docs.lerian.studio/pt/reference/products/reporter/reactivate-subscription.md), [adotar outra versão do documento](https://docs.lerian.studio/pt/reference/products/reporter/adopt-document-version.md) e [definir a instituição da remessa](https://docs.lerian.studio/pt/reference/products/reporter/set-subscription-institution.md). Leia o [contrato](https://docs.lerian.studio/pt/reference/products/reporter/get-the-contract-of-the-version-this-subscription-files.md) e o [manual](https://docs.lerian.studio/pt/reference/products/reporter/read-the-manual-of-the-version-this-subscription-files.md) da versão que uma inscrição remete. * **Mapeamento**: [obter](https://docs.lerian.studio/pt/reference/products/reporter/get-subscription-mapping.md) e [substituir](https://docs.lerian.studio/pt/reference/products/reporter/replace-subscription-mapping.md) o mapeamento YAML dos campos do documento para as suas tabelas, e [verificá-lo contra os bancos de dados ativos](https://docs.lerian.studio/pt/reference/products/reporter/check-mapping-readiness.md). [Veja previamente as linhas de uma consulta](https://docs.lerian.studio/pt/reference/products/reporter/preview-the-rows-of-a-query-of-the-mapping.md) de um mapeamento sem salvá-lo, e [reinicie o mapeamento](https://docs.lerian.studio/pt/reference/products/reporter/restart-the-mapping.md) a partir do mapeamento de referência da Lerian ou de um mapeamento em branco. * **Remessas**: [gerar um rascunho](https://docs.lerian.studio/pt/reference/products/reporter/create-regulatory-report.md), [corrigi-lo](https://docs.lerian.studio/pt/reference/products/reporter/correct-regulatory-report.md), [ler as correções](https://docs.lerian.studio/pt/reference/products/reporter/list-report-corrections.md), [aprová-lo](https://docs.lerian.studio/pt/reference/products/reporter/approve-regulatory-report.md), [ler a proveniência dele](https://docs.lerian.studio/pt/reference/products/reporter/get-report-provenance.md) e [ler as linhas dele como o arquivo as mostra](https://docs.lerian.studio/pt/reference/products/reporter/read-a-filings-rows-as-its-file-shows-them.md). Uma nova inscrição começa pelo mapeamento de referência da Lerian quando o catálogo publica um. Envie `mapping: blank` para começar por um mapeamento em branco. Veja [Conceitos essenciais do Reporter](https://docs.lerian.studio/pt/products/reporter/reporter-core-concepts.md) para o que um mapeamento pode ler. A aprovação é recusada enquanto um campo obrigatório estiver em branco. Quando o contrato do documento declara o tipo de remessa, o Reporter recusa um segundo original de um período depois que um foi aprovado, e uma substituição antes que o original seja aprovado. ### Prazos Seis operações modelam uma obrigação de entrega com uma data de vencimento e uma regra de recorrência: [listar](https://docs.lerian.studio/pt/reference/products/reporter/retrieve-deadlines.md), [criar](https://docs.lerian.studio/pt/reference/products/reporter/create-deadline.md), [atualizar](https://docs.lerian.studio/pt/reference/products/reporter/update-deadline.md), [excluir](https://docs.lerian.studio/pt/reference/products/reporter/delete-deadline.md), [entregar](https://docs.lerian.studio/pt/reference/products/reporter/deliver-deadline.md) e [notificações](https://docs.lerian.studio/pt/reference/products/reporter/retrieve-deadline-notifications.md). 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](https://docs.lerian.studio/pt/reference/products/reporter/get-metrics.md) 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](https://docs.lerian.studio/pt/reference/products/reporter/get-streaming-events.md) retorna o manifesto de eventos abordado em [Eventos](https://docs.lerian.studio/pt/products/reporter/reporter-events.md). ## 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`, `description` e `category`. O mapeamento regulatório é `application/yaml`. 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, fontes de dados e instituições 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`, `document_id`, `subscription_id`, `institution_id`, `regulatory`, `current`, `created_at` e `sort_order`. `current=true` lista apenas a geração de cada período de remessa que prevalece. O Reporter aceita esse filtro apenas em uma listagem de remessas. O cursor carrega a ordenação para o percurso. A listagem de templates filtra por `output_format`, `category`, `has_category`, `description`, `data_source_name` e `created_at`. A listagem de prazos filtra por `status`, `active`, `type`, `start_date` e `end_date`. ## Erros *** Todo erro responde `application/problem+json` e segue a [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). Faça a correspondência pelo `code` quando o corpo trouxer um, nunca pelo texto. A [lista de erros do Reporter](https://docs.lerian.studio/pt/reference/products/reporter/reporter-error-list.md) 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 *** > [card] [Referência da API](https://docs.lerian.studio/pt/reference/introduction.md) > > As 61 operações, com os formatos completos de requisição e resposta. > [card] [Início rápido da API](https://docs.lerian.studio/pt/reference/products/reporter/reporter-developer-quick-start.md) > > Envie um template, gere um relatório e baixe-o com cURL. > [card] [Eventos](https://docs.lerian.studio/pt/products/reporter/reporter-events.md) > > Inscreva-se em eventos de relatório e prazo em vez de consultar repetidamente. > [card] [O que é o Reporter?](https://docs.lerian.studio/pt/products/reporter/what-is-reporter.md) > > Templates, relatórios, fontes de dados e onde eles se encaixam. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.