Saltar al contenido principal
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 61 operaciones distribuidas en nueve áreas: plantillas, el generador de plantillas, informes, fuentes de datos, plazos, instituciones, presentación regulatoria, métricas y el manifiesto de streaming. Las 61 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, institutions, regulatory, metrics o streaming. Aprobar un borrador regulatorio se autoriza contra su propio recurso, regulatory-approval. 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. Dos operaciones POST se autorizan como la acción put sobre regulatory: la vista previa del mapeo y el reinicio del mapeo. 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.

​
Las operaciones por función

​
Plantillas

Nueve operaciones controlan el ciclo de vida de la plantilla: listar, subir, obtener, obtener el contenido, actualizar, eliminar y previsualizar, además de listar familias de informes y asignar una familia de informes. Una plantilla es un archivo de texto plano .tpl junto con su formato de salida, su descripción y su categoría. Eliminar una plantilla 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, y una presentación regulatoria llega a Draft en lugar de Finished. Haz polling sobre la operación de obtener, o suscríbete a los eventos descritos en Eventos. La descarga sirve un informe en Finished o Final, y un Draft solo cuando ningún campo obligatorio está en blanco. El encabezado de respuesta X-Report-Status indica el estado que recibiste. 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. Un despliegue self-hosted también puede sembrar entradas del registro a partir de variables DATASOURCE_* al iniciar.

​
Instituciones

Seis operaciones registran las instituciones financieras para las que un tenant reporta: listar, crear, obtener, reemplazar, eliminar y proponer desde Midaz. Una institución tiene un CNPJ y un alcance que nombra sus filas en cada fuente de datos. Una solicitud de informe indica la institución para la que lee. Cuando el tenant tiene varias instituciones, se rechaza una solicitud que no indica ninguna. Reemplazar requiere If-Match con la versión que leíste.

​
Presentación regulatoria

Veintitrés operaciones ejecutan el ciclo de presentación de los documentos regulatorios curados que incluye un despliegue: Una suscripción nueva parte del mapeo de referencia de Lerian cuando el catálogo publica uno. Envía mapping: blank para partir de un mapeo en blanco. Consulta Conceptos centrales de Reporter para ver lo que un mapeo puede leer. La aprobación se rechaza mientras un campo obligatorio esté en blanco. Cuando el contrato del documento declara el tipo de remesa, Reporter rechaza un segundo original de un período después de aprobar uno, y una sustitución antes de aprobar el original.

​
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, description y category. El mapeo regulatorio usa application/yaml. 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, fuentes de datos e instituciones 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, document_id, subscription_id, institution_id, regulatory, current, created_at y sort_order. current=true lista solo la generación de cada período de presentación que prevalece. Reporter acepta ese filtro solo en una lista de presentaciones. El cursor lleva el orden de clasificación para el recorrido. La lista de plantillas filtra por output_format, category, has_category, description, data_source_name y created_at. La lista de plazos filtra por status, active, type, start_date y end_date.

​
Errores

Todo error responde con application/problem+json y sigue RFC 9457. Compara por el code cuando el cuerpo lleve uno, 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 61 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í.