Reporter

Reporter es un producto central en el stack de reportes de Lerian. Permite a los equipos generar reportes dinámicos basados en datos a través de plantillas de texto plano simples (archivos .tpl). Estas plantillas pueden renderizarse en múltiples formatos como CSV, XML, HTML, TXT o incluso PDF—todo mientras se preserva la estructura de salida definida en la plantilla. Ejemplo:

Plantilla estructurada en CSV → salida CSV
Plantilla estructurada en XML → salida XML
Plantilla estructurada en HTML → salida HTML o PDF
Plantilla estructurada en TXT → salida TXT

Prueba Reporter localmente sin desplegar en Kubernetes usando nuestro repositorio plugins-docker-compose.Ten en cuenta que estos servicios requieren una licencia válida para funcionar. Sin ella, la aplicación no iniciará. Para detalles de licencia, consulta nuestra documentación de Licencia.

¿Por qué usar Reporter?

En lugar de escribir consultas SQL complejas, puedes usar marcadores de posición intuitivos que referencian tus dominios, tablas y campos directamente. Es una forma rápida, flexible y mantenible de crear reportes que evolucionan junto con tu modelo de datos.

Cómo funciona

Flujo de trabajo

Reporter sigue un flujo de trabajo simple y eficiente que convierte tus plantillas en reportes listos para producción. Comienzas enviando un archivo de plantilla con filtros y parámetros opcionales. Reporter recupera los datos requeridos de tus bases de datos configuradas (PostgreSQL, MongoDB, o ambas), aplica la lógica de tu plantilla y genera la salida final en el formato que elijas, como CSV, XML, HTML o PDF.

Arquitectura

Reporter está construido sobre una arquitectura en capas que mantiene las responsabilidades claras y soporta el crecimiento. La capa de datos se conecta a tus bases de datos a través de tus fuentes de datos configuradas. La capa de lógica de negocio gestiona el análisis de plantillas, la resolución de marcadores de posición y las tareas de renderización. La capa de presentación devuelve la salida formateada a través de APIs RESTful, lo que facilita la integración de Reporter en tus aplicaciones existentes y flujos operacionales.

Qué puede hacer

Consultas dinámicas con marcadores de posición: Referencia cualquier punto de datos mediante rutas directas — no se requiere SQL.
Lógica de bucles y condiciones: Soporte para bucles, condicionales y bloques con alcance.
Operaciones matemáticas y agregación: Realiza cálculos con sum_by, avg_by y el nuevo bloque {% calc %}.
Procesamiento asíncrono: Los reportes pesados se manejan de forma asíncrona para proteger las cargas de trabajo en vivo.
Múltiples formatos de salida: Genera documentos CSV, XML, HTML, TXT o PDF según tus necesidades.

Modelo de plantilla

Reporter usa plantillas que reflejan la estructura del documento final. Ya sea que estés generando un archivo XML estructurado o un PDF imprimible, el contenido coincidirá exactamente.

Aunque el contenido del archivo debe seguir el formato de salida, asegúrate de guardarlo con una extensión .tpl. Esto es requerido para que la plantilla funcione correctamente.

Configurando tu entorno

Antes de comenzar, debes renombrar las bases de datos usadas como referencias para buscar información mientras se renderizan los reportes. Esta configuración debe hacerse en el archivo .env del proyecto. Al definir nombres únicos y claros para cada base de datos, evitamos conflictos, especialmente en casos donde diferentes bases de datos tienen tablas con los mismos nombres, y aseguramos mejor fluidez en las consultas.

Ejemplo

Si estás usando una base de datos llamada onboarding, recomendamos renombrarla a algo más descriptivo, como:

midaz_onboarding (PostgreSQL).
midaz_onboarding_metadata (MongoDB).

Usando marcadores de posición

Las plantillas usan marcadores de posición para obtener datos dinámicamente. Un marcador de posición apunta a un campo dentro de una tabla o una colección de documentos, y sigue esta estructura:

{{ base.table_or_collection.field_or_document }}

Este formato funciona para bases de datos SQL (tablas) y MongoDB (colecciones), dándote flexibilidad completa independientemente de tu modelo de datos.

Construyendo plantillas

Puedes mejorar tus plantillas con condicionales, operadores matemáticos y variables temporales, haciéndolas más dinámicas y flexibles.

Bloques comunes

Bucle

Itera a través de un conjunto de datos y renderiza valores dentro del bloque. Aunque puede parecer un condicional, es una estructura de repetición. Ejemplo

{% for <item> in <list> %}
  ...
{% endfor %}

Condición simple

Verifica una regla lógica. Si es verdadera, el bloque se ejecuta. Ejemplo

