Skip to main content
Reporter expone una única API HTTP. Cada operación está bajo la ruta base /v1, sin ningún segmento de producto antes de ella. Una lista de plantillas es GET /v1/templates. La API tiene 28 operaciones distribuidas en siete áreas: plantillas, el generador de plantillas, informes, fuentes de datos, plazos, métricas y el manifiesto de streaming. Las 28 se renderizan bajo el anclaje Reporter en la Referencia de API. Esta página cubre lo que las operaciones tienen en común y te dirige 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 para clientes ni una base para la generación de SDK.

​
Autenticación

Reporter acepta un token bearer JWT. Un mismo esquema de seguridad se aplica a todas las operaciones:
Reporter autoriza cada solicitud contra la aplicación reporter, un recurso y una acción. El recurso corresponde 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 hacia Access Manager. Las rutas de sondeo quedan fuera de la autenticación para que un orquestador pueda acceder a ellas sin un 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 anteriores toma el tenant de un encabezado de la solicitud, y ningún valor enviado por el cliente lo sobrescribe. Consulta Multi-tenancy.

​
Las operaciones por función

​
Plantillas

Cinco operaciones controlan el ciclo de vida de la plantilla: listar, subir, obtener, actualizar y eliminar. Una plantilla es un archivo de texto plano .tpl junto con su formato de salida y su descripción. Eliminar una también elimina los plazos que la referencian.

​
Generador 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 se nutre un editor. Validar bloques verifica un árbol de bloques e informa los errores por bloque. Generar código convierte ese árbol en el código fuente de la plantilla que luego puedes subir.

​
Informes

Cuatro operaciones: crear, obtener, listar y descargar. El ciclo de vida es de crear y retener. POST /v1/reports responde 201 con un informe en Processing y delega el trabajo a un worker en segundo plano. El informe luego llega a Finished, Partial o Error. Haz polling sobre la operación de obtener, o suscríbete a los eventos descritos en Eventos. La descarga sirve un informe en Finished. Todo informe que crees permanece direccionable por su identificador mientras tu política de retención de almacenamiento de objetos conserve el artefacto.

​
Fuentes de datos

Siete operaciones administran el registro persistente bajo /v1/data-sources (fíjate en el guion). Puedes listar o crear entradas, y obtener, actualizar parcialmente o eliminar de forma lógica una por dataSourceId, inspeccionar su esquema en vivo y probar su conexión. Las contraseñas son de solo escritura, se cifran en reposo y no aparecen en ninguna respuesta. Una eliminación se rechaza mientras una plantilla activa siga referenciando la fuente de datos. Los despliegues de un solo tenant pueden sembrar entradas del registro a partir de variables DATASOURCE_* al iniciar. Los despliegues multi-tenant las crean por tenant a través de la API.

​
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, nunca lo envía un cliente. Las notificaciones son solo de extracción (pull): la operación devuelve los plazos dentro de su ventana de alerta, ordenados con los vencidos primero.

​
Métricas y streaming

Métricas devuelve contadores del despliegue: plantillas, informes, fuentes de datos y errores de informes de la ventana actual frente a la anterior. errorPeriodDays define esa ventana y su valor predeterminado es 7. Eventos de streaming devuelve el manifiesto de eventos descrito en Eventos.

​
Tipos de contenido

Crear y actualizar 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 el formato de salida del informe: application/pdf, application/xml, text/csv, text/html o text/plain.

​
Idempotencia

Crear plantillas y crear informes aceptan un encabezado de solicitud X-Idempotency. Envía tu propia clave, u omite el encabezado y Reporter deriva una a partir de un hash del cuerpo de la solicitud.
  • Una solicitud que repite otra que todavía está en curso se rechaza en lugar de duplicarse.
  • Una solicitud que repite otra ya completada reproduce la respuesta original y le agrega X-Idempotency-Replayed: true.

​
Paginación

Las listas de plantillas, plazos y fuentes de datos usan paginación por offset con los mismos dos parámetros. Un limit por encima del límite máximo se rechaza con un error de paginación en lugar de ajustarse. La lista de informes usa paginación por keyset en su lugar: envía limit sin page, y luego sigue nextCursor o prevCursor de la respuesta. Un cursor está ausente cuando no hay página en esa dirección, y la respuesta no incluye page ni total. La lista de informes acepta status, template_id, created_at y sort_order. El cursor lleva el orden de clasificación para el recorrido. La lista de plantillas filtra por outputFormat, y la lista de plazos por status.

​
Errores

Todo error responde con application/problem+json y sigue RFC 9457, con un title, un status, un detail y un code de dominio estable. Compara por el código, nunca por el texto. La lista de errores de Reporter asocia cada código con su estado HTTP y 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á desactivado a menos que lo actives. Mantenlo desactivado en producción.

​
Próximos pasos

Referencia de API

Las 28 operaciones, con las formas completas 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 eventos de informes y plazos en lugar de hacer polling.

¿Qué es Reporter?

Plantillas, informes, fuentes de datos y cómo encajan entre sí.