Corvex API

Esta página é o manual operacional para uma pessoa ou uma LLM montar automações Corvex. O entregável pode ir para o painel ou para a API v1:

POST /api/v1/automations/validate
POST /api/v1/automations
PATCH /api/v1/automations/:automationId

Automações criadas pela API nascem active: false. Para inserir ou reordenar uma etapa sem reenviar o JSON inteiro: POST /api/v1/automations/:id/steps e POST /api/v1/automations/:id/steps/:stepId/move. PATCH com steps completo continua válido.

Duas etapas mentais

INTENÇÃO DO USUÁRIO
        ↓
PLANO (trigger, delays, conditions, canais, textos)
        ↓
CONTRATO CORVEX (JSON válido)

Não pule o plano. Não invente recurso no contrato. Exemplo:

Usuário: "Quando gerar um PIX, espere 30 minutos e, se ainda não estiver pago,
envie um e-mail. Depois de 24 horas, se continuar pendente, envie outro."

Plano:
  trigger          pix.generated
  delay            30 minutos
  condition        payment_status = pending
  action           send_email  (template de lembrete PIX)
  delay            1440 minutos
  condition        payment_status = pending
  action           send_email  (segundo lembrete)

Depois disso, monte o JSON com steps e templates.

Modelo mental

Automation
  name
  trigger_event          ← o que inicia (não é um step)
  active
  steps[]                ← 1 a 50
       ├── delay         espera N minutos
       ├── condition     ramifica
       │     ├── if_true / branch
       │     └── if_false / outras branches
       ├── action        envia mensagem (o template vive em data)
       ├── retry         repete steps internos
       ├── loop          itera steps internos
       └── end           encerra o ramo

O trigger não é uma etapa. Ele fica em trigger_event.
O template não é uma etapa. Ele é o conteúdo da action (data.subject, data.body, data.message, …). O fluxo termina quando não há próximo step, quando um end corre, ou quando a condition não tem ramo verdadeiro e não há if_false.

Capability manifesto

Capacidade	Valores reais
Triggers	14 — ver Triggers
Steps	`delay` `condition` `action` `retry` `loop` `end`
Actions que enviam	`send_email` `send_sms` `send_whatsapp`
Actions extras	`webhook` (POST HTTPS) `create_coupon` (cria cupom)
Operators	`=` `!=` `in` `not-in` `empty` `not-empty` `>` `<` `>=` `<=`
Compound	`AND` `OR`
Campos de condition	`amount` `customer.` `lead.` `tracking.status\|code\|url\|carrier` `payment_status` `payment_method`
Canais	e-mail, SMS, WhatsApp
Delay	1–10080 minutos (inteiro)
SMS	≤ 160 caracteres no texto salvo
Steps por fluxo	1–50
Nome	3–100 caracteres
Metatags	catálogo por gatilho — Metatags
Lifecycle	só `active` true/false

Não existem: equals, contains, order.shipped, order.created. Edição incremental: POST .../steps e POST .../steps/:stepId/move, ou PATCH do documento. Templates: POST /api/v1/automation/templates + data.template_id.

Trigger → contexto → mensagem

trigger_event
    ↓
contextos com metatags naquele gatilho
    ↓
escolher canal (email / sms / whatsapp)
    ↓
escrever template só com {{chaves}} daquele gatilho

Trigger	O que pode ir na mensagem (exemplos)
`pix.generated`	`{{customer.name}}` `{{order.pix_code}}` `{{order.url_pix_gerado}}` `{{order.total}}`
`payment.confirmed`	`{{customer.name}}` `{{order.total}}` — sem PIX
`cart.abandoned`	`{{lead.name}}` `{{cart.url_checkout}}` — sem `{{order.pix_code}}`
`tracking_code_updated`	`{{tracking.code}}` `{{tracking.url}}`
`lead.created`	`{{lead.name}}` `{{lead.email}}` — dados ainda podem estar vazios
`email.received`	`{{inbound.subject}}` `{{inbound.from}}`
`subscription.*`	`{{subscription.portalUrl}}` `{{subscription.total}}`
`boleto.generated`	`{{customer.name}}` `{{order.boleto_barcode}}` `{{order.boleto_digitable_line}}` `{{order.url_boleto_gerado}}` — sem PIX
`payment.failed`	`{{customer.name}}` `{{order.total}}` — sem PIX e sem chaves de boleto

Confirme sempre em GET /api/v1/automation/metatags?triggerType=....

Como a LLM deve trabalhar

Entender a intenção

O que dispara? Espera? Condição? Qual canal? Qual tom?

Escolher o trigger

Só um dos 14. “Pedido enviado” → tracking_code_updated. “PIX gerado” → pix.generated.

Desenhar o plano

Lista linear: delay, condition, action. Se o recurso não existir, pare e explique.

Escrever as mensagens

Ver Templates. Só metatags daquele gatilho.

