Usar Reporter - Lerian

Usa esta guía para el flujo recurrente de Reporter: gestionar una plantilla, generar un informe, verificar el resultado y descargar el archivo terminado.

Requisitos previos

Antes de comenzar, comprueba lo siguiente:

Reporter está en ejecución y puedes autenticarte en su API.
Un operador configuró al menos una fuente para los datos que consulta tu plantilla.
Tienes un archivo .tpl que corresponde al formato de salida esperado. Consulta los ejemplos de plantillas y la referencia de plantillas.

Gestionar plantillas

Reporter usa archivos .tpl cargados para definir el contenido y la presentación de los informes.

Cargar una plantilla

Llama a Cargar una plantilla mediante una solicitud multipart con los tres campos obligatorios:

template: el archivo .tpl.
outputFormat: el formato del archivo generado, como HTML, PDF, XML, CSV o TXT.
description: una descripción legible de la plantilla.

Reporter devuelve el identificador de la plantilla que usarás para generar informes.

Mantener plantillas existentes

Usa los endpoints de plantillas para:

Eliminar una plantilla es una eliminación lógica. Reporter la excluye de las consultas estándar, pero conserva los informes creados a partir de ella.

Generar un informe con filtros

Llama a Crear un informe con los dos campos obligatorios:

templateId: el identificador devuelto al cargar la plantilla.
filters: las condiciones agrupadas por fuente de datos, tabla y campo.

La siguiente solicitud limita el informe a una transacción:

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

Para generar un informe sin filtrar filas, envía un objeto vacío. No omitas el campo:

{
  "templateId": "0196159b-4f26-7300-b3d9-f4f68a7c85f3",
  "filters": {}
}

Reporter devuelve el identificador del informe en el campo id. Guarda este valor como REPORT_ID para consultar el estado de generación y recuperar el resultado. Consulta Filtrado avanzado para conocer los operadores compatibles y la estructura de los filtros.

Descubrir esquemas de fuentes de datos

Examina las fuentes configuradas antes de crear plantillas o interfaces de filtros dinámicos:

Listar fuentes de datos devuelve las fuentes disponibles, sus esquemas y sus tablas.
Obtener una fuente de datos devuelve las tablas y los campos de una fuente.

Estos endpoints son de solo lectura. Los operadores configuran las fuentes durante el despliegue; la API no las crea ni las actualiza.

Interpretar estados y errores

Llama a Consultar el estado del informe con REPORT_ID.

Estado	Significado	Qué hacer
`Processing`	Reporter está generando el archivo.	Sigue consultando el estado con un intervalo razonable.
`Finished`	La generación finalizó correctamente.	Descarga el informe.
`Partial`	Reporter generó solo una parte del resultado solicitado.	Examina los detalles de la respuesta y corrige las secciones de datos que fallaron antes de volver a generar.
`Error`	La generación falló.	Examina los detalles del error, la plantilla, los filtros y la disponibilidad de las fuentes de datos.

Trata solo Finished como descargable. Un resultado Partial requiere investigación aunque Reporter haya generado algunos datos.

Verificar y descargar el informe

Cuando el estado sea Finished:

Llama a Descargar un informe con REPORT_ID.
Confirma que la respuesta tenga el tipo de contenido esperado y el encabezado Content-Disposition.
Abre el archivo y comprueba que los datos y la presentación correspondan a la plantilla y los filtros.

El endpoint de descarga solo entrega informes con estado Finished.

Solución de problemas

Síntoma	Qué comprobar
La carga de la plantilla se rechaza	Envía `template`, `outputFormat` y `description`, y confirma que el archivo use la extensión `.tpl`.
La creación del informe se rechaza	Envía `templateId` y `filters`. Usa `"filters": {}` cuando no necesites filtros de filas.
El informe permanece en `Processing`	Comprueba la salud del Worker, la conexión con RabbitMQ y las fuentes de datos usadas.
El informe termina como `Partial`	Examina qué secciones fallaron y verifica los nombres de la fuente, la tabla, el campo y los filtros.
El informe termina como `Error`	Comprueba el error devuelto, la sintaxis de la plantilla, los valores de filtro, las conexiones a fuentes de datos y el almacenamiento de objetos.
La descarga se rechaza	Consulta el estado más reciente. Solo puedes descargar el informe cuando sea `Finished`.

Configuración para operadores

Las siguientes opciones de despliegue están dirigidas a operadores. No las necesitas para el flujo de generación de informes.

Configurar el almacenamiento de objetos

Reporter guarda las plantillas y los informes generados en un bucket compatible con S3. Usa los prefijos templates/ y reports/. Reporter admite AWS S3, MinIO y SeaweedFS.

