/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. 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:
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.
As operações por tarefa
Templates
Cinco operações são donas do ciclo de vida de um template: listar, enviar, obter, atualizar e excluir. 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 e listar definições de filtro retornam o catálogo de que um editor se alimenta. Validar blocos confere uma árvore de blocos e reporta os erros de cada bloco. Gerar código transforma essa árvore em código-fonte de template que você pode enviar em seguida.Relatórios
Quatro operações, e apenas quatro: criar, obter, listar e baixar. 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. 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 e obter uma, 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, criar, atualizar, excluir, entregar e notificações. 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 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 retorna o manifesto de eventos coberto em Eventos.
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.
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, 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 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
Referência de API
As 23 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
Assine os eventos de relatório e de prazo em vez de fazer sondagem.
O que é o Reporter?
Templates, relatórios, fontes de dados e onde eles se encaixam.