Usar Reporter

Usa esta guía para el workflow recurrente de Reporter: gestiona una plantilla, genera un informe, verifica el resultado y descarga el archivo terminado.

Requisitos previos

Antes de empezar, confirma que:

Reporter está en ejecución y puedes autenticarte con su API.
Un operador configuró al menos una fuente de datos para los datos que consulta tu plantilla.
Tienes un archivo .tpl que corresponde al formato de salida deseado. Para la salida en PDF, escribe la plantilla como HTML. Consulta Ejemplos de plantillas y la referencia de plantillas.

Gestionar plantillas

Reporter usa los archivos .tpl subidos para definir el contenido y el diseño del informe.

Subir una plantilla

Llama a Subir una plantilla como una solicitud multipart con los cuatro 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.
category: la familia del informe, como cadoc. Usa letras minúsculas, dígitos, guiones bajos y guiones, con hasta 100 caracteres.

Reporter devuelve el identificador de la plantilla que usas al generar informes.

Mantener las 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 ya creados a partir de ella.

Generar un informe con filtros

Llama a Crear un informe con los dos campos obligatorios:

templateId: el identificador que se devolvió al subir 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 admitidos y la estructura de los filtros.

Descubrir los esquemas de las fuentes de datos

Inspecciona las fuentes de datos configuradas antes de crear plantillas o interfaces de filtro dinámicas:

Listar fuentes de datos devuelve una página de conexiones registradas sin credenciales.
Consultar una fuente de datos devuelve la configuración de una conexión según su dataSourceId. Las credenciales permanecen ocultas.
Obtener el esquema de una fuente de datos inspecciona las tablas o colecciones en vivo y sus campos tipados.

La API controla el ciclo de vida del registro: crear una fuente de datos, actualizarla parcialmente, probar la conexión, inspeccionar su esquema o eliminarla de forma lógica. Reporter rechaza la eliminación mientras una plantilla activa siga referenciando la fuente. Un despliegue self-hosted también puede sembrar entradas desde variables DATASOURCE_* al iniciar.

Interpretar los estados y errores del informe

Llama a Consultar el estado de un informe con REPORT_ID.

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

Trata como descargables los informes Finished y Final, y un Draft sin campo obligatorio en blanco. Un resultado Partial requiere investigación aunque Reporter haya generado algunos datos.

Verificar y descargar el informe

Cuando el estado es Finished:

Llama a Descargar un informe con REPORT_ID.
Confirma que la respuesta tiene el tipo de contenido esperado y el encabezado Content-Disposition.
Abre el archivo y verifica que sus datos y su diseño correspondan a la plantilla y a los filtros.

Solución de problemas

Síntoma	Qué revisar
Se rechaza la subida de la plantilla	Envía `template`, `outputFormat`, `description` y `category`, y confirma que el archivo usa la extensión `.tpl`.
Se rechaza la creación del informe	Envía tanto `templateId` como `filters`. Usa `"filters": {}` cuando no necesites filtrar filas.
El informe permanece en `Processing`	Revisa el estado del Worker, la conectividad con RabbitMQ y las fuentes de datos referenciadas.
El informe termina como `Partial`	Revisa qué secciones de datos fallaron y verifica su fuente, tabla, campo y nombres de filtro.
El informe termina como `Error`	Revisa el error devuelto, la sintaxis de la plantilla, los valores de los filtros, la conectividad con la fuente de datos y el almacenamiento de objetos.
Se rechaza la descarga	Revisa el último estado. Las descargas están disponibles para informes `Finished` y `Final`, y para un `Draft` sin campo obligatorio en blanco.

Configuración del operador

Los siguientes ajustes de despliegue son para operadores. Los usuarios de la aplicación no los necesitan 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 URLs con estilo de ruta. MinIO y SeaweedFS suelen requerirlo.	`false`
`OBJECT_STORAGE_DISABLE_SSL`	Usa HTTP en lugar de HTTPS cuando `OBJECT_STORAGE_ENDPOINT` no tiene un esquema. Un esquema explícito `http://` o `https://` 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 siguen 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 las políticas de ciclo de vida del bucket de S3 si los informes generados deben expirar automáticamente.

Configurar fuentes de datos externas

Configura DATASOURCE_CRED_ENC_KEY con una clave AES hexadecimal persistente antes de iniciar Reporter. Genera una clave de 32 bytes con openssl rand -hex 32. El Manager y el Worker fallan al iniciar si la clave falta o tiene un formato inválido. Mantén la misma clave disponible para cada runtime de Reporter que lea el registro, porque las contraseñas guardadas están cifradas con ella. Usa la API para el ciclo de vida normal de las fuentes de datos. En un despliegue self-hosted, también puedes sembrar entradas de PostgreSQL o MongoDB al iniciar con variables 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 por 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>_SSLCA_BASE64`	Base64 estándar de un paquete CA en PEM, como alternativa a la ruta de un archivo de certificado. Para PostgreSQL, define `SSLMODE` como `verify-ca` o `verify-full`, o déjalo vacío para `verify-full`.	No
`DATASOURCE_<NAME>_OPTIONS`	Opciones adicionales de la URI de MongoDB.	Solo MongoDB
`DATASOURCE_<NAME>_ROW_CEILING`	Filas que puede devolver una tabla. El valor predeterminado es `DATASOURCE_DEFAULT_ROW_CEILING`.	No
`DATASOURCE_<NAME>_QUERY_TIMEOUT_SEC`	Tiempo de espera de la consulta, en segundos. El valor predeterminado es `DATASOURCE_DEFAULT_QUERY_TIMEOUT_SEC`.	No
`DATASOURCE_<CONFIG_NAME>_SCHEMAS`	Esquemas de PostgreSQL a exponer, 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 ella en una plantilla mediante su CONFIG_NAME:

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

Para varios esquemas de PostgreSQL, deriva la variable del esquema a partir 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 el filtro:

{% 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 la variable del esquema no está definida, Reporter usa el esquema public. El Manager y el Worker se conectan a una fuente de datos bajo demanda, cuando una solicitud la necesita.

Resumen

Conceptos

Guías

Integración

Console

Operaciones

Requisitos previos

Gestionar plantillas

Subir una plantilla

Mantener las plantillas existentes

Generar un informe con filtros

Descubrir los esquemas de las fuentes de datos

Interpretar los estados y errores del informe

Verificar y descargar el informe

Solución de problemas

Configuración del operador

Configurar el almacenamiento de objetos

Configurar fuentes de datos externas

Tareas relacionadas

​Requisitos previos

​Gestionar plantillas

​Subir una plantilla

​Mantener las plantillas existentes

​Generar un informe con filtros

​Descubrir los esquemas de las fuentes de datos

​Interpretar los estados y errores del informe

​Verificar y descargar el informe

​Solución de problemas

​Configuración del operador

​Configurar el almacenamiento de objetos

​Configurar fuentes de datos externas

​Tareas relacionadas

Requisitos previos

Gestionar plantillas

Subir una plantilla

Mantener las plantillas existentes

Generar un informe con filtros

Descubrir los esquemas de las fuentes de datos

Interpretar los estados y errores del informe

Verificar y descargar el informe

Solución de problemas

Configuración del operador

Configurar el almacenamiento de objetos

Configurar fuentes de datos externas

Tareas relacionadas