Usando Reporter

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

Uso tipico

Paso 1 — Crear el archivo `.tpl`

Escriba una plantilla que coincida con el formato de salida deseado (HTML, 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 orientacion.

El archivo debe guardarse con la extension .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 gestion de plantillas:

Listar Plantillas — Ver las plantillas de la organizacion.
Obtener detalles de una Plantilla — Acceder a la informacion de una plantilla especifica.
Actualizar una Plantilla — Modificar el archivo .tpl, la descripcion 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 generacion. 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.

Paso 4 — Verificar el estado del informe

El endpoint Verificar Estado del Informe monitorea el progreso, mostrando si el informe esta en estado processing o finished.

Paso 5 — Descargar el informe

Una vez 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 dinamicos

Dos endpoints de soporte permiten el filtrado dinamico:

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 especifica, incluyendo tablas y campos.

Estos endpoints son opcionales y estan disenados para casos de uso avanzados, como la creacion de interfaces personalizadas o la automatizacion de flujos de trabajo de informes basados en datos de esquema.

Configuracion del almacenamiento

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

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

Variables de entorno de almacenamiento

Variable	Descripcion	Valor por defecto
`OBJECT_STORAGE_ENDPOINT`	URL del endpoint compatible con S3. Dejar vacio para AWS S3.	—
`OBJECT_STORAGE_REGION`	Region de AWS	`us-east-1`
`OBJECT_STORAGE_ACCESS_KEY_ID`	Clave de acceso para autenticacion	—
`OBJECT_STORAGE_SECRET_KEY`	Clave secreta para autenticacion	—
`OBJECT_STORAGE_USE_PATH_STYLE`	Usar URLs de estilo path. Requerido para MinIO y SeaweedFS.	`false`
`OBJECT_STORAGE_DISABLE_SSL`	Deshabilitar verificacion SSL. Usar solo para desarrollo local.	`false`
`OBJECT_STORAGE_BUCKET`	Nombre del bucket	`reporter-storage`

Ejemplos de configuracion 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 automaticamente los informes generados, configure politicas de ciclo de vida del bucket S3 en su bucket.

Configuracion de fuentes de datos externas

Reporter se conecta a bases de datos externas (PostgreSQL y MongoDB) como fuentes de datos para sus plantillas. Cada fuente de datos se configura mediante variables de entorno siguiendo el patron DATASOURCE_<NAME>_*.

Variables de entorno de fuentes de datos

Variable	Descripcion	Requerido
`DATASOURCE_<NAME>_CONFIG_NAME`	Identificador unico usado en plantillas (por ejemplo, `midaz_onboarding`)	Si
`DATASOURCE_<NAME>_HOST`	Host de la base de datos	Si
`DATASOURCE_<NAME>_PORT`	Puerto de la base de datos	Si
`DATASOURCE_<NAME>_USER`	Usuario de la base de datos	Si
`DATASOURCE_<NAME>_PASSWORD`	Contrasena de la base de datos	Si
`DATASOURCE_<NAME>_DATABASE`	Nombre de la base de datos	Si
`DATASOURCE_<NAME>_TYPE`	Tipo de base de datos: `postgresql` o `mongodb`	Si
`DATASOURCE_<NAME>_SSLMODE`	Modo SSL para PostgreSQL (`disable`, `require`)	Solo PostgreSQL
`DATASOURCE_<NAME>_SSLROOTCERT`	Ruta del certificado raiz 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 unica

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 multiples esquemas

Para consultar tablas en multiples 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 explicita 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 esta configurado, Reporter usa por defecto solo el esquema public.

Comportamiento de conexion

Reporter utiliza dos estrategias de inicializacion:

Componente Manager (lazy): Carga la configuracion sin conectarse. Se conecta bajo demanda cuando una plantilla referencia la fuente de datos. Esto proporciona un inicio mas rapido.
Componente Worker (eager): Intenta conectarse al inicio con reintento con backoff exponencial (hasta 5 reintentos). Continua con funcionalidad degradada si una fuente de datos no esta disponible.

Referencia completa de variables de entorno

Aplicacion

Variable	Descripcion	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`	Direccion de enlace del Manager	`:4005`

Almacenamiento de objetos (compatible con S3)

Variable	Descripcion	Valor por defecto
`OBJECT_STORAGE_ENDPOINT`	URL del endpoint S3	—
`OBJECT_STORAGE_REGION`	Region 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	Descripcion	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`	Contrasena de la base de datos	—
`MONGO_PORT`	Puerto de la base de datos	—
`MONGO_MAX_POOL_SIZE`	Tamano del pool de conexiones	`1000`
`MONGO_PARAMETERS`	Parametros adicionales de URI	—

RabbitMQ

Variable	Descripcion	Valor por defecto
`RABBITMQ_URI`	Esquema de URI (`amqp`)	—
`RABBITMQ_HOST`	Host de RabbitMQ	—
`RABBITMQ_PORT_AMQP`	Puerto AMQP	—
`RABBITMQ_PORT_HOST`	Puerto de administracion	—
`RABBITMQ_DEFAULT_USER`	Usuario	—
`RABBITMQ_DEFAULT_PASS`	Contrasena	—
`RABBITMQ_GENERATE_REPORT_QUEUE`	Nombre de la cola para generacion de informes	—
`RABBITMQ_NUMBERS_OF_WORKERS`	Numero de workers consumidores (solo worker)	`5`

Redis / Valkey

Variable	Descripcion	Valor por defecto
`REDIS_HOST`	Host de Redis con puerto (por ejemplo, `host:6379`)	—
`REDIS_PASSWORD`	Contrasena de Redis	—
`REDIS_DB`	Numero de base de datos	`0`
`REDIS_PROTOCOL`	Version del protocolo Redis	`3`
`REDIS_MASTER_NAME`	Nombre del master de Sentinel (si usa Sentinel)	—
`REDIS_TLS`	Habilitar TLS	`false`

Generacion de PDF (solo worker)

Variable	Descripcion	Valor por defecto
`PDF_POOL_WORKERS`	Numero de workers paralelos para generacion de PDF	`2`
`PDF_TIMEOUT_SECONDS`	Tiempo limite por generacion de PDF en segundos	`90`

Telemetria (OpenTelemetry)

Variable	Descripcion	Valor por defecto
`OTEL_RESOURCE_SERVICE_NAME`	Nombre del servicio para trazas	—
`OTEL_LIBRARY_NAME`	Nombre de la libreria de instrumentacion	—
`OTEL_RESOURCE_SERVICE_VERSION`	Version del servicio	—
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	Entorno de despliegue	—
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint del exportador OTLP	—
`ENABLE_TELEMETRY`	Habilitar recopilacion de telemetria	`false`

Autenticacion

Variable	Descripcion	Valor por defecto
`PLUGIN_AUTH_ADDRESS`	URL del servicio de autenticacion	—
`PLUGIN_AUTH_ENABLED`	Habilitar autenticacion	`false`

Licencia

Variable	Descripcion	Valor por defecto
`LICENSE_KEY`	Clave de licencia para Reporter	—
`ORGANIZATION_IDS`	IDs de organizacion para validacion de licencia	—

Introducción

Ejemplos de plantillas

Plantillas brasileñas

Usando Reporter

Uso tipico

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 dinamicos

Configuracion del almacenamiento

Variables de entorno de almacenamiento

Ejemplos de configuracion por proveedor

Configuracion de fuentes de datos externas

Variables de entorno de fuentes de datos

Ejemplo de fuente de datos unica

Fuente de datos con multiples esquemas

Comportamiento de conexion

Referencia completa de variables de entorno

Aplicacion

Almacenamiento de objetos (compatible con S3)

MongoDB

RabbitMQ

Redis / Valkey

Generacion de PDF (solo worker)

Telemetria (OpenTelemetry)

Autenticacion

Licencia

Introducción

Ejemplos de plantillas

Plantillas brasileñas

​Uso tipico

​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 dinamicos

​Configuracion del almacenamiento

​Variables de entorno de almacenamiento

​Ejemplos de configuracion por proveedor

​Configuracion de fuentes de datos externas

​Variables de entorno de fuentes de datos

​Ejemplo de fuente de datos unica

​Fuente de datos con multiples esquemas

​Comportamiento de conexion

​Referencia completa de variables de entorno

​Aplicacion

​Almacenamiento de objetos (compatible con S3)

​MongoDB

​RabbitMQ

​Redis / Valkey

​Generacion de PDF (solo worker)

​Telemetria (OpenTelemetry)

​Autenticacion

​Licencia

Uso tipico

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 dinamicos

Configuracion del almacenamiento

Variables de entorno de almacenamiento

Ejemplos de configuracion por proveedor

Configuracion de fuentes de datos externas

Variables de entorno de fuentes de datos

Ejemplo de fuente de datos unica

Fuente de datos con multiples esquemas

Comportamiento de conexion

Referencia completa de variables de entorno

Aplicacion

Almacenamiento de objetos (compatible con S3)

MongoDB

RabbitMQ

Redis / Valkey

Generacion de PDF (solo worker)

Telemetria (OpenTelemetry)

Autenticacion

Licencia