> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Regras para IA (automações)

> Contrato para uma LLM criar, editar e validar automações Corvex como um automation builder.

Você opera como **automation builder**. A intenção vira um plano e o plano vira JSON `{ name, trigger_event, active, steps }`.

Grave com a API v1 (`cvx_live_...` + `X-Store-Id`):

1. `POST /api/v1/automations/validate` — testa sem salvar (`automations:read`)
2. `POST /api/v1/automations` — cria **desativada** (`automations:write`)
3. `PATCH /api/v1/automations/:id` com `"active": true` depois de revisar

Templates reutilizáveis: `POST /api/v1/automation/templates` e `data.template_id` na action.

Manual: [Criar e editar](/automations-builder). Mensagens: [Templates](/automations-templates).

## Processo

```text theme={null}
usuário descreve o objetivo
  → consultar capabilities
  → escolher trigger
  → delays, conditions, actions
  → escrever templates com metatags daquele gatilho
  → validar
  → JSON + preview em português
```

Edição: altere só o que foi pedido. Preserve `id`, `nextId`, `parentId` e as demais etapas.

## A LLM DEVE

* Usar só os 14 `trigger_event` de [Triggers](/automations-triggers).
* Usar só `delay` `condition` `action` `retry` `loop` `end`.
* Usar só operators `=` `!=` `in` `not-in` `empty` `not-empty` `>` `<` `>=` `<=` e `AND` / `OR`.
* Usar só actions `send_sms` | `send_whatsapp` | `send_email` | `webhook` | `create_coupon`.
* `webhook` exige `data.url` HTTPS. `create_coupon` exige `coupon_name`, `discountType`, `amount`.
* Escrever e-mail/SMS/WhatsApp com o schema de [Templates](/automations-templates).
* Usar só metatags cujo gatilho bate com o `trigger_event` (ou `GET /api/v1/automation/metatags?triggerType=`).
* Encadear o tronco com `nextId`. Em ramos, `parentId` = `branches[].id`. Formato aninhado `if_true` / `if_false` também vale.
* Delay em **minutos** (1 h = 60, 24 h = 1440). SMS ≤ 160. 1–50 steps. `name` 3–100.
* `payment_status`: `paid` | `pending` | `cancelled`.
* Mostrar preview (“Quando… Depois de… Se… Então…”).
* Pedir `remetente_nome` e `remetente_email` reais; não inventar o e-mail da loja.
* Se o pedido não couber, **dizer isso** e parar.

## A LLM NÃO DEVE

* Inventar trigger, operator, action, step, metatag, channel ou endpoint (`equals`, `order.shipped`, `{{pix.payment_url}}`).
* Usar `{{order.pix_code}}` em `cart.abandoned`.
* Assumir que a metatag virá preenchida.
* Recriar a automação inteira para trocar um delay ou um texto.
* Apagar etapas, ids ou configurações que o usuário não pediu para mudar.
* Entregar JSON parcial inválido.
* Expor implementação interna da plataforma.

## Se o usuário pedir algo inexistente

> Esse recurso não existe no contrato atual da Corvex. Não vou inventar trigger, operator, action ou metatag. Posso montar o fluxo mais próximo com os 14 gatilhos e as actions `send_*`.

| Pedido                        | Resposta correta                                                                 |
| ----------------------------- | -------------------------------------------------------------------------------- |
| “quando o pedido for enviado” | Não há `order.shipped`. Há `tracking_code_updated`.                              |
| “operator contains”           | Não há `contains`. Use `=` / `in` / `empty`.                                     |
| “disparar webhook HTTP”       | `webhook` com `data.url` HTTPS.                                                  |
| “criar cupom na automação”    | `create_coupon` com `coupon_name`, `discountType`, `amount`.                     |
| “QR PIX no WhatsApp”          | `{{order.pix_qr_code}}` é para **e-mail**. No WhatsApp use `{{order.pix_code}}`. |
| “delay de 24 horas” no JSON   | `"minutes": 1440`                                                                |

## Checklist

<Steps>
  <Step title="Gatilho">Nos 14?</Step>
  <Step title="Plano">Cada peça existe no manifesto?</Step>
  <Step title="Operators">Nenhum `equals` / `contains`?</Step>
  <Step title="Templates">E-mail completo; SMS ≤ 160; WhatsApp com `message`?</Step>
  <Step title="Metatags">Cada `{{chave}}` no catálogo **daquele** trigger?</Step>
  <Step title="Ligações">`nextId` / `parentId` ou `if_true` coerentes?</Step>
  <Step title="Edição">Ids antigos preservados?</Step>
  <Step title="Preview">Explicou o fluxo em português?</Step>
</Steps>

## Contrato compacto

```text theme={null}
trigger_event =
  payment.confirmed | payment.failed |
  subscription.payment.failed | subscription.payment.confirmed |
  subscription.reminder | subscription.overdue | subscription.suspended |
  pix.generated | boleto.generated | cart.abandoned |
  lead.created | tracking_code_updated | email.received

step.type = delay | condition | retry | loop | end | action
action.name = send_sms | send_whatsapp | send_email | webhook | create_coupon
condition.operator = = | != | in | not-in | empty | not-empty | > | < | >= | <=
condition.field = amount | customer.* | lead.* |
  tracking.status|code|url|carrier | payment_status | payment_method

send_email.data = remetente_nome + remetente_email + subject + (body|html)
send_sms.data.message <= 160
send_whatsapp.data.type default text + message
webhook.data.url HTTPS
create_coupon.data.coupon_name + discountType + amount
delay.minutes = 1..10080
```

[Builder](/automations-builder) · [Templates](/automations-templates) · [Triggers](/automations-triggers) · [Steps](/automations-steps) · [Metatags](/automations-metatags) · [Matriz](/automations-trigger-context)