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

# Eventos recomendados

> Nomes e propriedades sugeridos para os eventos mais comuns de e-commerce.

A API aceita **qualquer nome** de evento que siga o formato (letras minúsculas,
números e sublinhados). Este catálogo é uma convenção, não uma regra: nada
aqui é validado, e você pode enviar eventos e propriedades que não estão na
lista.

Vale a pena seguir o catálogo por dois motivos:

* Os mesmos nomes e propriedades em todos os eventos deixam flows e mensagens
  previsíveis: `{{event.order_number}}` funciona igual em `order_shipped` e em
  `order_delivered`.
* Um evento com nome do catálogo já nasce com a **natureza** indicada na
  tabela (`utility` ou `marketing`), devolvida em `GET /v1/event-types`.
* Alguns eventos têm um flow pronto nas receitas da Bevits: **Pedido enviado**
  para `order_shipped` (lê `tracking_code`, `tracking_url` e `carrier`) e **Pix
  gerado** para `pix_generated` (lê `pix_code` e `order_url`, lembra o cliente
  15 minutos depois e para quando chega `payment_confirmed` com o mesmo
  `order_number`) e **Pontos
  expirando** para `points_expiring` (lê `points`).

Veja como enviar em [Eventos personalizados](https://docs.bevits.com/pt-BR/api-reference/custom-events.md).

## Propriedades comuns

Use estas propriedades, com o mesmo nome, em todos os eventos em que fizerem
sentido:

| Propriedade | Conteúdo |
| - | - |
| `order_number` | Número do pedido, como o cliente o vê. |
| `order_url` | Link para o pedido. |
| `total_in_cents` | Valor total em centavos. |
| `currency` | Moeda, como `BRL`. |
| `items[]` | Itens do pedido. Cada item: `sku`, `name`, `quantity`, `price_in_cents`, `image_url`, `url`. |

Nos eventos sobre um produto, `product` é um objeto com `sku`, `name`,
`price_in_cents`, `image_url`, `url` e `category`.

```json theme={null}
{
  "name": "order_shipped",
  "customer": { "external_id": "u_8842", "email": "ana@exemplo.com.br" },
  "properties": {
    "order_number": "10293",
    "order_url": "https://loja.com/pedidos/10293",
    "total_in_cents": 15990,
    "currency": "BRL",
    "items": [
      {
        "sku": "CAM-01",
        "name": "Camiseta",
        "quantity": 2,
        "price_in_cents": 7995,
        "image_url": "https://cdn.loja.com/cam-01.png",
        "url": "https://loja.com/produtos/camiseta"
      }
    ],
    "tracking_code": "BR123",
    "tracking_url": "https://rastreio.exemplo.com.br/BR123",
    "carrier": "Correios",
    "estimated_delivery_date": "2026-11-22"
  },
  "external_id": "ship_10293"
}
```

## Catálogo

| Grupo | Evento | Propriedades recomendadas, além das comuns | Natureza |
| - | - | - | - |
| Pedido | `order_placed` | | utilidade |
| | `order_cancelled` | `reason` | utilidade |
| Pagamento | `pix_generated` | `pix_code`, `expires_at` | utilidade |
| | `pix_expired` | | utilidade |
| | `boleto_generated` | `boleto_url`, `barcode`, `due_date` | utilidade |
| | `payment_confirmed` | `payment_method` | utilidade |
| | `payment_failed` | `payment_method`, `reason` | utilidade |
| | `refund_issued` | `amount_in_cents`, `reason` | utilidade |
| Logística | `order_invoiced` | `invoice_url`, `invoice_number` | utilidade |
| | `order_shipped` | `tracking_code`, `tracking_url`, `carrier`, `estimated_delivery_date` | utilidade |
| | `out_for_delivery` | `tracking_code`, `tracking_url` | utilidade |
| | `order_delivered` | `delivered_at` | utilidade |
| | `delivery_failed` | `reason`, `tracking_url` | utilidade |
| | `ready_for_pickup` | `pickup_location`, `pickup_deadline` | utilidade |
| Intenção | `product_viewed` | `product` | marketing |
| | `search_performed` | `query`, `results_count` | marketing |
| | `product_added_to_cart` | `product`, `cart_url` | marketing |
| | `checkout_started` | `checkout_url` | marketing |
| | `wishlist_added` | `product` | marketing |
| Estoque e preço | `back_in_stock` | `product` | marketing |
| | `price_dropped` | `product`, `previous_price_in_cents` | marketing |
| Pós-venda | `review_requested` | `review_url` | utilidade |
| | `review_submitted` | `rating`, `comment`, `product` | |
| | `return_requested` | `reason`, `return_url` | utilidade |
| | `exchange_requested` | `reason` | utilidade |
| | `nps_answered` | `score`, `comment` | |
| | `support_ticket_resolved` | `ticket_id`, `survey_url` | utilidade |
| Fidelidade | `points_earned` | `points`, `balance` | marketing |
| | `points_expiring` | `points`, `expires_at` | marketing |
| | `tier_changed` | `previous_tier`, `tier` | marketing |
| | `cashback_available` | `amount_in_cents`, `expires_at` | marketing |
| | `cashback_expiring` | `amount_in_cents`, `expires_at` | marketing |
| | `coupon_issued` | `code`, `discount`, `expires_at` | marketing |
| Assinatura | `subscription_created` | `plan`, `next_charge_date` | utilidade |
| | `renewal_upcoming` | `plan`, `next_charge_date`, `amount_in_cents` | utilidade |
| | `subscription_renewed` | `plan`, `next_charge_date` | utilidade |
| | `subscription_payment_failed` | `plan`, `retry_date`, `update_payment_url` | utilidade |
| | `subscription_cancelled` | `plan`, `reason` | utilidade |
| Conta e captação | `account_created` | `source` | marketing |
| | `lead_captured` | `source`, `form_name` | marketing |
| Loja física | `store_purchase` | `store_name` | utilidade |
| | `appointment_scheduled` | `scheduled_for`, `location` | utilidade |
| | `appointment_reminder` | `scheduled_for`, `location` | utilidade |

Na API, a natureza aparece como `utility` (utilidade) ou `marketing`. Os
eventos sem natureza (`review_submitted`, `nps_answered`) normalmente não geram
mensagem: servem para registrar a resposta do cliente.

Datas e horários vão como texto em ISO 8601 (`2026-11-22` ou
`2026-11-22T14:00:00-03:00`). Valores monetários vão em centavos.

## Três regras

### 1. Natureza do evento

**Utilidade** é um evento sobre algo que o cliente já fez: um pedido, um
pagamento, uma entrega. **Marketing** é um evento usado para vender, como
`back_in_stock` ou `coupon_issued`, e a mensagem que ele gera exige o
consentimento do cliente.

A natureza é uma propriedade do tipo de evento. Os nomes do catálogo nascem com
a natureza da tabela; um nome fora do catálogo nasce sem natureza e segue a
regra de marketing. A natureza pode ser alterada em Configurações → Eventos.
Um evento de utilidade alcança quem nunca aceitou marketing, mas não quem pediu
para sair; no WhatsApp oficial, o template também precisa ser de utilidade.
Detalhes em [Quem recebe as mensagens do flow](https://docs.bevits.com/pt-BR/api-reference/custom-events.md#quem-recebe-as-mensagens-do-flow).

### 2. Eventos de produto são enviados por cliente

`back_in_stock` e `price_dropped` acontecem com um produto, mas a API liga cada
evento a um cliente. Envie um evento por cliente interessado, usando o
[envio em lote](https://docs.bevits.com/pt-BR/api-reference/custom-events.md#envio-em-lote).

### 3. Fora do catálogo de propósito

Redefinição de senha e códigos de verificação não estão no catálogo. São
mensagens críticas em tempo e não pertencem a um flow de marketing.

## Se a sua loja não tem integração nativa

As integrações nativas da Bevits já geram os eventos de pedido criado, pago,
enviado e cancelado, de carrinho abandonado e de novo cliente. Se você envia
esses fatos pela API porque não usa uma integração nativa, use os nomes do
catálogo: `order_placed`, `payment_confirmed`, `order_shipped`,
`order_cancelled`, `checkout_started` e `account_created`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.