Montar o JSON

name, trigger_event, active, steps. IDs estáveis se for edição.

Validar

Checklist abaixo. Depois mostre o preview em português.

Preview (antes de salvar)

Sempre explique o fluxo assim:

Quando: PIX for gerado
Depois de: 30 minutos
Se: o pagamento continuar pendente (payment_status = pending)
Então: enviar e-mail "Seu PIX ainda está disponível"
Depois de: 24 horas
Se: o pagamento continuar pendente
Então: enviar e-mail "Último lembrete do PIX"

Peça confirmação do remetente (remetente_nome / remetente_email) — não invente o e-mail da loja.

Operações de edição (no JSON)

Editar = PATCH no documento ou POST /api/v1/automations/:id/steps e POST /api/v1/automations/:id/steps/:stepId/move. Preserve id / nextId / parentId das etapas que você não pediu para mudar.

Pedido	O que fazer
Criar automação	JSON novo. Pode omitir `id` dos steps.
Trocar delay 30 → 60	Altere só `minutes` daquele step. Preserve `id` e `nextId`.
Inserir delay entre A e B	Novo step; ajuste `nextId` (formato flat) ou a posição no array / `if_true`.
Remover o segundo SMS	Apague esse step. Religue `nextId` / `parentId` dos vizinhos.
Reordenar	Mude `nextId` ou a ordem no array. Não apague actions não pedidas.
Só o texto	Altere `data.message` / `data.subject` / `data.body`.
Duplicar fluxo	Copie o JSON, mude `name`, remova `id` da automação.
Criar ramificação	Step `condition` + `if_true` / `if_false` ou `branches` + `parentId`.

Invariantes: não recrie o fluxo inteiro para uma troca pontual; não mude id de steps existentes; não altere trigger, nome ou outras actions sem pedido; máximo 50 steps; delay continua 1–10080.

Exemplo: só o delay

Antes: "minutes": 30. Pedido: “troque 30 minutos por 1 hora”.

{ "type": "delay", "id": "wait-1", "minutes": 60, "nextId": "send-1" }

O resto do JSON permanece igual.

Validação antes de entregar

Trigger existe nos 14?
Cada step.type é um dos 6?
Cada action.name é um dos 5? webhook tem url HTTPS? create_coupon tem coupon_name + discountType + amount?
Operator é = (nunca equals) / in / empty / …?
Campo da condition está na lista curta?
payment_status usa paid pending cancelled?
Delay em minutos inteiros (24 h = 1440, não 24 hours)?
E-mail tem remetente, assunto ≥ 3, body ou html?
SMS ≤ 160?
WhatsApp tem message (texto) ou o campo obrigatório do tipo?
Cada {{chave}} existe naquele trigger_event?
Tronco sem parentId; ramos com parentId = branches[].id?
1–50 steps, nome 3–100?
Edição: ids antigos preservados?

Se algum item falhar, não entregue JSON inválido. Explique a limitação.

Biblioteca intenção → automação

Recuperar PIX

Intent: “Avise quem gerar PIX e não pagar.”

Peça	Valor
Trigger	`pix.generated`
Condition	`payment_status` `=` `pending`
Actions	`send_email` (e opcionalmente `send_sms` / `send_whatsapp`)
Metatags	`{{customer.name}}` `{{order.pix_code}}` `{{order.url_pix_gerado}}`

JSON (formato aninhado, válido):

{
  "name": "Lembrete PIX pendente",
  "trigger_event": "pix.generated",
  "active": true,
  "steps": [
    {
      "id": "wait-30",
      "type": "delay",
      "minutes": 30,
      "nextId": "still-pending"
    },
    {
      "id": "still-pending",
      "type": "condition",
      "field": "payment_status",
      "operator": "=",
      "value": "pending",
      "if_true": [
        {
          "id": "email-1",
          "type": "action",
          "name": "send_email",
          "data": {
            "remetente_nome": "Nome da loja",
            "remetente_email": "loja@example.com",
            "subject": "Seu PIX ainda está disponível",
            "body": "Olá, {{customer.name}}!\n\nSeu pedido ainda aguarda pagamento.\n\nCódigo PIX:\n{{order.pix_code}}\n\nPagar agora:\n{{order.url_pix_gerado}}"
          },
          "nextId": "wait-24h"
        },
        {
          "id": "wait-24h",
          "type": "delay",
          "minutes": 1440,
          "nextId": "still-pending-2"
        },
        {
          "id": "still-pending-2",
          "type": "condition",
          "field": "payment_status",
          "operator": "=",
          "value": "pending",
          "if_true": [
            {
              "id": "email-2",
              "type": "action",
              "name": "send_email",
              "data": {
                "remetente_nome": "Nome da loja",
                "remetente_email": "loja@example.com",
                "subject": "Último lembrete: PIX em aberto",
                "body": "Olá, {{customer.name}}, o PIX do pedido ainda não foi pago:\n{{order.url_pix_gerado}}"
              }
            }
          ],
          "if_false": [{ "type": "end" }]
        }
      ],
      "if_false": [{ "type": "end" }]
    }
  ]
}

