Inicio rápido de la API de Reporter

Empieza a usar la API de Reporter: autentícate, sube una plantilla y genera tu primer informe con esta guía rápida pensada para desarrolladores.

Esta guía está dirigida a desarrolladores. Si buscas una visión general a nivel de negocio de lo que hace Reporter, consulta ¿Qué es Reporter?.

Pon Reporter en funcionamiento en minutos. Esta guía recorre el camino completo, desde la carga de tu primera plantilla hasta la descarga de un reporte generado.

​

Antes de comenzar

---

Necesitas:

• Una instancia de Reporter en ejecución
• Un token de autenticación válido (si Access Manager está habilitado)
• Un archivo de plantilla .tpl listo para cargar

Todos los ejemplos usan cURL. Reemplaza $TOKEN con tu token de autenticación y https://reporter.example.com con la URL de tu Reporter.

​

Paso 1: Cargar una plantilla

---

Carga un archivo .tpl que define la estructura y contenido de tu reporte. El contenido de la plantilla debe coincidir con el formato de salida seleccionado: HTML para HTML y PDF, XML para XML, CSV para CSV y texto no vacío para TXT. El archivo cargado debe tener extensión .tpl.

Referencia de API: Cargar plantilla

cURL

curl -X POST "https://reporter.example.com/v1/templates" \
 -H "Authorization: Bearer $TOKEN" \
 -F "template=@account_summary.tpl" \
 -F "outputFormat=PDF" \
 -F "description=Reporte de resumen diario de cuentas"

{
  "id": "0196b270-a315-7137-9408-3f16af2685e1",
  "outputFormat": "pdf",
  "description": "Reporte de resumen diario de cuentas",
  "fileName": "0196b270-a315-7137-9408-3f16af2685e1.tpl",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:00:00Z"
}

Guarda el id de la plantilla. Lo usarás para generar reportes.

​

Formatos de salida soportados

Formato	Caso de uso
CSV	Exportaciones de datos e integración con hojas de cálculo
XML	Datos estructurados y envíos regulatorios
HTML	Reportes visualizables en navegador
PDF	Documentos listos para imprimir y compartir
TXT	Texto plano e integración con sistemas legados

​

Paso 2: Verificar la plantilla

---

Lista tus plantillas para confirmar que la carga fue exitosa.

Referencia de API: Listar plantillas

cURL

curl -X GET "https://reporter.example.com/v1/templates" \
 -H "Authorization: Bearer $TOKEN"

​

Paso 3: Generar un reporte

---

Envía una solicitud de generación de reporte con el ID de la plantilla y el objeto obligatorio filters. Agrega filtros para acotar los datos o envía {} si no necesitas filtrarlos.

Referencia de API: Crear reporte

cURL

curl -X POST "https://reporter.example.com/v1/reports" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "templateId": "0196b270-a315-7137-9408-3f16af2685e1",
   "filters": {
     "midaz_onboarding": {
       "account": {
         "created_at": {
           "between": ["2026-03-01", "2026-03-05"]
         }
       }
     }
   }
 }'

{
  "id": "0196c5c0-5044-724f-95f3-4b32076e7ad7",
  "templateId": "0196b270-a315-7137-9408-3f16af2685e1",
  "templateOutputFormat": "pdf",
  "templateDescription": "Reporte de resumen diario de cuentas",
  "filters": {
    "midaz_onboarding": {
      "account": {
        "created_at": {
          "between": ["2026-03-01", "2026-03-05"]
        }
      }
    }
  },
  "status": "Processing",
  "metadata": null,
  "completedAt": null,
  "createdAt": "2026-03-05T10:05:00Z",
  "updatedAt": "2026-03-05T10:05:00Z",
  "deletedAt": null
}

Guarda el id del reporte para los siguientes pasos.

​

Estructura de filtros

Los filtros siguen la ruta: fuente de datos > tabla > campo > operador > valores.

Operador	Descripción	Ejemplo
eq	Igual a	{ "eq": ["active"] }
gt / gte	Mayor que / mayor o igual	{ "gte": ["2026-01-01"] }
lt / lte	Menor que / menor o igual	{ "lt": [1000] }
between	Valor dentro de un rango	{ "between": ["2026-03-01", "2026-03-31"] }
in / nin	Valor en / no en una lista	{ "in": ["active", "pending"] }

El campo filters es obligatorio. Para generar un reporte sin filtros, envía un objeto vacío: "filters": {}.

​

Paso 4: Verificar estado del reporte

---

La generación de reportes es asíncrona. Consulta el endpoint de estado hasta que el reporte esté listo.

Referencia de API: Verificar estado del reporte

cURL

curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7" \
 -H "Authorization: Bearer $TOKEN"

Estado	Significado
Processing	Reporter está consultando datos y renderizando la plantilla
Finished	El reporte está listo para descargar
Partial	Algunas secciones de datos se generaron y otras fallaron; el campo metadata del reporte contiene los códigos de error por sección
Error	Un error impidió que se generara el reporte.

Espera el estado Finished antes de proceder a la descarga.

​

Paso 5: Descargar el reporte

---

Una vez que el reporte está finalizado, descarga el archivo generado.

Referencia de API: Descargar reporte

cURL

curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7/download" \
 -H "Authorization: Bearer $TOKEN" \
 -o account_summary.pdf

El archivo se devuelve con encabezados Content-Disposition indicando el nombre del archivo y formato.

​

Paso 6: Explorar fuentes de datos

---

Para entender qué datos están disponibles para tus plantillas, lista las fuentes de datos configuradas. Luego usa GET /v1/data-sources/{dataSourceId} para inspeccionar el esquema de una fuente de datos.

Referencia de API: Listar fuentes de datos | Obtener fuente de datos

cURL

curl -X GET "https://reporter.example.com/v1/data-sources" \
 -H "Authorization: Bearer $TOKEN"

La respuesta de listado identifica cada fuente de datos. La respuesta de detalle incluye las tablas y campos disponibles, que puedes referenciar en tus plantillas con la sintaxis {{ datasource.table.field }}.

​

Próximos pasos

---

¿Qué es Reporter?

Descripción completa de la sintaxis de plantillas, tags y filtros.

Formatos de plantillas

Ejemplos prácticos para plantillas HTML, XML y TXT.

Usando Reporter

Guía detallada sobre plantillas, almacenamiento y configuración de fuentes de datos.

Manejo de errores

Lista completa de códigos de error y cómo resolverlos.