/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. 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, 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.
As operações por função
Templates
Cinco operações controlam o ciclo de vida do template: listar, enviar, obter, atualizar e excluir. 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 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. Consulte repetidamente a operação de obtenção, ou inscreva-se nos eventos descritos em Eventos. 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, 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 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: truenela.
Paginação
As listagens de templates, prazos e fontes de dados 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, 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, 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 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 28 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.