> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Usar Reporter > Gestiona plantillas de Reporter, genera informes regulatorios bajo demanda, haz seguimiento de su estado y descarga los archivos terminados. 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](/es/products/reporter/template-examples) y la [referencia de plantillas](/es/products/reporter/template-reference). *** ## 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](/es/reference/products/reporter/upload-template) como 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 usas al generar informes. ### Mantener las plantillas existentes Usa los endpoints de plantillas para: * [Listar plantillas](/es/reference/products/reporter/list-templates). * [Consultar los detalles de una plantilla](/es/reference/products/reporter/retrieve-template-details). * [Actualizar una plantilla](/es/reference/products/reporter/update-templates). * [Eliminar una plantilla](/es/reference/products/reporter/delete-template). 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](/es/reference/products/reporter/create-report) 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: ```json theme={null} { "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: ```json theme={null} { "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](/es/products/reporter/template-reference#advanced-filtering) 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](/es/reference/products/reporter/list-data-sources) devuelve una página de conexiones registradas sin credenciales. * [Consultar una fuente de datos](/es/reference/products/reporter/retrieve-data-source) devuelve la configuración de una conexión según su `dataSourceId`. Las credenciales permanecen ocultas. * `GET /v1/data-sources/{dataSourceId}/schema` 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. Los despliegues de un solo tenant también pueden sembrar entradas desde variables `DATASOURCE_*` al iniciar. Los despliegues multi-tenant crean entradas por tenant a través de la API. *** ## Interpretar los estados y errores del informe Llama a [Consultar el estado de un informe](/es/reference/products/reporter/check-report-status) 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 solo `Finished` como descargable. Un resultado `Partial` requiere investigación aunque Reporter haya generado algunos datos. *** ## Verificar y descargar el informe Cuando el estado es `Finished`: 1. Llama a [Descargar un informe](/es/reference/products/reporter/download-report) con `REPORT_ID`. 2. Confirma que la respuesta tiene el tipo de contenido esperado y el encabezado `Content-Disposition`. 3. Abre el archivo y verifica que sus datos y su diseño correspondan a la plantilla y a los filtros. El endpoint de descarga solo sirve informes con estado `Finished`. *** ## Solución de problemas | Síntoma | Qué revisar | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Se rechaza la subida de la plantilla | Envía `template`, `outputFormat` y `description`, 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 solo están disponibles cuando es `Finished`. | *** ## 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` | ```env theme={null} 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. ```env theme={null} 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 ``` ```env theme={null} 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) 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 falla 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 modo multi-tenant, Reporter omite la siembra por variables de entorno y cada tenant crea sus propias entradas a través de la API. En modo de un solo tenant, puedes sembrar entradas de PostgreSQL o MongoDB al iniciar con variables `DATASOURCE__*`: | Variable | Descripción | Obligatoria | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | | `DATASOURCE__CONFIG_NAME` | Identificador usado en las plantillas, como `midaz_onboarding`. | Sí | | `DATASOURCE__HOST` | Host de la base de datos. | Sí | | `DATASOURCE__PORT` | Puerto de la base de datos. | Sí | | `DATASOURCE__USER` | Usuario de la base de datos. | Solo cuando la base de datos requiere autenticación de usuario | | `DATASOURCE__PASSWORD` | Contraseña de la base de datos. | Solo cuando la base de datos requiere autenticación por contraseña | | `DATASOURCE__DATABASE` | Nombre de la base de datos. | Sí | | `DATASOURCE__TYPE` | `postgresql` o `mongodb`, en minúsculas. | Sí | | `DATASOURCE__SSLMODE` | Modo SSL de PostgreSQL, como `disable` o `require`. | Solo PostgreSQL | | `DATASOURCE__SSLROOTCERT` | Ruta del certificado raíz de PostgreSQL. | Solo PostgreSQL | | `DATASOURCE__SSL` | Habilita SSL para MongoDB. | Solo MongoDB | | `DATASOURCE__SSLCA` | Ruta del certificado CA de MongoDB. | Solo MongoDB | | `DATASOURCE__OPTIONS` | Opciones adicionales de la URI de MongoDB. | Solo MongoDB | | `DATASOURCE__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`: ```env theme={null} 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`: ```django theme={null} {% 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`: ```env theme={null} 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: ```django theme={null} {% for order in external_db:sales.orders %} {{ order.id }} - {{ order.total }} {% endfor %} ``` ```json theme={null} { "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 carga la configuración de la fuente de datos y se conecta bajo demanda. El Worker se conecta durante el inicio y reintenta las fuentes no disponibles. Puede seguir funcionando con capacidad reducida cuando una fuente permanece no disponible. *** ## Tareas relacionadas * [Primeros pasos con Reporter](/es/products/reporter/reporter-quick-start) * [Conectar Reporter con Midaz](/es/products/reporter/connecting-reporter-to-midaz) * [Crear plantillas](/es/products/reporter/template-reference) * [Revisar ejemplos de plantillas](/es/products/reporter/template-examples)