Variable	Descripción	Valor predeterminado
`OBJECT_STORAGE_ENDPOINT`	Endpoint compatible con S3. Déjalo vacío para AWS 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`	Usa URL de estilo path. MinIO y SeaweedFS suelen requerirlo.	`false`
`OBJECT_STORAGE_DISABLE_SSL`	Usa HTTP en lugar de HTTPS cuando `OBJECT_STORAGE_ENDPOINT` no incluye un esquema. Un esquema `http://` o `https://` explícito tiene prioridad.	`false`
`OBJECT_STORAGE_BUCKET`	Nombre del bucket.	`reporter-storage`

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

Los ejemplos de MinIO y SeaweedFS que aparecen a continuación usan HTTP solo para desarrollo local. Los despliegues de producción requieren HTTPS y TLS.

MinIO (desarrollo local)

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 admite TTL por objeto. Configura políticas de ciclo de vida del bucket de S3 si los informes generados deben caducar automáticamente.

Configurar fuentes de datos externas

Define cada fuente PostgreSQL o MongoDB mediante variables de entorno DATASOURCE_<NAME>_*.

Variable	Descripción	Obligatoria
`DATASOURCE_<NAME>_CONFIG_NAME`	Identificador usado en las plantillas, como `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.	Solo cuando la base de datos requiere autenticación de usuario
`DATASOURCE_<NAME>_PASSWORD`	Contraseña de la base de datos.	Solo cuando la base de datos requiere autenticación con contraseña
`DATASOURCE_<NAME>_DATABASE`	Nombre de la base de datos.	Sí
`DATASOURCE_<NAME>_TYPE`	`postgresql` o `mongodb`, en minúsculas.	Sí
`DATASOURCE_<NAME>_SSLMODE`	Modo SSL de PostgreSQL, como `disable` o `require`.	Solo PostgreSQL
`DATASOURCE_<NAME>_SSLROOTCERT`	Ruta del certificado raíz de PostgreSQL.	Solo PostgreSQL
`DATASOURCE_<NAME>_SSL`	Habilita SSL para MongoDB.	Solo MongoDB
`DATASOURCE_<NAME>_SSLCA`	Ruta del certificado CA de MongoDB.	Solo MongoDB
`DATASOURCE_<NAME>_OPTIONS`	Opciones adicionales de la URI de MongoDB.	Solo MongoDB
`DATASOURCE_<CONFIG_NAME>_SCHEMAS`	Esquemas PostgreSQL que se exponen, separados por comas. El prefijo de la variable se deriva de `CONFIG_NAME`.	Solo PostgreSQL

Para una fuente cuyo CONFIG_NAME es midaz_onboarding:

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

Haz referencia a la fuente en una plantilla mediante su CONFIG_NAME:

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

Para usar varios esquemas de PostgreSQL, deriva la variable de esquemas de CONFIG_NAME. Por ejemplo, external_db corresponde a DATASOURCE_EXTERNAL_DB_SCHEMAS:

DATASOURCE_EXTERNAL_CONFIG_NAME=external_db
DATASOURCE_EXTERNAL_HOST=external-postgres
DATASOURCE_EXTERNAL_PORT=5432
DATASOURCE_EXTERNAL_USER=db_user
DATASOURCE_EXTERNAL_PASSWORD=CHANGE_ME
DATASOURCE_EXTERNAL_DATABASE=external_database
DATASOURCE_EXTERNAL_TYPE=postgresql
DATASOURCE_EXTERNAL_SSLMODE=require
DATASOURCE_EXTERNAL_DB_SCHEMAS=sales,inventory,reporting

Usa database:schema.table en las plantillas y schema.table como clave de tabla en los filtros:

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

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

Cuando no defines la variable de esquemas, Reporter usa el esquema public. El Manager carga la configuración de las fuentes de datos y se conecta bajo demanda. El Worker se conecta durante el inicio y reintenta las fuentes no disponibles. Puede continuar con funcionalidad reducida si una fuente sigue sin estar disponible.

​Requisitos previos

​Gestionar plantillas

​Cargar una plantilla

​Mantener plantillas existentes

​Generar un informe con filtros

​Descubrir esquemas de fuentes de datos

​Interpretar estados y errores

​Verificar y descargar el informe

​Solución de problemas

​Configuración para operadores

​Configurar el almacenamiento de objetos

​Configurar fuentes de datos externas

​Tareas relacionadas

Requisitos previos

Gestionar plantillas

Cargar una plantilla

Mantener plantillas existentes

Generar un informe con filtros

Descubrir esquemas de fuentes de datos

Interpretar estados y errores

Verificar y descargar el informe

Solución de problemas

Configuración para operadores

Configurar el almacenamiento de objetos

Configurar fuentes de datos externas

Tareas relacionadas