/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. 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:
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.
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.
As operações por função
Templates
Nove operações controlam o ciclo de vida do template: listar, enviar, obter, obter o conteúdo, atualizar, excluir e pré-visualizar, além de listar famílias de relatório e atribuir uma família de relatório. 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 e listar definições de filtro retornam o catálogo do qual um editor se baseia. Validar blocos verifica uma árvore de blocos e relata erros por bloco. Gerar código transforma essa árvore em código-fonte de template que você pode então enviar.Relatórios
Quatro operações: criar, obter, listar e baixar. 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. 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, criar, obter, substituir, excluir e propor a partir do Midaz. 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 exigeIf-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, obter um documento e obter o contrato dele, que lista todos os campos de que o arquivo precisa.
- Inscrições: listar, criar, obter, desativar, reativar, adotar outra versão do documento e definir a instituição da remessa. Leia o contrato e o manual da versão que uma inscrição remete.
- Mapeamento: obter e substituir o mapeamento YAML dos campos do documento para as suas tabelas, e verificá-lo contra os bancos de dados ativos. Veja previamente as linhas de uma consulta de um mapeamento sem salvá-lo, e reinicie o mapeamento a partir do mapeamento de referência da Lerian ou de um mapeamento em branco.
- Remessas: gerar um rascunho, corrigi-lo, ler as correções, aprová-lo, ler a proveniência dele e ler as linhas dele como o arquivo as mostra.
mapping: blank para começar por um mapeamento em branco. Veja Conceitos essenciais do Reporter 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, criar, atualizar, excluir, entregar e notificações. 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 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 retorna o manifesto de eventos abordado em Eventos.
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: truenela.
Paginação
As listagens de templates, prazos, fontes de dados e instituições usam paginação por offset com os mesmos dois parâmetros.
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. Faça a correspondência pelo code quando o corpo trouxer um, nunca pelo texto. A lista de erros do Reporter 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
Referência da API
As 61 operações, com os formatos completos de requisição e resposta.
Início rápido da API
Envie um template, gere um relatório e baixe-o com cURL.
Eventos
Inscreva-se em eventos de relatório e prazo em vez de consultar repetidamente.
O que é o Reporter?
Templates, relatórios, fontes de dados e onde eles se encaixam.