> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Plantillas de reportes
> Listar plantillas operativas Gu1 y encolar corridas async a object storage (email opcional).
## Resumen
Gu1 publica un **catálogo code-first** de plantillas operativas (alertas por reglas, exportaciones masivas y vistas de Metrics Hub). Las mismas plantillas alimentan **Reportería** (bajo demanda) y la acción de automation **`send_report` / Generar reporte** (`reportPresetId` o `reportTemplateCode` + params).
| Método | Path | Uso |
| ------ | ---------------------------------- | --------------------------------------------------- |
| `GET` | `/report-templates` | Listar catálogo (`category` opcional) |
| `GET` | `/report-templates/{code}` | Detalle + `parameterDefinitions` |
| `POST` | `/report-templates/{code}/preview` | Descargar vista previa CSV/PDF con datos de ejemplo |
| `POST` | `/report-templates/{code}/run` | Encolar exportación async (`download` o `email`) |
Todas las corridas operativas (**incluida `alerts_by_rules`**) encolan un job en segundo plano, guardan el archivo en object storage y responden **202** con `result.jobId`. Descargá después desde [Jobs de exportación de reportes](/es/api-reference/entities/report-export-jobs) (Reportería **Descargables**). Comparten el **cooldown** de export por organización cuando aplica.
## Autenticación y tenant
`Bearer YOUR_API_KEY` — ver [Autenticación](/es/api-reference/authentication).
UUID de organización producción o sandbox — ver [Entornos](/es/api-reference/environments).
## Permisos
| Endpoint | Permiso granular |
| -------------------- | ---------------- |
| `GET` list / get | `reports:read` |
| `POST` preview / run | `reports:export` |
## Listar plantillas
```
GET http://api.gu1.ai/report-templates
```
Filtro opcional: `alerts`, `metrics`, `entities`, `transactions`, `investigations`.
## Obtener una plantilla
```
GET http://api.gu1.ai/report-templates/{code}
```
Responde `404` con `REPORT_TEMPLATE_NOT_FOUND` si el código no existe.
## Vista previa (datos de ejemplo)
```
POST http://api.gu1.ai/report-templates/{code}/preview
```
Devuelve un archivo **CSV** o **PDF** con filas de demostración (no consulta datos del tenant).
`csv` (default) o `pdf`.
Opcional: `es`, `en` o `pt` (copy del PDF).
Respuesta: binario con `Content-Disposition: attachment` (`preview-{code}.csv|pdf`).
## Ejecutar una plantilla
```
POST http://api.gu1.ai/report-templates/{code}/run
```
Parámetros de la plantilla (`lookbackDays`, `ruleIds`, `emailLocale`, `filters`, etc.).
Debe estar en `formats` de la plantilla. Default: `defaultFormat`.
`download` (solo encolar job) o `email` (encolar job + enviar correo). La UI de Reportería siempre usa `download`.
Obligatorio si `delivery` es `email`.
### Respuesta (202)
```json theme={null}
{
"success": true,
"result": {
"success": true,
"jobId": "…",
"status": "queued",
"delivery": "download"
}
}
```
### Semántica: `alerts_by_rules`
Exporta **alertas ya creadas** del tenant cuyo `alerted_at` cae en la ventana `lookbackDays`.
* **`ruleIds`** (array UUID, opcional): si se envía, filtra `trigger_rule_id IN (...)`. Vacío = todas las reglas.
* Columnas: entidad, tax ID, alerta, severidad, estado, score, regla, nº de investigación, link al caso/alerta, fecha.
* Orden: nombre de entidad, luego fecha de alerta.
* No recalcula la matriz ni inventa umbrales: solo lista alertas persistidas.
### Rate limit
Si hubo otra exportación reciente en la org, puede responder **429** con `EXPORT_RATE_LIMIT`, header `Retry-After` y `retryAfterSeconds` / `cooldownSeconds` en `error.details`.
### Ejemplo
```json theme={null}
{
"params": {
"lookbackDays": 30,
"ruleIds": ["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"]
},
"format": "xlsx",
"delivery": "email",
"recipientEmails": ["ops@example.com"]
}
```
### Respuesta 202 (email)
```json theme={null}
{
"success": true,
"result": {
"success": true,
"code": "alerts_by_rules",
"delivery": "email",
"jobId": "…",
"status": "queued"
}
}
```
### Respuesta 202 (download)
```json theme={null}
{
"success": true,
"result": {
"success": true,
"code": "alerts_by_rules",
"delivery": "download",
"jobId": "…",
"status": "queued"
}
}
```
## Automations
La entrega programada usa `send_report` (**Generar reporte**) con:
* **`reportPresetId`** (canónico): ejecuta el preset congelado; siempre crea un job en S3. Con `sendEmail: true` y `recipientEmails` también envía el archivo por correo.
* Legacy: `reportTemplateCode` + `params`, o `reportType` sin preset.
Deep-link desde Reportería **Programar**: `/automations/builder?type=scheduled&reportPresetId=…`.
Ver [Jobs de exportación de reportes](/es/api-reference/entities/report-export-jobs) para Descargables.
## Filtros configurables
Las plantillas operativas exponen un constructor `campo → operador → valor`. Enviá las condiciones en `params.filters`; todas se combinan con **Y**. Una lista vacía incluye todos los registros. Los [presets de reportes](/es/api-reference/entities/report-presets) congelan las condiciones completas.
Los campos con catálogo cambian el control según el operador: `equals` recibe un valor único y `in` recibe un array. Por ejemplo, país puede usar `{ "operator": "equals", "value": "AR" }` o `{ "operator": "in", "value": ["AR", "BR"] }`.
```json theme={null}
{
"params": {
"filters": [
{ "id": "f1", "field": "tax_id", "operator": "in_custom_list", "value": "11111111-1111-4111-8111-111111111111" },
{ "id": "f2", "field": "age", "operator": "gte", "value": "18" },
{ "id": "f3", "field": "is_pep", "operator": "is_true", "value": "" }
]
},
"format": "xlsx",
"delivery": "download"
}
```
* **Alertas:** regla (`in`), severidad, estado, tipo afectado, score, falso positivo, fecha y tipo de alerta.
* **Entidades:** tipo, estado, Tax ID exacto o en lista personalizada, país, ID externo, búsqueda, edad, score, estado KYC, regla con hit, fechas de alta/enriquecimiento, PEP, sanciones, medios adversos, MEI, procesos legales —incluidos criminales—, socios, relaciones, actividad electoral, actividades económicas e investigaciones activas.
* **Transacciones:** tipo, estado, medio de pago, score, monto, moneda, fecha, regla con hit, Tax ID relacionado, IDs externos de origen/destino, autotransacción, ausencia de evaluación, hit de regla shadow, búsqueda, marcada y presencia de alertas.
* **Investigaciones:** estado, prioridad, tipología, score, tipo de objetivo, fechas de creación/actualización y búsqueda en título/descripción.
Los operadores disponibles dependen del campo: `equals`, `contains`, `in`, `gte`, `lte`, `between`, `before`, `after`, `is_true`, `is_false`, `in_custom_list` y `not_in_custom_list`. El catálogo devuelto por `GET /report-templates` incluye `filterFields` con los operadores y opciones válidos para cada plantilla.