> ## 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.

# Presets de relatórios

> Salve configurações editáveis de modelos Gu1 por organização para download em um clique e automações send_report.

## Overview

Um **preset de relatório** guarda uma configuração de [modelo de relatório](/pt/api-reference/entities/report-templates) Gu1 para sua organização (`name` + `templateCode` + `params`). Após criar, você pode **editar** `name`, `description` e `params`; o `templateCode` fica fixo. Também pode listar, obter, executar ou excluir.

| Método   | Path                       | Uso                                                |
| -------- | -------------------------- | -------------------------------------------------- |
| `GET`    | `/report-presets`          | Listar presets da org                              |
| `GET`    | `/report-presets/{id}`     | Detalhe                                            |
| `POST`   | `/report-presets`          | Criar (nome + modelo + params)                     |
| `PATCH`  | `/report-presets/{id}`     | Atualizar nome, descrição e/ou params              |
| `DELETE` | `/report-presets/{id}`     | Exclusão definitiva                                |
| `POST`   | `/report-presets/{id}/run` | Executar com params salvos (`download` ou `email`) |

Limite: **50** presets por organização. Nome único por org (sem distinguir maiúsculas).

**Executar** sempre enfileira um job async para object storage (**202** + `jobId`). Baixe depois em Relatórios **Downloads** / [Jobs de exportação de relatórios](/pt/api-reference/entities/report-export-jobs). Os `params` podem incluir `emailLocale`, `format` (`csv` / `pdf` / `xlsx` conforme o modelo) e outros campos (`lookbackDays`, `ruleIds`, `filters`).

## Autenticação e tenant

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY` — ver [Autenticação](/pt/api-reference/authentication).
</ParamField>

<ParamField header="X-Organization-ID" type="string" required>
  UUID da organização produção ou sandbox — ver [Ambientes](/pt/api-reference/environments).
</ParamField>

## Permissões

| Endpoint                               | Permissão granular |
| -------------------------------------- | ------------------ |
| `GET` list / get                       | `reports:read`     |
| `POST` create / run, `PATCH`, `DELETE` | `reports:export`   |

## Criar

```
POST http://api.gu1.ai/report-presets
```

<ParamField body="name" type="string" required>
  Nome visível (1–120 caracteres). Deve ser único na organização (sem distinguir maiúsculas).
</ParamField>

<ParamField body="description" type="string">
  Nota opcional para sua equipe (máx. 500 caracteres).
</ParamField>

<ParamField body="templateCode" type="string" required>
  Código do catálogo Gu1 (por exemplo `alerts_by_rules`).
</ParamField>

<ParamField body="params" type="object">
  Params do modelo (`lookbackDays`, `ruleIds`, `emailLocale`, `format`, `filters`, etc.). Validados contra o modelo.
</ParamField>

Ao criar, a Gu1 guarda um **`paramsSummary`** legível (nomes de regras, janela) para a UI. Ao **executar**, usam-se os UUIDs vivos de `params`; regras inexistentes são omitidas pelo runner.

### Exemplo

```json theme={null}
{
  "name": "Total contas CBU/CVU",
  "description": "Revisão operacional mensal",
  "templateCode": "alerts_by_rules",
  "params": {
    "lookbackDays": 30,
    "ruleIds": ["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"]
  }
}
```

### Resposta 201

```json theme={null}
{
  "success": true,
  "preset": {
    "id": "…",
    "organizationId": "…",
    "name": "Total contas CBU/CVU",
    "templateCode": "alerts_by_rules",
    "params": { "lookbackDays": 30, "ruleIds": ["…"] },
    "paramsSummary": {
      "lookbackDays": 30,
      "ruleLabels": ["Total de contas"],
      "lines": ["Últimos 30 dias", "Regras: Total de contas"]
    },
    "createdAt": "2026-08-06T12:00:00.000Z"
  }
}
```

### Erros

| Código                      | Status | Significado                   |
| --------------------------- | ------ | ----------------------------- |
| `REPORT_TEMPLATE_NOT_FOUND` | 400    | `templateCode` desconhecido   |
| `REPORT_PRESET_NAME_EXISTS` | 409    | Nome duplicado na org         |
| `REPORT_PRESET_LIMIT`       | 400    | Limite de 50 atingido         |
| `REPORT_PRESET_NOT_FOUND`   | 404    | Id desconhecido para esta org |

## Atualizar

```
PATCH http://api.gu1.ai/report-presets/{id}
```

Pelo menos um de `name`, `description` ou `params` é obrigatório. Não é possível alterar `templateCode`. Os `params` são revalidados contra o modelo existente.

<ParamField body="name" type="string">
  Novo nome (1–120). Deve continuar único na org.
</ParamField>

<ParamField body="description" type="string">
  Nova descrição (máx. 500) ou `null` para limpar.
</ParamField>

<ParamField body="params" type="object">
  Params completos a persistir (substituição, não merge parcial de chaves omitidas).
</ParamField>

## Executar

```
POST http://api.gu1.ai/report-presets/{id}/run
```

Carrega o preset e chama o mesmo runner que `POST /report-templates/{code}/run` com os `params` salvos.

<ParamField body="delivery" type="string">
  `download` (default) ou `email`.
</ParamField>

<ParamField body="recipientEmails" type="string[]">
  Obrigatório quando `delivery` é `email`.
</ParamField>

<ParamField body="format" type="string">
  Opcional: `csv`, `xlsx` ou `pdf` (deve ser suportado pelo modelo). Se omitido, usa `params.format` ou o default do modelo.
</ParamField>

Resposta de sucesso: **202** (mesmo shape que run de modelos, mais `presetId`). Sempre enfileira um job em segundo plano. Consulte ou baixe via [Jobs de exportação de relatórios](/pt/api-reference/entities/report-export-jobs).

## Automações

Em Relatórios, **Agendar** abre o builder com `reportPresetId` (canônico). Use a ação **`send_report` / Gerar relatório** com `reportPresetId` e opcionalmente `sendEmail` + `recipientEmails`; o legado `reportTemplateCode` + `params` continua funcionando.