Usando Reporter

Reporter ayuda a los usuarios de Midaz Ledger a crear informes dinámicos basados en datos sin necesidad de conocimientos de SQL. Usted define dominios, tablas y campos utilizando marcadores de posición simples en lugar de construir consultas complejas.

Uso típico

Paso 1 — Crear el archivo `.tpl`

Escriba una plantilla que coincida con el formato de salida deseado (HTML, PDF, XML, CSV o TXT). La plantilla debe incorporar bloques de Reporter y seguir la sintaxis apropiada para su formato de salida. Consulte Ejemplos de plantillas para obtener orientación.

El archivo debe guardarse con la extensión .tpl. Esto es necesario para un procesamiento correcto.

Paso 2 — Subir la plantilla

Una vez lista, suba el archivo .tpl utilizando el endpoint Subir una Plantilla. Configure el campo outputFormat para especificar el formato del informe. El sistema asigna un nombre de archivo UUID (por ejemplo, 0196159b-4f26-7300-b3d9-f4f68a7c85f3.tpl). Endpoints de gestión de plantillas:

Listar Plantillas — Ver las plantillas de la organización.
Obtener detalles de una Plantilla — Acceder a la información de una plantilla específica.
Actualizar una Plantilla — Modificar el archivo .tpl, la descripción o el formato de salida.
Eliminar una Plantilla — Marcar plantillas como eliminadas mediante la marca de tiempo deletedAt.

Paso 3 — Generar el informe

Use el endpoint Crear un Informe para iniciar la generación. Pase un templateId y filters opcionales en el cuerpo de la solicitud:

{
  "templateId": "0196159b-4f26-7300-b3d9-f4f68a7c85f3",
  "filters": {
    "midaz_transaction": {
      "transaction": {
        "id": { "eq": ["0196d983-a2c2-7d5a-a5b7-029fe0dcb710"] }
      }
    }
  }
}

La API devuelve un reportId para rastrear y recuperar la salida.

Puede aplicar filtros avanzados para controlar qué datos se incluyen en el reporte. Los filtros admiten operadores como eq, gt, gte, lt, lte, between, in y nin. Los filtros funcionan de manera transparente tanto en fuentes de datos PostgreSQL como MongoDB. Consulte Filtrado avanzado para la referencia completa y ejemplos.

Paso 4 — Verificar el estado del informe

El endpoint Verificar Estado del Informe monitorea el progreso. Los valores de estado posibles son:

Processing — El reporte se está generando.
Finished — El reporte está listo para descargar.
Error — Ocurrió un error durante la generación.
PendingExtraction — El reporte está esperando que se complete la extracción de datos.

Paso 5 — Descargar el informe

Una vez el estado sea Finished, descargue el informe usando el endpoint Descargar un Informe. El archivo aparece en el cuerpo de la respuesta con los encabezados Content-Disposition apropiados.

Mapeo de fuentes de datos para filtros dinámicos

Dos endpoints de soporte permiten el filtrado dinámico:

Listar Fuentes de Datos — Lista las fuentes de datos disponibles con sus esquemas y tablas.
Obtener una Fuente de Datos por id — Devuelve el esquema de una fuente de datos específica, incluyendo tablas y campos.

Estos endpoints son opcionales y están diseñados para casos de uso avanzados, como la creación de interfaces personalizadas o la automatización de flujos de trabajo de informes basados en datos de esquema.

Configuración del almacenamiento

Reporter almacena plantillas e informes generados en almacenamiento de objetos compatible con S3 (almacenamiento de archivos en la nube). Soporta AWS S3, MinIO y SeaweedFS de forma nativa. Todos los archivos se almacenan en un único bucket con prefijos internos:

templates/ — para archivos de plantillas subidos
reports/ — para archivos de informes generados

Variables de entorno de almacenamiento

Variable	Descripción	Valor por defecto
`OBJECT_STORAGE_ENDPOINT`	URL del endpoint compatible con S3. Dejar vacío para AWS S3.	—
`OBJECT_STORAGE_REGION`	Región de AWS	`us-east-1`
`OBJECT_STORAGE_ACCESS_KEY_ID`	Clave de acceso para autenticación	—
`OBJECT_STORAGE_SECRET_KEY`	Clave secreta para autenticación	—
`OBJECT_STORAGE_USE_PATH_STYLE`	Usar URLs de estilo path. Requerido para MinIO y SeaweedFS.	`false`
`OBJECT_STORAGE_DISABLE_SSL`	Deshabilitar verificación SSL. Usar solo para desarrollo local.	`false`
`OBJECT_STORAGE_BUCKET`	Nombre del bucket	`reporter-storage`

Ejemplos de configuración por proveedor

