> ## 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.
# Modelos de relatórios
> Listar modelos operacionais Gu1 e enfileirar execuções async para object storage (e-mail opcional).
## Resumo
A Gu1 publica um **catálogo code-first** de modelos operacionais (alertas por regras, exportações em massa e vistas do Metrics Hub). Os mesmos modelos alimentam **Relatórios** (sob demanda) e a ação de automation **`send_report` / Gerar relatório** (`reportPresetId` ou `reportTemplateCode` + params).
| Método | Path | Uso |
| ------ | ---------------------------------- | --------------------------------------------------- |
| `GET` | `/report-templates` | Listar catálogo (`category` opcional) |
| `GET` | `/report-templates/{code}` | Detalhe + `parameterDefinitions` |
| `POST` | `/report-templates/{code}/preview` | Baixar preview CSV/PDF com dados de exemplo |
| `POST` | `/report-templates/{code}/run` | Enfileirar exportação async (`download` ou `email`) |
Todas as execuções operacionais (**incluindo `alerts_by_rules`**) enfileiram um job em segundo plano, gravam o arquivo em object storage e respondem **202** com `result.jobId`. Baixe depois em [Jobs de exportação de relatórios](/pt/api-reference/entities/report-export-jobs) (Relatórios **Downloads**). Compartilham o **cooldown** de export por organização quando aplicável.
## Autenticação e tenant
`Bearer YOUR_API_KEY` — ver [Autenticação](/pt/api-reference/authentication).
UUID da organização produção ou sandbox — ver [Ambientes](/pt/api-reference/environments).
## Permissões
| Endpoint | Permissão granular |
| -------------------- | ------------------ |
| `GET` list / get | `reports:read` |
| `POST` preview / run | `reports:export` |
## Listar modelos
```
GET http://api.gu1.ai/report-templates
```
Filtro opcional: `alerts`, `metrics`, `entities`, `transactions`, `investigations`.
## Obter um modelo
```
GET http://api.gu1.ai/report-templates/{code}
```
Retorna `404` com `REPORT_TEMPLATE_NOT_FOUND` se o código não existir.
## Pré-visualização (dados de exemplo)
```
POST http://api.gu1.ai/report-templates/{code}/preview
```
Retorna um arquivo **CSV** ou **PDF** com linhas de demonstração (não consulta dados do tenant).
`csv` (default) ou `pdf`.
Opcional: `es`, `en` ou `pt` (copy do PDF).
Resposta: binário com `Content-Disposition: attachment` (`preview-{code}.csv|pdf`).
## Executar um modelo
```
POST http://api.gu1.ai/report-templates/{code}/run
```
Parâmetros do modelo (`lookbackDays`, `ruleIds`, `emailLocale`, `filters`, etc.).
Deve estar em `formats` do modelo. Default: `defaultFormat`.
`download` (apenas enfileirar job) ou `email` (enfileirar job + enviar e-mail). A UI de Relatórios sempre usa `download`.
Obrigatório se `delivery` for `email`.
### Resposta (202)
```json theme={null}
{
"success": true,
"result": {
"success": true,
"jobId": "…",
"status": "queued",
"delivery": "download"
}
}
```
### Semântica: `alerts_by_rules`
Exporta **alertas já criadas** do tenant cujo `alerted_at` cai na janela `lookbackDays`.
* **`ruleIds`** (array UUID, opcional): se enviado, filtra `trigger_rule_id IN (...)`. Vazio = todas as regras.
* Colunas: entidade, tax ID, alerta, severidade, status, score, regra, nº da investigação, link do caso/alerta, data.
* Ordem: nome da entidade, depois data da alerta.
* Não recalcula a matriz nem inventa limiares: apenas lista alertas persistidas.
### Rate limit
Se houve outra exportação recente na org, pode responder **429** com `EXPORT_RATE_LIMIT`, header `Retry-After` e `retryAfterSeconds` / `cooldownSeconds` em `error.details`.
### Exemplo
```json theme={null}
{
"params": {
"lookbackDays": 30,
"ruleIds": ["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"]
},
"format": "xlsx",
"delivery": "email",
"recipientEmails": ["ops@example.com"]
}
```
### Resposta 202 (email)
```json theme={null}
{
"success": true,
"result": {
"success": true,
"code": "alerts_by_rules",
"delivery": "email",
"jobId": "…",
"status": "queued"
}
}
```
### Resposta 202 (download)
```json theme={null}
{
"success": true,
"result": {
"success": true,
"code": "alerts_by_rules",
"delivery": "download",
"jobId": "…",
"status": "queued"
}
}
```
## Automations
A entrega agendada usa `send_report` (**Gerar relatório**) com:
* **`reportPresetId`** (canônico): executa o preset congelado; sempre cria um job no S3. Com `sendEmail: true` e `recipientEmails` também envia o arquivo por e-mail.
* Legacy: `reportTemplateCode` + `params`, ou `reportType` sem preset.
Deep-link a partir de Relatórios **Agendar**: `/automations/builder?type=scheduled&reportPresetId=…`.
Ver [Jobs de exportação de relatórios](/pt/api-reference/entities/report-export-jobs) para Downloads.
## Filtros configuráveis
Os templates operacionais oferecem um construtor `campo → operador → valor`. Envie as condições em `params.filters`; todas são combinadas com **E**. Uma lista vazia inclui todos os registros. Os [presets de relatórios](/pt/api-reference/entities/report-presets) congelam as condições completas.
Os campos com catálogo alteram o controle conforme o operador: `equals` recebe um valor e `in` recebe um array. Por exemplo, país aceita `{ "operator": "equals", "value": "AR" }` ou `{ "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:** regra (`in`), severidade, status, tipo afetado, score, falso positivo, data e tipo do alerta.
* **Entidades:** tipo, status, Tax ID exato ou em lista personalizada, país, ID externo, busca, idade, score, status KYC, regra com hit, datas de criação/enriquecimento, PEP, sanções, mídia adversa, MEI, processos legais —incluindo criminais—, sócios, relações, atividade eleitoral, atividades econômicas e investigações ativas.
* **Transações:** tipo, status, meio de pagamento, score, valor, moeda, data, regra com hit, Tax ID relacionado, IDs externos de origem/destino, autotransação, ausência de avaliação, hit de regra shadow, busca, marcada e presença de alertas.
* **Investigações:** status, prioridade, tipologia, score, tipo de alvo, datas de criação/atualização e busca em título/descrição.
Os operadores disponíveis dependem do campo: `equals`, `contains`, `in`, `gte`, `lte`, `between`, `before`, `after`, `is_true`, `is_false`, `in_custom_list` e `not_in_custom_list`. O catálogo retornado por `GET /report-templates` inclui `filterFields` com os operadores e opções válidos de cada template.