{% if value_a == value_b %}
  ...
{% endif %}

Alcance temporal

Crea una variable temporal dentro del bloque. Esto hace que las plantillas sean más fáciles de leer y evita repetir rutas largas (como acceder al mismo objeto o campo múltiples veces). Ejemplo

{% with <object> as <alias> %}
  ...
{% endwith %}

Formato de valores

Te permite mostrar números con un número fijo de decimales, perfecto para mantener valores financieros claros y consistentes. Agrega un número después de los dos puntos para definir la precisión decimal. Por ejemplo, :2 muestra dos decimales: 123.45. Ejemplo

{{{ field_name }}|floatformat:2 }  ➔ renderiza 123.45

Bloques condicionales

Reporter soporta condiciones lógicas enriquecidas:

Bloque	Descripción	Ejemplo
If	Ejecuta un bloque si la condición es verdadera.	`{% if condition %}...{% endif %}`
If-else	Ejecuta un bloque si es verdadero, otro si es falso.	`{% if condition %}...{% else %}...{% endif %}`
If - else - if	Permite múltiples verificaciones dentro del mismo bloque.	`{% if a %}...{% elif b %}...{% else %}...{% endif %}`
Igual	Verifica si dos valores son iguales.	`{% if a == b %}`
No igual	Verifica si dos valores son diferentes.	`{% if a != b %}`
Mayor que	Verifica si a es mayor que b.	`{% if a > b %}`
Menor que	Verifica si a es menor que b.	`{% if a < b %}`
Mayor o igual que	Verifica si a es mayor o igual que b.	`{% if a >= b %}`
Menor o igual que	Verifica si a es menor o igual que b.	`{% if a <= b %}`
Y (And)	Devuelve verdadero si ambas condiciones son verdaderas.	`{% if a and b %}`
O (Or)	Devuelve verdadero si al menos una condición es verdadera.	`{% if a or b %}`
No (Not)	Invierte el resultado booleano de una condición.	`{% if not a %}`

Operadores y filtros

Puedes combinar condiciones lógicas con operaciones matemáticas para definir reglas, calcular valores y formatear resultados con precisión. Ejemplo: Calculando Suma Total con Filtro

<Sum>
  {% sum_by transaction.operation by "amount" if accountAlias != "@external/BRL" %}
</Sum>

Asumiendo los siguientes datos:

"transaction": {
  "operation": [
    { "value": "10.00", "accountAlias": "@user/BRL" },
    { "value": "5.00", "accountAlias": "@external/BRL" },
    { "value": "25.00", "accountAlias": "@user/BRL" }
  ]
}

La salida será:

<Sum>35.00</Sum>

Otras funciones

Conteo

<Count>
  {% count_by transaction.operation if accountAlias != "@external/BRL" %}
</Count>

Promedio

<Average>
  {% avg_by transaction.operation by "amount" if accountAlias != "@external/BRL" %}
</Average>

Mínimo

<Minimum>
  {% min_by transaction.operation by "amount" if accountAlias != "@external/BRL" %}
</Minimum>

Máximo

<Maximum>
  {% max_by transaction.operation by "amount" if accountAlias != "@external/BRL" %}
</Maximum>

Porcentaje

Digamos que el usuario está generando un reporte de gastos mensuales y quiere mostrar cuánto del total se gastó en “Comida”:

<Percentage>
  {{ category.amount | percent_of: total.expenses }}
</Percentage>

Si:

category.amount = "6.00"
total.expenses = "20.00"

Salida:

<Percentage>
  30.00%
</Percentage>

Fecha

Aplica la fecha actual al renderizar la plantilla. Puedes formatearla como necesites (ddMMyyyy, yyyyMMdd, y más). El tiempo también puede incluirse, como en el ejemplo a continuación.

El tiempo se genera en UTC (Tiempo Universal Coordinado), sin zonas horarias regionales o ajustes de horario de verano.

Entrada:

{% date_time "ddMMYYYY HH:mm"}

Salida:

13-05-2025 21:15

Contains

Usa este filtro para verificar si un valor está parcialmente incluido en otro, incluso si no son idénticos. Es beneficioso cuando tus datos incluyen prefijos o sufijos dinámicos, como en alias de cuentas.

{% if contains(midaz_transaction.transaction.body.source.from.accountAlias, midaz_onboarding.account.alias) %}

Ejemplo:

midaz_transaction.transaction.body.source.from.account_alias = 0#@external/BRL
midaz_onboarding.account.alias = @external/BRL

Aunque las cadenas no coincidan exactamente, contains devolverá true porque @external/BRL está dentro de 0#@external/BRL.

Operaciones matemáticas