AWS S3

OBJECT_STORAGE_ENDPOINT=
OBJECT_STORAGE_REGION=us-west-2
OBJECT_STORAGE_ACCESS_KEY_ID=AKIA...
OBJECT_STORAGE_SECRET_KEY=your-secret-key
OBJECT_STORAGE_USE_PATH_STYLE=false
OBJECT_STORAGE_DISABLE_SSL=false
OBJECT_STORAGE_BUCKET=reporter-prod-bucket

MinIO

OBJECT_STORAGE_ENDPOINT=http://minio:9000
OBJECT_STORAGE_REGION=us-east-1
OBJECT_STORAGE_ACCESS_KEY_ID=minioadmin
OBJECT_STORAGE_SECRET_KEY=minioadmin
OBJECT_STORAGE_USE_PATH_STYLE=true
OBJECT_STORAGE_DISABLE_SSL=true
OBJECT_STORAGE_BUCKET=reporter-storage

SeaweedFS (desarrollo local)

OBJECT_STORAGE_ENDPOINT=http://reporter-seaweedfs:8333
OBJECT_STORAGE_REGION=us-east-1
OBJECT_STORAGE_ACCESS_KEY_ID=any
OBJECT_STORAGE_SECRET_KEY=any
OBJECT_STORAGE_USE_PATH_STYLE=true
OBJECT_STORAGE_DISABLE_SSL=true
OBJECT_STORAGE_BUCKET=reporter-storage

S3 no soporta TTL por objeto. Para expirar automáticamente los informes generados, configure políticas de ciclo de vida del bucket S3 en su bucket.

Configuración de fuentes de datos externas

Reporter se conecta a bases de datos externas (PostgreSQL y MongoDB) como fuentes de datos para sus plantillas. Puede configurar las fuentes de datos de dos maneras:

Mediante variables de entorno — Usando el patrón DATASOURCE_<NAME>_* descrito a continuación. Ideal para configuraciones de infraestructura como código y configuraciones estáticas.
Mediante la API de conexiones — Usando la API de conexiones de base de datos para registrar, probar y administrar conexiones de forma dinámica. Ideal para escenarios donde las conexiones cambian frecuentemente o se administran a través de una interfaz.

Configuración mediante variables de entorno

Cada fuente de datos se configura mediante variables de entorno siguiendo el patrón DATASOURCE_<NAME>_*.

Variables de entorno de fuentes de datos

Variable	Descripción	Requerido
`DATASOURCE_<NAME>_CONFIG_NAME`	Identificador único usado en plantillas (por ejemplo, `midaz_onboarding`)	Sí
`DATASOURCE_<NAME>_HOST`	Host de la base de datos	Sí
`DATASOURCE_<NAME>_PORT`	Puerto de la base de datos	Sí
`DATASOURCE_<NAME>_USER`	Usuario de la base de datos	Sí
`DATASOURCE_<NAME>_PASSWORD`	Contraseña de la base de datos	Sí
`DATASOURCE_<NAME>_DATABASE`	Nombre de la base de datos	Sí
`DATASOURCE_<NAME>_TYPE`	Tipo de base de datos: `postgresql` o `mongodb` (minúsculas). Nota: la API de conexiones usa valores en mayúsculas (`POSTGRESQL`, `MONGODB`).	Sí
`DATASOURCE_<NAME>_SSLMODE`	Modo SSL para PostgreSQL (`disable`, `require`)	Solo PostgreSQL
`DATASOURCE_<NAME>_SSLROOTCERT`	Ruta del certificado raíz SSL para PostgreSQL	Solo PostgreSQL
`DATASOURCE_<NAME>_SSL`	Habilitar SSL para MongoDB (`true` o `false`)	Solo MongoDB
`DATASOURCE_<NAME>_SSLCA`	Ruta del archivo de certificado CA para MongoDB	Solo MongoDB
`DATASOURCE_<NAME>_OPTIONS`	Opciones adicionales de URI para MongoDB	Solo MongoDB
`DATASOURCE_<NAME>_SCHEMAS`	Lista de esquemas a exponer separados por comas	Solo PostgreSQL

Ejemplo de fuente de datos única

DATASOURCE_ONBOARDING_CONFIG_NAME=midaz_onboarding
DATASOURCE_ONBOARDING_HOST=midaz-postgres-replica
DATASOURCE_ONBOARDING_PORT=5702
DATASOURCE_ONBOARDING_USER=midaz
DATASOURCE_ONBOARDING_PASSWORD=lerian
DATASOURCE_ONBOARDING_DATABASE=onboarding
DATASOURCE_ONBOARDING_TYPE=postgresql
DATASOURCE_ONBOARDING_SSLMODE=disable

