/v1, sin ningún segmento de producto por delante. Una lista de plantillas es GET /v1/templates.
La API reúne 23 operaciones repartidas en siete áreas: plantillas, el constructor de plantillas, informes, fuentes de datos, plazos, métricas y el manifiesto de streaming. Las 23 se renderizan bajo el ancla Reporter de la Referencia de API. Esta página es el mapa, no el territorio. Cubre lo que las operaciones comparten y te apunta a la página de referencia de cada una.
Los documentos OpenAPI de este portal son fuentes de renderizado para las páginas de referencia. No son contratos de cliente, ni una base para generar SDK.
Autenticación
Reporter acepta un token JWT bearer. Un único esquema de seguridad aplica a todas las operaciones:
reporter, un recurso y una acción. El recurso sigue al área — templates, reports, deadlines, data-source, metrics o streaming. La acción es el método HTTP en minúsculas, así que POST /v1/reports se autoriza como la acción post sobre reports. PLUGIN_AUTH_ENABLED activa el middleware y PLUGIN_AUTH_ADDRESS lo apunta al Access Manager.
Las rutas de sondeo quedan fuera de la autenticación para que un orquestador las alcance sin token: /health, /readyz y /version.
La identidad del tenant viaja dentro del token. Reporter resuelve el tenant a partir del claim tenantId del JWT. Ninguna de las operaciones de arriba toma un tenant de una cabecera de solicitud, y ningún valor que envíe el cliente lo sobrescribe. Lee Multi-tenancy.
Las operaciones por tarea
Plantillas
Cinco operaciones son dueñas del ciclo de vida de una plantilla: listar, subir, obtener, actualizar y eliminar. Una plantilla es un archivo.tpl de texto plano más su formato de salida y su descripción. Eliminar una borra también los plazos que apuntan a ella.
Constructor de plantillas
Cuatro operaciones respaldan un editor visual sin persistir nada. Listar definiciones de bloque y listar definiciones de filtro devuelven el catálogo del que dibuja un editor. Validar bloques revisa un árbol de bloques y reporta los errores de cada bloque. Generar código convierte ese árbol en código fuente de plantilla que después puedes subir.Informes
Cuatro operaciones, y solo cuatro: crear, obtener, listar y descargar. El ciclo de vida es crear y conservar.POST /v1/reports responde 201 con un informe en Processing y entrega el trabajo a un worker en segundo plano. El informe llega después a Finished, Partial o Error. Consulta la operación de obtención por sondeo, o suscríbete a los eventos descritos en Eventos. La descarga sirve un informe en Finished. Cada informe que creas sigue siendo direccionable por su identificador mientras la política de retención de tu almacenamiento de objetos conserve el artefacto.
Fuentes de datos
Dos operaciones de lectura: listar y obtener una, ambas bajo/v1/data-sources — fíjate en el guion. Un operador registra las fuentes de datos mediante variables de entorno, así que estas operaciones informan lo que el despliegue ya tiene y no exponen ninguna vía de escritura.
Plazos
Seis operaciones modelan una obligación de presentación con una fecha de vencimiento y una regla de recurrencia: listar, crear, actualizar, eliminar, entregar y notificaciones. El estado se deriva de la fecha de vencimiento y de la marca de entrega, y nunca lo envía un cliente. Las notificaciones son solo de consulta: la operación devuelve los plazos que están dentro de su ventana de alerta, ordenados con los vencidos primero.Métricas y streaming
Métricas devuelve los contadores del despliegue — plantillas, informes, fuentes de datos y errores de informe de la ventana actual frente a la anterior.errorPeriodDays fija esa ventana y vale 7 por defecto. Eventos de streaming devuelve el manifiesto de eventos que cubre Eventos.
Tipos de contenido
La creación y la actualización de plantillas usan
multipart/form-data: una parte de archivo template, más outputFormat y description. Todo lo demás que lleva cuerpo usa application/json.
La descarga responde con los bytes y un nombre de archivo en Content-Disposition. El tipo de medio sigue al formato de salida del informe — application/pdf, application/xml, text/csv, text/html o text/plain.
Idempotencia
La creación de plantillas y la creación de informes aceptan una cabecera de solicitud
X-Idempotency. Envía tu propia clave, u omite la cabecera y Reporter deriva una a partir de un hash del cuerpo de la solicitud.
- Una solicitud que repite otra todavía en curso se rechaza en lugar de duplicarse.
- Una solicitud que repite otra ya completada reproduce la respuesta original y la marca con
X-Idempotency-Replayed: true.
Paginación
Las operaciones de listado usan paginación por desplazamiento con los mismos dos parámetros.
Un
limit por encima del techo se rechaza con un error de paginación en lugar de recortarse. La lista de informes también acepta un parámetro cursor, que lleva la posición de la página anterior en lugar de un número de página.
El listado de informes añade filtros encima: status, template_id, output_format, description, type, active, una ventana start_date/end_date y sort_order, que vale desc por defecto. El listado de plantillas filtra por outputFormat, y el de plazos por status.
Errores
Cada error responde
application/problem+json y sigue RFC 9457, con un title, un status, un detail y un code de dominio estable. Haz coincidir tu lógica con el código, nunca con el texto. La lista de errores de Reporter mapea cada código a su estado HTTP y a su solución.
Leer la especificación desde un servicio en ejecución
SWAGGER_ENABLED=true monta una referencia navegable en /swagger/docs, con el documento OpenAPI 3.1 en /swagger/openapi.json y /swagger/openapi.yaml. Está apagada salvo que la enciendas. Mantenla apagada en producción.
Próximos pasos
Referencia de API
Las 23 operaciones, con sus formatos completos de solicitud y respuesta.
Inicio rápido de la API
Sube una plantilla, genera un informe y descárgalo con cURL.
Eventos
Suscríbete a los eventos de informes y plazos en lugar de sondear.
¿Qué es Reporter?
Plantillas, informes, fuentes de datos y dónde encajan.