Substitua remetente pelos dados reais da loja.

Recuperar carrinho

Intent: “Uma hora depois de abandonar o checkout, envie um lembrete.” Não existe campo de condition has_purchased. O gatilho cart.abandoned já significa checkout abandonado. Delay + envio é o fluxo suportado. Opcional: só enviar se houver telefone (lead.phone not-empty).

{
  "name": "Recuperação de carrinho",
  "trigger_event": "cart.abandoned",
  "active": true,
  "steps": [
    { "id": "wait-1h", "type": "delay", "minutes": 60, "nextId": "mail-1" },
    {
      "id": "mail-1",
      "type": "action",
      "name": "send_email",
      "data": {
        "remetente_nome": "Nome da loja",
        "remetente_email": "loja@example.com",
        "subject": "Você esqueceu itens no checkout",
        "body": "Olá, {{lead.name}}!\n\nSeu checkout ainda está aberto:\n{{cart.url_checkout}}"
      }
    }
  ]
}

Não use {{order.pix_code}} aqui.

Pós-compra

Intent: “Quando o pagamento for confirmado, envie instruções.” Trigger payment.confirmed. Sem delay. Sem PIX.

Olá, {{customer.name}}! Recebemos {{order.total}}. Obrigado pela compra.

Rastreio

Intent: “Quando o código de rastreio estiver disponível, envie ao cliente.” Trigger tracking_code_updated. WhatsApp ou e-mail com {{tracking.code}} e {{tracking.url}}.

O que recusar

Pedido	Motivo
“Quando o pedido for enviado” como trigger próprio	Use `tracking_code_updated`
Condition `contains` no e-mail	Não existe; use `=` / `in` / `empty`
Webhook HTTP na automação	`webhook` com `data.url` HTTPS
Cupom automático	`create_coupon` com `coupon_name`, `discountType`, `amount`
Delay em horas no JSON	Campo é `minutes`
Metatag `{{pix.payment_url}}`	Não existe; em PIX use `{{order.url_pix_gerado}}`

Matrizes rápidas

Canal × template

Canal	Action	Obrigatório
E-mail	`send_email`	`remetente_nome`, `remetente_email`, `subject` ≥ 3, `body` ou `html`
SMS	`send_sms`	`message` ≤ 160
WhatsApp texto	`send_whatsapp`	`data.type` `text` ou `whatsapp`, `message`

Campo × operator

Tipo de dado	Operators úteis
Texto (`customer.email`, `lead.phone`)	`=` `!=` `empty` `not-empty` `in` `not-in`
Número (`amount`)	`=` `!=` `>` `<` `>=` `<=` (`0` conta como vazio)
Status (`payment_status`)	`=` `!=` `in` com `paid` / `pending` / `cancelled`
Qualquer	`empty` `not-empty`

Não há contains, starts_with, before, after.

Trigger × action

Qualquer action pode ser salva em qualquer trigger. O envio falha se faltar e-mail (e-mail) ou telefone (SMS/WhatsApp). A restrição real é metatag × trigger, não action × trigger. Próximo: Templates de comunicação e regras para IA.

Visão geral

Fundamentos

Checkout externo

Catálogo

Pedidos e entrega

Clientes

Marketing

Webhooks

Automações

Criar e editar automações

Duas etapas mentais

Modelo mental

Capability manifesto

Trigger → contexto → mensagem

Como a LLM deve trabalhar

Preview (antes de salvar)

Operações de edição (no JSON)

Exemplo: só o delay

Validação antes de entregar

Biblioteca intenção → automação

Recuperar PIX

Recuperar carrinho

Pós-compra

Rastreio

O que recusar

Matrizes rápidas

Canal × template

Campo × operator

Trigger × action

​Duas etapas mentais

​Modelo mental

​Capability manifesto

​Trigger → contexto → mensagem

​Como a LLM deve trabalhar

​Preview (antes de salvar)

​Operações de edição (no JSON)

​Exemplo: só o delay

​Validação antes de entregar

​Biblioteca intenção → automação

​Recuperar PIX

​Recuperar carrinho

​Pós-compra

​Rastreio

​O que recusar

​Matrizes rápidas

​Canal × template

​Campo × operator

​Trigger × action

Duas etapas mentais

Modelo mental

Capability manifesto

Trigger → contexto → mensagem

Como a LLM deve trabalhar

Preview (antes de salvar)

Operações de edição (no JSON)

Exemplo: só o delay

Validação antes de entregar

Biblioteca intenção → automação

Recuperar PIX

Recuperar carrinho

Pós-compra

Rastreio

O que recusar

Matrizes rápidas

Canal × template

Campo × operator

Trigger × action