En las plantillas, se referencia esta fuente de datos como midaz_onboarding:

{% for account in midaz_onboarding.account %}
  {{ account.id }} - {{ account.name }}
{% endfor %}

Fuente de datos con múltiples esquemas

Para consultar tablas en múltiples esquemas de PostgreSQL, configure la variable DATASOURCE_<NAME>_SCHEMAS con una lista separada por comas:

DATASOURCE_EXTERNAL_CONFIG_NAME=external_db
DATASOURCE_EXTERNAL_HOST=external-postgres
DATASOURCE_EXTERNAL_PORT=5432
DATASOURCE_EXTERNAL_USER=db_user
DATASOURCE_EXTERNAL_PASSWORD=db_password
DATASOURCE_EXTERNAL_DATABASE=external_database
DATASOURCE_EXTERNAL_TYPE=postgresql
DATASOURCE_EXTERNAL_SSLMODE=disable
DATASOURCE_EXTERNAL_SCHEMAS=sales,inventory,reporting

En las plantillas, use la sintaxis explícita de esquema database:schema.table:

{% for order in external_db:sales.orders %}
  {{ order.id }} - {{ order.total }}

  {% for item in external_db:inventory.items|where:"order_id:{{ order.id }}" %}
    Item: {{ item.name }} ({{ item.quantity }} in stock)
  {% endfor %}
{% endfor %}

Al generar un informe con filtros, use schema.table como clave de tabla:

{
  "templateId": "00000000-0000-0000-0000-000000000000",
  "filters": {
    "external_db": {
      "sales.orders": {
        "created_at": { "gte": ["2025-01-01"] }
      }
    }
  }
}

Cuando DATASOURCE_<NAME>_SCHEMAS no está configurado, Reporter usa por defecto solo el esquema public.

Comportamiento de conexión

Reporter utiliza dos estrategias de inicialización:

Componente Manager (lazy): Carga la configuración sin conectarse. Se conecta bajo demanda cuando una plantilla referencia la fuente de datos. Esto proporciona un inicio más rápido.
Componente Worker (eager): Intenta conectarse al inicio con reintentos a intervalos crecientes (hasta 5 intentos). Continúa con funcionalidad degradada si una fuente de datos no está disponible.

Referencia completa de variables de entorno

Aplicación

Variable	Descripción	Valor por defecto
`ENV_NAME`	Nombre del entorno	`development`
`LOG_LEVEL`	Nivel de log (`debug`, `info`, `warn`, `error`)	`debug`
`SERVER_PORT`	Puerto HTTP del Manager	`4005`
`SERVER_ADDRESS`	Dirección de enlace del Manager	`:4005`

Almacenamiento de objetos (compatible con S3)

Variable	Descripción	Valor por defecto
`OBJECT_STORAGE_ENDPOINT`	URL del endpoint S3	—
`OBJECT_STORAGE_REGION`	Región de AWS	`us-east-1`
`OBJECT_STORAGE_ACCESS_KEY_ID`	Clave de acceso	—
`OBJECT_STORAGE_SECRET_KEY`	Clave secreta	—
`OBJECT_STORAGE_USE_PATH_STYLE`	URLs de estilo path	`false`
`OBJECT_STORAGE_DISABLE_SSL`	Deshabilitar SSL	`false`
`OBJECT_STORAGE_BUCKET`	Nombre del bucket	`reporter-storage`

MongoDB

Variable	Descripción	Valor por defecto
`MONGO_URI`	Esquema de URI (`mongodb` o `mongodb+srv`)	—
`MONGO_HOST`	Host de MongoDB	—
`MONGO_NAME`	Nombre de la base de datos	—
`MONGO_USER`	Usuario de la base de datos	—
`MONGO_PASSWORD`	Contraseña de la base de datos	—
`MONGO_PORT`	Puerto de la base de datos	—
`MONGO_MAX_POOL_SIZE`	Tamaño del pool de conexiones	`1000`
`MONGO_PARAMETERS`	Parámetros adicionales de URI	—

RabbitMQ

Variable	Descripción	Valor por defecto
`RABBITMQ_URI`	Esquema de URI (`amqp`)	—
`RABBITMQ_HOST`	Host de RabbitMQ	—
`RABBITMQ_PORT_AMQP`	Puerto AMQP	—
`RABBITMQ_PORT_HOST`	Puerto de administración	—
`RABBITMQ_DEFAULT_USER`	Usuario	—
`RABBITMQ_DEFAULT_PASS`	Contraseña	—
`RABBITMQ_GENERATE_REPORT_QUEUE`	Nombre de la cola para generación de informes	—
`RABBITMQ_NUMBERS_OF_WORKERS`	Número de workers consumidores (solo worker)	`5`