Reporter te permite realizar cálculos en datos exportados.

Palabra clave	Descripción
`sum_by`	Suma valores.
`-`	Resta.
`*`	Multiplica.
`/`	Divide.
`avg_by`	Calcula promedio.
`min_by`	Valor mínimo.
`max_by`	Valor máximo.
`percent_of`	Calcula porcentaje.
`filter(list, "field", value)`	Filtra listas como si fuera una cláusula `WHERE`.
`{% calc %}`	Ejecuta expresiones matemáticas en línea para calcular valores dinámicamente durante la renderización de plantillas. Soporta operaciones aritméticas, expresiones anidadas y referencias a variables — ideal para cálculos como totales, saldos o métricas derivadas. Ejemplo: `{% calc (balance.available + 1.2) * balance.on_hold - balance.available / 2 %}`

Filtrado avanzado

Reporter soporta lógica de filtrado compleja en el objeto filters de una solicitud de reporte. Cada filtro se aplica por datasource > table > field, usando una condición como:

{
  "filters": {
    "midaz_onboarding": {
      "account": {
        "id": { "eq": ["123", "456"] },
        "createdAt": { "between": ["2023-01-01", "2023-01-31"] },
        "status": { "in": ["active", "pending"] }
      }
    }
  }
}

Operadores soportados:

eq: Igual a;
gt: Mayor que;
gte: Mayor o igual que;
lt: Menor que;
lte: Menor o igual que;
between: El valor cae dentro de un rango;
in: El valor está dentro de una lista;
nin: El valor no está dentro de una lista.

Recomendaciones de seguridad

La seguridad es fundamental al trabajar con productos y plugins de Lerian. Antes de desplegar cualquier componente en tu entorno, recomendamos encarecidamente revisar nuestras Recomendaciones de Seguridad. Cada producto—junto con sus plugins asociados—debe implementarse en línea con las mejores prácticas de seguridad, incluyendo:

Asegurar límites de red
Gestionar y rotar secretos
Aplicar gestión de parches oportuna
Hacer cumplir controles de acceso estrictos basados en roles (RBAC)

Siguiendo estas prácticas, aseguras que los productos y plugins de Lerian operen de forma segura, se integren perfectamente con tu infraestructura y mantengan el cumplimiento, la integridad de datos y la confianza del usuario en todo tu ecosistema.

Compatibilidad de versión con Midaz

Para asegurar una experiencia completa y confiable con el producto Reporter, debes actualizar de Midaz v2.x.x a Midaz v3.x.x. Reporter depende de mejoras principales introducidas en Midaz v3, y sin esta actualización ciertas funcionalidades de reportes pueden estar limitadas o no disponibles.

¿Necesitas inspiración?

Consulta la página de Ejemplos de plantillas para explorar qué puedes hacer y comenzar a dar forma a tu propia plantilla.

Introducción

Ejemplos de plantillas

Plantillas de BACEN

Usando Reporter con Midaz Console

¿Por qué usar Reporter?

Cómo funciona

Flujo de trabajo

Arquitectura

Qué puede hacer

Modelo de plantilla

Configurando tu entorno

Ejemplo

Usando marcadores de posición

Construyendo plantillas

Bloques comunes

Bloques condicionales

Operadores y filtros

Otras funciones

Contains

Operaciones matemáticas

Filtrado avanzado

Operadores soportados:

Recomendaciones de seguridad

Compatibilidad de versión con Midaz

¿Necesitas inspiración?

Introducción

Ejemplos de plantillas

Plantillas de BACEN

Usando Reporter con Midaz Console

​¿Por qué usar Reporter?

​Cómo funciona

​Flujo de trabajo

​Arquitectura

​Qué puede hacer

​Modelo de plantilla

​Configurando tu entorno

​Ejemplo

​Usando marcadores de posición

​Construyendo plantillas

​Bloques comunes

​Bloques condicionales

​Operadores y filtros

​Otras funciones

​Contains

​Operaciones matemáticas

​Filtrado avanzado

​Operadores soportados:

​Recomendaciones de seguridad

​Compatibilidad de versión con Midaz

​¿Necesitas inspiración?

¿Por qué usar Reporter?

Cómo funciona

Flujo de trabajo

Arquitectura

Qué puede hacer

Modelo de plantilla

Configurando tu entorno

Ejemplo

Usando marcadores de posición

Construyendo plantillas

Bloques comunes

Bloques condicionales

Operadores y filtros

Otras funciones

Contains

Operaciones matemáticas

Filtrado avanzado

Operadores soportados:

Recomendaciones de seguridad

Compatibilidad de versión con Midaz

¿Necesitas inspiración?