El ciclo de vida de reportes
Cada reporte en Reporter sigue el mismo ciclo de cuatro etapas:
Cargar la plantilla
Registrar la plantilla en Reporter para que pueda ser reutilizada en múltiples generaciones.
Generar un reporte
Enviar una solicitud con filtros opcionales para producir un reporte a partir de la plantilla.
Diseñar una plantilla
Una plantilla es un archivo de texto plano con extensión
.tpl que define cómo se ve tu reporte y qué datos incluye. Las plantillas reflejan la estructura del resultado final — si quieres un reporte XML, escribes XML dentro del archivo .tpl; si quieres HTML, escribes HTML.
En lugar de escribir consultas SQL, referencias datos a través de placeholders que siguen una sintaxis de ruta simple:
{{ midaz_onboarding.account.name }} obtiene el nombre de la cuenta de la base de datos de onboarding de Midaz.
Qué puedes hacer en las plantillas
| Capacidad | Descripción |
|---|---|
| Loops | Iterar sobre colecciones de registros |
| Condiciones | Mostrar u ocultar contenido según valores de datos |
| Agregaciones | Calcular sumas, promedios, conteos, mínimos y máximos |
| Aritmética | Realizar cálculos en campos numéricos |
| Filtros | Transformar valores en línea (formatear números, reemplazar cadenas, extraer subcadenas) |
| Contadores | Rastrear y mostrar totales acumulados entre iteraciones |
Formatos de salida soportados
| Contenido de la plantilla | Formato de salida |
|---|---|
.tpl con estructura CSV | Archivo CSV |
.tpl con estructura XML | Archivo XML |
.tpl con estructura HTML | Archivo HTML o PDF |
.tpl con estructura TXT | Archivo TXT |
Cargar la plantilla
Una vez que tu archivo
.tpl está listo, cárgalo en Reporter. Durante la carga, especificas:
- El archivo de plantilla — tu archivo
.tpl - Formato de salida — el formato que Reporter debe generar (CSV, XML, HTML, PDF o TXT)
- Descripción — una etiqueta opcional para ayudar a identificar la plantilla después
Las plantillas son reutilizables. Cárgalas una vez y genera reportes desde la misma plantilla todas las veces que necesites con diferentes filtros.
Generar un reporte
Para generar un reporte, envía una solicitud con el ID de la plantilla y filtros opcionales que acotan los datos.
Cómo funcionan los filtros
Los filtros siguen una ruta estructurada: fuente de datos > tabla > campo. Puedes filtrar por igualdad, rangos, mayor/menor que y pertenencia a listas. Por ejemplo, para generar un reporte para un rango de fechas y estado de cuenta específicos:| Filtro | Qué hace |
|---|---|
createdAt: between ["2024-01-01", "2024-01-31"] | Solo incluye registros de enero 2024 |
status: in ["active", "pending"] | Solo incluye cuentas activas o pendientes |
id: eq ["123", "456"] | Solo incluye IDs de cuenta específicos |
Operadores de filtro soportados
| Operador | Descripción |
|---|---|
eq | Igual a |
gt / gte | Mayor que / mayor o igual que |
lt / lte | Menor que / menor o igual que |
between | El valor está dentro de un rango |
in / nin | El valor está / no está en una lista |
Procesamiento
La generación de reportes es asíncrona. Después de enviar una solicitud, Reporter devuelve un ID de reporte que usas para verificar el progreso. Los reportes pasan por dos estados:| Estado | Significado |
|---|---|
processing | Reporter está consultando datos y renderizando la plantilla |
finished | El reporte está listo para descargar |
Descargar el resultado
Una vez que un reporte alcanza el estado
finished, descárgalo. El archivo se devuelve en el formato especificado durante la carga de la plantilla — CSV, XML, HTML, PDF o TXT.
Fuentes de datos
Reporter se conecta a tus bases de datos y extrae datos según lo que tus plantillas referencian. Soporta:
| Base de datos | Caso de uso |
|---|---|
| PostgreSQL | Datos relacionales — cuentas, transacciones, asientos contables |
| MongoDB | Datos de documentos — metadatos, esquemas flexibles |
midaz_onboarding o midaz_transaction).
Soporte multi-esquema
Para bases de datos PostgreSQL con múltiples esquemas, las plantillas pueden consultar entre esquemas usando sintaxis explícita:sales, inventory y reporting dentro de una misma base de datos.
Escenario de ejemplo
Una fintech necesita generar un resumen diario de cuentas para su equipo de operaciones. Configuración:
- Un diseñador de plantillas escribe una plantilla HTML con saldos de cuentas, conteos de transacciones y totales diarios usando los tags de agregación de Reporter
- La plantilla se carga una vez con formato de salida configurado como PDF
- Un job automatizado envía una solicitud de reporte con un filtro de fecha para el día actual.
- Reporter consulta la base de datos de Midaz, aplica la lógica de la plantilla y renderiza el resultado.
- El reporte alcanza el estado
finisheden segundos. - El equipo de operaciones descarga el PDF y revisa el resumen diario.
- La misma plantilla se reutiliza todos los días — solo cambia el filtro de fecha.
Reportes regulatorios brasileños
Reporter incluye plantillas listas para usar para reportes regulatorios del Banco Central de Brasil (BACEN):
| Plantilla | Propósito |
|---|---|
| CADOC 4010 / 4016 | Balance de comprobación y reportes de balance general |
| CADOC 4111 | Reportes detallados de transacciones |
| CCS | Reportes de registro de clientes y cuentas |
Próximos pasos
¿Qué es Reporter?
Descripción completa de la arquitectura y capacidades de Reporter.
Formatos de plantillas
Ejemplos prácticos para plantillas HTML, XML y TXT.
Reporte de balance de comprobación
Guía completa para generar balances de comprobación con Midaz y Reporter.
Plantillas BACEN
Plantillas listas para usar para reportes regulatorios brasileños.