Redis / Valkey

Variable	Descripción	Valor por defecto
`REDIS_HOST`	Host de Redis con puerto (por ejemplo, `host:6379`)	—
`REDIS_PASSWORD`	Contraseña de Redis	—
`REDIS_DB`	Número de base de datos	`0`
`REDIS_PROTOCOL`	Versión del protocolo Redis	`3`
`REDIS_MASTER_NAME`	Nombre del master de Sentinel (si usa Sentinel)	—
`REDIS_TLS`	Habilitar TLS	`false`

Generación de PDF (solo worker)

Variable	Descripción	Valor por defecto
`PDF_POOL_WORKERS`	Número de workers paralelos para generación de PDF	`2`
`PDF_TIMEOUT_SECONDS`	Tiempo límite por generación de PDF en segundos	`90`

Telemetría (OpenTelemetry)

Variable	Descripción	Valor por defecto
`OTEL_RESOURCE_SERVICE_NAME`	Nombre del servicio para trazas	—
`OTEL_LIBRARY_NAME`	Nombre de la librería de instrumentación	—
`OTEL_RESOURCE_SERVICE_VERSION`	Versión del servicio	—
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	Entorno de despliegue	—
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint del exportador OTLP	—
`ENABLE_TELEMETRY`	Habilitar recopilación de telemetría	`false`

Autenticación

Variable	Descripción	Valor por defecto
`PLUGIN_AUTH_ADDRESS`	URL del servicio de autenticación	—
`PLUGIN_AUTH_ENABLED`	Habilitar autenticación	`false`

Licencia

Variable	Descripción	Valor por defecto
`LICENSE_KEY`	Clave de licencia para Reporter	—
`ORGANIZATION_IDS`	IDs de organización para validación de licencia	—

Introducción

Ejemplos de plantillas

Plantillas brasileñas

Usando Reporter

Uso típico

Paso 1 — Crear el archivo `.tpl`

Paso 2 — Subir la plantilla

Paso 3 — Generar el informe

Paso 4 — Verificar el estado del informe

Paso 5 — Descargar el informe

Mapeo de fuentes de datos para filtros dinámicos

Configuración del almacenamiento

Variables de entorno de almacenamiento

Ejemplos de configuración por proveedor

Configuración de fuentes de datos externas

Configuración mediante variables de entorno

Variables de entorno de fuentes de datos

Ejemplo de fuente de datos única

Fuente de datos con múltiples esquemas

Comportamiento de conexión

Referencia completa de variables de entorno

Aplicación

Almacenamiento de objetos (compatible con S3)

MongoDB

RabbitMQ

Redis / Valkey

Generación de PDF (solo worker)

Telemetría (OpenTelemetry)

Autenticación

Licencia

Introducción

Ejemplos de plantillas

Plantillas brasileñas

​Uso típico

​Paso 1 — Crear el archivo .tpl

​Paso 2 — Subir la plantilla

​Paso 3 — Generar el informe

​Paso 4 — Verificar el estado del informe

​Paso 5 — Descargar el informe

​Mapeo de fuentes de datos para filtros dinámicos

​Configuración del almacenamiento

​Variables de entorno de almacenamiento

​Ejemplos de configuración por proveedor

​Configuración de fuentes de datos externas

​Configuración mediante variables de entorno

​Variables de entorno de fuentes de datos

​Ejemplo de fuente de datos única

​Fuente de datos con múltiples esquemas

​Comportamiento de conexión

​Referencia completa de variables de entorno

​Aplicación

​Almacenamiento de objetos (compatible con S3)

​MongoDB

​RabbitMQ

​Redis / Valkey

​Generación de PDF (solo worker)

​Telemetría (OpenTelemetry)

​Autenticación

​Licencia

Uso típico

Paso 1 — Crear el archivo `.tpl`

Paso 2 — Subir la plantilla

Paso 3 — Generar el informe

Paso 4 — Verificar el estado del informe

Paso 5 — Descargar el informe

Mapeo de fuentes de datos para filtros dinámicos

Configuración del almacenamiento

Variables de entorno de almacenamiento

Ejemplos de configuración por proveedor

Configuración de fuentes de datos externas

Configuración mediante variables de entorno

Variables de entorno de fuentes de datos

Ejemplo de fuente de datos única

Fuente de datos con múltiples esquemas

Comportamiento de conexión

Referencia completa de variables de entorno

Aplicación

Almacenamiento de objetos (compatible con S3)

MongoDB

RabbitMQ

Redis / Valkey

Generación de PDF (solo worker)

Telemetría (OpenTelemetry)

Autenticación

Licencia