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

> Envie para a Bevits o que acontece no seu sistema e use esses eventos para iniciar flows.

Um evento é um fato: esta pessoa fez isto, neste momento, com estes detalhes.
Envie um `POST` e a Bevits grava o evento, liga-o a um cliente e inicia os flows
que escutam esse nome.

```bash theme={null}
curl https://api.bevits.com/v1/events \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "customer": { "email": "ana@exemplo.com.br" },
    "properties": { "tracking_code": "BR123", "carrier": "Correios" }
  }'
```

* **URL:** `POST https://api.bevits.com/v1/events`
* **Formato:** `name` (o que aconteceu), `customer` (com quem) e `properties`
  (detalhes). Opcionais: `occurred_at`, `external_id` e `backfill`.
* **Como liga ao cliente:** envie os identificadores que tiver (`external_id`,
  `tax_id`, `email`, `phone`). O primeiro que casar, nessa ordem, decide. Se
  nenhum casar, o cliente é criado. A resposta diz qual cliente foi e por qual
  identificador.

Nada é cadastrado antes: nem o evento, nem as propriedades, nem o cliente.

> [!NOTE]
>
> A chave precisa do escopo `write` ou `events:write`. Veja
> [Chave só de envio](#chave-só-de-envio).

## Envio completo

```json theme={null}
{
  "name": "order_shipped",
  "customer": {
    "external_id": "u_8842",
    "email": "ana@exemplo.com.br",
    "phone": "+5511988887777",
    "tax_id": "123.456.789-09",
    "name": "Ana Souza",
    "attributes": { "plano": "premium" }
  },
  "properties": {
    "order_number": "10293",
    "tracking": { "code": "BR123", "carrier": "Correios" },
    "items": [{ "sku": "CAM-01", "name": "Camiseta", "quantity": 2 }]
  },
  "occurred_at": "2026-11-18T14:03:00-03:00",
  "external_id": "ship_10293",
  "backfill": false
}
```

| Campo | Obrigatório | Regra |
| - | - | - |
| `name` | sim | Letras minúsculas, números e sublinhados, começando por letra (`^[a-z][a-z0-9_]*$`). Até 64 caracteres. |
| `customer` | sim | Ao menos um identificador: `id`, `external_id`, `tax_id`, `email` ou `phone`. |
| `properties` | não | Objeto JSON livre. Veja [Propriedades e limites](#propriedades-e-limites). |
| `occurred_at` | não | ISO 8601 com offset. Padrão: o momento do recebimento. |
| `external_id` | não | ID do fato no seu sistema, até 255 caracteres. Veja [Repetir com segurança](#repetir-com-segurança). |
| `backfill` | não | `true` grava sem disparar flows. Padrão `false`. |

Campos desconhecidos são recusados com `unknown_field`, em vez de ignorados.
Um `customerId` no lugar de `customer.id` falha na primeira chamada.

O nome é estrito para que `Order Shipped`, `order shipped` e `order_shipped`
não virem três eventos diferentes. Um nome inválido já falha na primeira
chamada e sugere o correto:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "invalid_event_name",
    "message": "Event names use lowercase letters, digits and underscores, start with a letter and have at most 64 characters. Did you mean \"order_shipped\"?",
    "param": "name",
    "suggestion": "order_shipped",
    "request_id": "req_07f6cdc3c20249d6afcd90b4"
  }
}
```

```bash cURL theme={null}
curl https://api.bevits.com/v1/events \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "customer": {
      "external_id": "u_8842",
      "email": "ana@exemplo.com.br",
      "phone": "+5511988887777"
    },
    "properties": {
      "order_number": "10293",
      "tracking": { "code": "BR123", "carrier": "Correios" }
    },
    "occurred_at": "2026-11-18T14:03:00-03:00",
    "external_id": "ship_10293"
  }'
```

```javascript Node.js theme={null}
const response = await fetch("https://api.bevits.com/v1/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BEVITS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "order_shipped",
    customer: {
      external_id: "u_8842",
      email: "ana@exemplo.com.br",
      phone: "+5511988887777",
    },
    properties: {
      order_number: "10293",
      tracking: { code: "BR123", carrier: "Correios" },
    },
    occurred_at: "2026-11-18T14:03:00-03:00",
    external_id: "ship_10293",
  }),
});

const body = await response.json();

if (!response.ok) {
  // error.code diz o motivo, error.param diz o campo.
  throw new Error(`${body.error.code ?? body.error.type}: ${body.error.message}`);
}

// 201: evento novo. 200: o external_id já existia (body.duplicate === true).
console.log(body.id, body.customer, body.flows);
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.bevits.com/v1/events",
    headers={"Authorization": f"Bearer {os.environ['BEVITS_API_KEY']}"},
    json={
        "name": "order_shipped",
        "customer": {
            "external_id": "u_8842",
            "email": "ana@exemplo.com.br",
            "phone": "+5511988887777",
        },
        "properties": {
            "order_number": "10293",
            "tracking": {"code": "BR123", "carrier": "Correios"},
        },
        "occurred_at": "2026-11-18T14:03:00-03:00",
        "external_id": "ship_10293",
    },
    timeout=30,
)
body = response.json()

if not response.ok:
    # error.code diz o motivo, error.param diz o campo.
    error = body["error"]
    raise RuntimeError(f"{error.get('code', error['type'])}: {error['message']}")

# 201: evento novo. 200: o external_id já existia (body["duplicate"] é True).
print(body["id"], body["customer"], body["flows"])
```

## Como o evento liga ao cliente

**A regra:** os identificadores são testados nesta ordem, `id`, `external_id`,
`tax_id`, `email`, `phone`, e o primeiro que pertencer a um cliente ativo
decide. Se nenhum pertencer, o cliente é criado com tudo que foi enviado.

| Identificador | O que é | Como é comparado |
| - | - | - |
| `id` | ID do cliente na Bevits (`cus_…`) | Exato. |
| `external_id` | ID do cliente no seu sistema | Texto exato, até 255 caracteres. |
| `tax_id` | CPF ou CNPJ | Só os dígitos. Precisa ser um documento válido. |
| `email` | E-mail | Em minúsculas, sem espaços nas pontas. |
| `phone` | Telefone | E.164 (`+5511988887777`). Sem código do país, assume o país da loja. |

`external_id` e `tax_id` são identificadores **fortes**: identificam uma
pessoa. `email` e `phone` são **fracos**: podem ser compartilhados ou trocar de
dono. Cada identificador pertence a um único cliente, e é isso que torna o
resultado previsível.

Um evento nunca funde dois clientes. Quando algo não bate, a API mantém o que
já existia e avisa em `warnings`:

| Situação | O que acontece | Aviso |
| - | - | - |
| Nenhum identificador casa | O cliente é criado com tudo que foi enviado. A resposta traz `customer.created: true`. | |
| O cliente casado ainda não tem um identificador enviado | O identificador é gravado nele. | |
| Vários clientes ativos têm o mesmo documento, e-mail ou telefone (duplicados antigos) | Casa com o mais antigo. A escolha fica fixa para as próximas chamadas. | `ambiguous_identifier` |
| O e-mail ou telefone é de um cliente que tem um `external_id` ou `tax_id` diferente do enviado | Esse identificador não é usado para casar: é outra pessoa com o mesmo contato. A busca segue para o próximo. Se nenhum casar, um cliente novo é criado. Ele guarda o contato, mas o e-mail ou telefone continua identificando o dono original. | `identifier_conflict` |
| Casou por `id`, `external_id` ou `tax_id`, e o e-mail ou telefone enviado é diferente do atual | O contato é substituído. O cliente deixa de ser encontrado pelo valor antigo. | |
| Casou por `email` ou `phone`, e o outro contato enviado é diferente do atual | O contato atual é mantido. | `identifier_mismatch` |
| O `external_id` ou `tax_id` enviado é diferente do que o cliente casado já tem | Nada é sobrescrito. | `identifier_mismatch` |
| Um dos outros identificadores enviados pertence a outro cliente | O evento fica com o cliente casado. Nada é movido de um cliente para o outro. | `identifier_conflict` |
| `customer.id` não existe | `404` com `customer_not_found`. Os outros identificadores não são testados. | |
| Os identificadores só pertencem a um cliente excluído | Cliente excluído nunca casa e nunca é reativado por um evento. Um cliente novo é criado. | |

Cada aviso traz `code`, `message` e `param` (por exemplo `customer.email`).

### Dados do cliente na mesma chamada

* `customer.name` atualiza o nome do cliente.
* `customer.attributes` grava atributos do cliente. Só as chaves enviadas
  mudam. Os valores podem ser texto (até 256 caracteres), número ou booleano, e
  as chaves têm até 64 caracteres.
* Um atributo que ainda não existe é criado com o tipo inferido do valor: texto,
  número, booleano ou data (texto em ISO 8601).
* Um valor que não cabe no tipo de um atributo existente recusa o evento com
  `attribute_type_mismatch`. Nada é gravado.
* Um cliente só com `external_id`, sem e-mail nem telefone, é válido. O evento
  é gravado, e um flow que não consegue alcançá-lo por nenhum canal aparece
  como `skipped` com `no_contact_channel`.

## Repetir com segurança

`external_id` é o ID do fato no seu sistema, como `ship_10293`. Ele é único por
nome de evento durante **90 dias**. Reenviar o mesmo `name` e `external_id`
nesse período responde `200` com o evento original e `duplicate: true`.

* **Nada acontece de novo.** O reenvio não dispara flows e não toca no cliente:
  atributos e identificadores não são reaplicados.
* **Corpo diferente no reenvio.** O primeiro envio continua valendo, e a
  resposta traz o aviso `payload_mismatch`. Não é um upsert.
* **Sem `external_id`.** Cada chamada é um evento novo. A API nunca deduplica
  por conta própria.

O header `Idempotency-Key` também é aceito nos envios (`POST /v1/events` e
`POST /v1/events/bulk`). Durante 24 horas, repetir a mesma chave com o mesmo
corpo devolve a resposta guardada, com o header `Idempotent-Replayed: true`. A
mesma chave com outro corpo responde `409 conflict`.

Use os dois: `external_id` protege o fato, `Idempotency-Key` protege a
requisição. No lote, o `Idempotency-Key` é o que impede um timeout de duplicar
os itens sem `external_id`.

```bash theme={null}
curl https://api.bevits.com/v1/events \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-ship-10293" \
  -d '{
    "name": "order_shipped",
    "customer": { "external_id": "u_8842" },
    "external_id": "ship_10293"
  }'
```

## Propriedades e limites

`properties` é um objeto JSON livre e é todo seu: não há chave reservada. Os
valores podem ser texto, número, booleano, data (texto em ISO 8601), lista e
objeto. Não existe esquema a cadastrar. O tipo de cada propriedade é inferido
dos eventos recebidos e aparece em [Tipos de evento](#tipos-de-evento).

O que não cabe é recusado com `422` e um `error.code`. Nada é truncado.

| Limite | Valor | `error.code` |
| - | - | - |
| Tamanho do evento | 64 KB | `event_too_large` |
| Chaves em `properties`, contando as aninhadas | 200 | `too_many_properties` |
| Profundidade de `properties` | 5 níveis | `properties_too_deep` |
| Itens por lista | 100 | `array_too_long` |
| Nomes de evento ativos por loja | 500 | `too_many_event_names` |
| Eventos por lote | 100 | |
| Tamanho do lote | 1 MB | `batch_too_large` |

O limite de nomes existe para pegar cedo o erro de colocar dado no nome, como
`order_10293_shipped`. O nome diz o que aconteceu; IDs e valores vão em
`properties`. Tipos de evento arquivados não contam no limite, e um evento com
nome arquivado é recusado com `event_type_archived`.

## Tempo

`occurred_at` diz quando o fato aconteceu. Sem ele, vale o momento do
recebimento.

| `occurred_at` | Resultado |
| - | - |
| Mais de 5 minutos no futuro | `422` com `occurred_at_in_future`. |
| Mais antigo que 13 meses | `422` com `occurred_at_too_old`. |
| Mais antigo que 72 horas | O evento é gravado, mas não dispara flows: `flows[].reason` é `stale`. |
| Qualquer valor aceito, com `backfill: true` | O evento é gravado, mas não dispara flows: `flows[].reason` é `backfill`. |

Use `backfill: true` para importar histórico. A regra das 72 horas protege
contra uma fila reprocessada despejar mensagens antigas nos seus clientes.

## O que a resposta diz

`201 Created` quando o evento é novo. `200 OK` com o evento original quando o
`external_id` já existia.

```json theme={null}
{
  "object": "event",
  "id": "evt_01jd2v9k3m8q4r5s6t7u8v9w0x",
  "name": "order_shipped",
  "external_id": "ship_10293",
  "occurred_at": "2026-11-18T17:03:00.000Z",
  "received_at": "2026-11-18T17:03:01.000Z",
  "customer": {
    "id": "cus_ckabc123",
    "matched_by": "external_id",
    "created": false
  },
  "flows": [
    { "id": "flw_ckdef456", "name": "Pedido enviado", "status": "queued" },
    {
      "id": "flw_ckghi789",
      "name": "Entrega expressa",
      "status": "skipped",
      "reason": "filter_not_matched"
    }
  ],
  "properties": {
    "order_number": "10293",
    "tracking": { "code": "BR123", "carrier": "Correios" }
  },
  "backfill": false,
  "livemode": true
}
```

Uma resposta de sucesso é uma promessa: o evento está gravado, ligado a um
cliente e pode ser lido pelo `id` na hora.

* `customer.matched_by` diz qual identificador encontrou o cliente. Quando o
  evento criou o cliente, vem `created: true` e `matched_by` é omitido.
* `flows` lista os flows **ativos** que escutam esse nome. Lista vazia significa
  que nenhum flow está escutando.
* `warnings` aparece só quando há algo a avisar. Um aviso nunca substitui um
  erro.
* `duplicate: true` aparece quando a chamada devolveu um evento que já existia.

### `flows[].status` e `flows[].reason`

| `status` | Significado |
| - | - |
| `queued` | O início do flow foi enfileirado. É o que a resposta do envio informa. |
| `started` | O flow foi iniciado para o cliente. Aparece ao consultar o evento depois. |
| `skipped` | O flow não foi iniciado. `reason` diz por quê. |

| `reason` | Quando é decidido | Significado |
| - | - | - |
| `test_mode` | No envio | O evento foi enviado com uma chave de teste. |
| `backfill` | No envio | O evento veio com `backfill: true`. |
| `stale` | No envio | `occurred_at` tem mais de 72 horas. |
| `filter_not_matched` | No envio | As propriedades não passaram nos filtros do gatilho. |
| `no_contact_channel` | Depois | O cliente não tem o contato (e-mail ou telefone) de nenhum canal usado pelo flow. |
| `no_consent` | Depois | O cliente tem o contato, mas não aceitou receber mensagens dessa natureza por nenhum canal usado pelo flow ([quem recebe](#quem-recebe-as-mensagens-do-flow)). |
| `flow_inactive` | Depois | O flow foi desativado antes de iniciar. |
| `flow_error` | No envio ou depois | O flow tem um gatilho ou passos que não podem ser lidos, por isso não foi iniciado. Abra o flow na Bevits e publique de novo. |
| `dispatch_failed` | Depois | A Bevits não conseguiu iniciar o flow, mesmo tentando de novo por 72 horas. Nenhuma mensagem foi enviada por este evento. |

Para saber o que aconteceu com um flow `queued`,
[consulte o evento](#ler-um-evento).

### Avisos de um flow

Um flow iniciado pode trazer `flows[].warnings`: o que ele não conseguiu fazer e
você pode corrigir no envio. O campo só aparece quando há algo a avisar.

| `flows[].warnings[].code` | Significado |
| - | - |
| `missing_variable` | Uma mensagem do flow (e-mail, SMS ou WhatsApp) foi pulada porque uma variável do template não tinha valor nem texto alternativo. `param` aponta a propriedade que faltou, como `properties.tracking.code`. |

### Avisos

| `warnings[].code` | Significado |
| - | - |
| `ambiguous_identifier` | Vários clientes tinham o mesmo identificador. O mais antigo foi usado. |
| `identifier_conflict` | Um identificador enviado pertence a outro cliente e ficou com ele. |
| `identifier_mismatch` | O cliente já tinha um valor diferente para esse identificador, e ele foi mantido. |
| `payload_mismatch` | Já existia um evento com o mesmo `name` e `external_id` e outro corpo. O primeiro continua valendo. |

## Disparar um flow com o evento

Um flow escuta um evento personalizado pelo gatilho `custom.<nome_do_evento>`.
Crie o flow por `POST /v1/flows` com `platform: "custom"` e o nome do evento em
`event`:

```json theme={null}
{
  "name": "Pedido enviado pelos Correios",
  "trigger": {
    "platform": "custom",
    "event": "order_shipped",
    "filters": [
      { "property": "tracking.carrier", "operator": "equals", "value": "Correios" }
    ]
  },
  "start": "avisar",
  "nodes": [
    { "key": "avisar", "type": "send_whatsapp", "template_id": "wtp_…" }
  ]
}
```

* `trigger.filters` é opcional e aceita até 10 filtros. O flow só inicia quando
  todos casam com as propriedades do evento. `property` é o caminho da
  propriedade, como `tracking.carrier` ou `items[0].sku`.
* Uma propriedade ausente ou de outro tipo simplesmente não passa no filtro. O
  flow aparece como `skipped` com `filter_not_matched`.
* As mensagens usam as propriedades do evento como [variáveis](#variáveis), e
  os blocos de condição as comparam com `field: "event.<caminho>"`
  ([condições](#condições)).
* O flow é criado como rascunho. Ele só recebe eventos depois de ativado
  (`POST /v1/flows/{flow_id}/activate`).
* O flow pode ser criado antes de o primeiro evento com esse nome chegar.

No painel, o mesmo gatilho fica em **API de eventos → Evento personalizado**, no
bloco de gatilho do flow: escolha um evento já recebido ou digite o nome, e
adicione filtros pelas propriedades. As receitas **Pedido enviado** e **Pix
gerado** criam flows prontos para `order_shipped` e `pix_generated`.

### Variáveis

As mensagens do flow (e-mail, SMS e WhatsApp) leem as propriedades do evento
como variáveis:

| Variável | O que lê |
| - | - |
| `{{event.tracking.code}}` | Uma propriedade, em qualquer profundidade. |
| `{{event.items[0].name}}` | Um item de lista, pela posição. |
| `{{event.carrier \| default: "Correios"}}` | O texto alternativo, usado quando a propriedade não veio ou está vazia. Aspas simples também valem. |

* Uma variável sem valor e sem texto alternativo faz a mensagem ser pulada, em
  qualquer canal (e-mail, SMS e WhatsApp), para o cliente nunca receber a
  variável como foi escrita. O evento registra `missing_variable` no flow
  ([avisos de um flow](#avisos-de-um-flow)). Nos templates oficiais do
  WhatsApp, use uma variável dinâmica para dar um texto alternativo.
* Uma lista ou um objeto inteiro é escrito como JSON. No e-mail, o bloco de
  itens do pedido mostra `items[]` quando os itens seguem o formato do
  [catálogo](https://docs.bevits.com/pt-BR/api-reference/recommended-events.md) (`name`, `quantity`,
  `price_in_cents`, `image_url`, `url`).
* No editor, as propriedades já recebidas aparecem no grupo **Evento** do
  seletor de variáveis.

### Condições

Um bloco de condição compara uma propriedade do evento com
`field: "event.<caminho>"`. A propriedade é comparada como o tipo do valor dado:
número, booleano ou texto, e lista com `includes`.

```json theme={null}
{
  "key": "expressa",
  "type": "condition",
  "field": "event.shipping.express",
  "operator": "equals",
  "value": true,
  "if_true": "avisar"
}
```

As propriedades não têm esquema: uma propriedade de outro tipo não pode ser
comparada, a condição é falsa e a execução registra o motivo. No editor, o
bloco de condição oferece o grupo **Evento**, com as propriedades já recebidas
e o tipo de cada uma.

### Aguardar e encerrar por evento

Um flow também pode **escutar** eventos do mesmo cliente enquanto está em
execução. São dois usos do mesmo mecanismo:

* **Aguardar evento**: um bloco que pausa a execução até o evento chegar, com um
  tempo máximo de até 90 dias. Tem duas saídas: *chegou* (`if_arrived`) e
  *tempo esgotado* (`if_timed_out`).
* **Encerrar quando chegar**: no gatilho, eventos que encerram a execução assim
  que chegam (`trigger.exit_on`, até 5). Ex.: a cobrança de um Pix termina
  quando chega `payment_confirmed`.

```json theme={null}
{
  "name": "Pix com lembrete",
  "trigger": {
    "platform": "custom",
    "event": "pix_generated",
    "exit_on": [{ "event": "order_cancelled", "match_on": "order_number" }]
  },
  "start": "codigo",
  "nodes": [
    { "key": "codigo", "type": "send_whatsapp", "template_id": "wtp_…", "next": "pagou" },
    {
      "key": "pagou",
      "type": "wait_for_event",
      "event": "payment_confirmed",
      "match_on": "order_number",
      "timeout_amount": 15,
      "timeout_unit": "minutes",
      "if_arrived": "obrigado",
      "if_timed_out": "lembrete"
    },
    { "key": "obrigado", "type": "send_email", "template_id": "etp_…" },
    { "key": "lembrete", "type": "send_whatsapp", "template_id": "wtp_…" }
  ]
}
```

* **Um evento que chega antes também conta.** Tudo o que o flow escuta é
  registrado quando a execução começa. Se o `payment_confirmed` chega antes de
  a execução alcançar o bloco de espera (ou antes até de o flow começar), o
  bloco segue na hora pela saída *chegou*, e uma regra de saída encerra a
  execução antes do primeiro envio.
* **`match_on` liga ao pedido certo.** Sem ele, qualquer evento com esse nome do
  mesmo cliente conta. Com `"match_on": "order_number"`, só conta o evento
  cujo `order_number` é igual ao do evento que iniciou o flow, para um cliente
  com dois pedidos abertos não ter os dois encerrados por um pagamento. `10293`
  e `"10293"` são o mesmo valor. Só vale em flows iniciados por evento
  personalizado; se o evento inicial não tiver a propriedade, nada casa.
* **`filters`** funcionam como os do gatilho: só conta o evento que passa em
  todos.
* **Encerrar é cancelar.** A execução é cancelada e nenhum envio seguinte sai:
  todo envio confere o cancelamento antes de sair.
* Eventos de teste (`bvt_test_`) e de `backfill` nunca contam: um não acontece
  de verdade, o outro é histórico importado.
* O bloco de espera conta o tempo máximo a partir de quando a execução chega
  nele.
* Os blocos seguintes leem o evento recebido como
  `{{events.<nome>.<caminho>}}`, por exemplo
  `{{events.payment_confirmed.payment_method}}`. Se o tempo esgotar, essas
  variáveis não têm valor: use um texto alternativo
  (`{{events.payment_confirmed.payment_method | default: "Pix"}}`).
* Flows do Instagram não aguardam nem encerram por evento.

No painel, o bloco **Aguardar evento** fica na barra lateral do editor, e as
regras de saída ficam no bloco de gatilho, em **Encerrar quando chegar**. A
receita **Pix gerado** já vem com um lembrete que para quando chega o
`payment_confirmed` do mesmo `order_number`.

## Validar sem gravar

`POST /v1/events/validate` recebe o mesmo corpo e devolve o que
`POST /v1/events` devolveria, sem gravar nada e sem alterar clientes. Use
durante o desenvolvimento para ver qual cliente casaria, quais flows seriam
enfileirados e quais avisos surgiriam.

```bash theme={null}
curl https://api.bevits.com/v1/events/validate \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "customer": { "email": "novo@exemplo.com.br" }
  }'
```

* Exige o escopo `read`. Uma chave só com `events:write` não pode validar.
* Quando o envio criaria o cliente, a resposta traz
  `"customer": { "would_create": true }`.
* O `id` do evento devolvido é provisório: não existe um evento para consultar
  depois.
* Os erros são os mesmos do envio.

## Envio em lote

`POST /v1/events/bulk` aceita até 100 eventos e 1 MB por chamada. Cada item tem
o mesmo formato de `POST /v1/events`.

```bash cURL theme={null}
curl https://api.bevits.com/v1/events/bulk \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stock-CAM-01-2026-11-18" \
  -d '{
    "events": [
      {
        "name": "back_in_stock",
        "customer": { "email": "ana@exemplo.com.br" },
        "properties": { "product": { "sku": "CAM-01", "name": "Camiseta" } },
        "external_id": "stock_CAM-01_u_8842"
      },
      {
        "name": "back_in_stock",
        "customer": { "email": "bruno@exemplo.com.br" },
        "properties": { "product": { "sku": "CAM-01", "name": "Camiseta" } },
        "external_id": "stock_CAM-01_u_9120"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const events = interested.map((customer) => ({
  name: "back_in_stock",
  customer: { email: customer.email },
  properties: { product: { sku: "CAM-01", name: "Camiseta" } },
  external_id: `stock_CAM-01_${customer.id}`,
}));

const response = await fetch("https://api.bevits.com/v1/events/bulk", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BEVITS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "stock-CAM-01-2026-11-18",
  },
  body: JSON.stringify({ events }),
});

const batch = await response.json();

if (!response.ok) {
  throw new Error(`${batch.error.code ?? batch.error.type}: ${batch.error.message}`);
}

// results tem a mesma ordem de events.
batch.results.forEach((result, index) => {
  if (result.status === "error") {
    console.error(events[index].external_id, result.error.code, result.error.param);
  }
});
```

```python Python theme={null}
import os
import requests

events = [
    {
        "name": "back_in_stock",
        "customer": {"email": customer["email"]},
        "properties": {"product": {"sku": "CAM-01", "name": "Camiseta"}},
        "external_id": f"stock_CAM-01_{customer['id']}",
    }
    for customer in interested
]

response = requests.post(
    "https://api.bevits.com/v1/events/bulk",
    headers={
        "Authorization": f"Bearer {os.environ['BEVITS_API_KEY']}",
        "Idempotency-Key": "stock-CAM-01-2026-11-18",
    },
    json={"events": events},
    timeout=60,
)
batch = response.json()

if not response.ok:
    error = batch["error"]
    raise RuntimeError(f"{error.get('code', error['type'])}: {error['message']}")

# results tem a mesma ordem de events.
for event, result in zip(events, batch["results"]):
    if result["status"] == "error":
        print(event["external_id"], result["error"].get("code"), result["error"].get("param"))
```

A resposta é `200` com um resultado por evento:

```json theme={null}
{
  "object": "event_batch",
  "created": 1,
  "duplicate": 1,
  "failed": 1,
  "results": [
    { "status": "created", "event": { "object": "event", "id": "evt_…" } },
    { "status": "duplicate", "event": { "object": "event", "id": "evt_…", "duplicate": true } },
    {
      "status": "error",
      "error": {
        "type": "validation_error",
        "code": "invalid_tax_id",
        "message": "tax_id must be a valid CPF or CNPJ. For other documents, identify the customer by external_id.",
        "param": "events[2].customer.tax_id"
      }
    }
  ]
}
```

* **Não é atômico.** Cada evento vale por si. Um evento inválido falha sozinho
  e os outros seguem.
* `results` tem a mesma ordem e o mesmo tamanho de `events`. Cada `event` vem
  completo, como na resposta de `POST /v1/events`.
* O `param` de cada erro começa pela posição do evento: `events[2].name`.
* O `200` não significa que tudo foi aceito. Confira `failed` e reenvie só os
  itens com `status: "error"` depois de corrigi-los.
* O lote inteiro só é recusado (`422`) quando `events` está vazio, tem mais de
  100 itens ou passa de 1 MB (`batch_too_large`).
* **Ordem:** os eventos são gravados na ordem enviada. A ordem em que os flows
  de eventos diferentes executam não é garantida.

## Ler um evento

`GET /v1/events/{event_id}` devolve o evento, o cliente a que foi ligado e o
que aconteceu com cada flow. Funciona logo depois do envio.

```bash theme={null}
curl https://api.bevits.com/v1/events/evt_01jd2v9k3m8q4r5s6t7u8v9w0x \
  -H "Authorization: Bearer $BEVITS_API_KEY"
```

O corpo é o mesmo objeto `event` do envio. Nele, cada flow que estava `queued`
passa a `started` ou a `skipped` com o motivo.

No painel, **Configurações → Eventos** mostra os eventos recebidos ao vivo, com
o cliente encontrado e o resultado de cada flow, e permite enviar um evento de
teste. É lá também que um tipo de evento ganha rótulo e natureza, ou é
arquivado.

Um evento pode ser lido pelo ID durante os 13 meses de histórico, com
`properties` e o resultado de cada flow. Depois disso, a rota responde `404`.

## Listar eventos

`GET /v1/events` lista os eventos da loja, do recebido mais recentemente ao
mais antigo. `GET /v1/customers/{customer_id}/events` é a linha do tempo de um
cliente, incluindo os eventos de clientes que foram fundidos a ele.

```bash theme={null}
curl "https://api.bevits.com/v1/events?name=order_shipped&occurred_after=2026-11-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $BEVITS_API_KEY"
```

```json theme={null}
{
  "data": [{ "object": "event", "id": "evt_01jd2v9k3m8q4r5s6t7u8v9w0x", "name": "order_shipped", "...": "..." }],
  "has_more": true
}
```

| Parâmetro | Uso |
| - | - |
| `name` | Só eventos com esse nome. |
| `customer_id` | Só eventos desse cliente (`cus_…`), incluindo os de clientes fundidos a ele. |
| `external_id` | O evento enviado com esse `external_id`. |
| `occurred_after` | Aconteceu nesse momento ou depois (ISO 8601 com offset). |
| `occurred_before` | Aconteceu antes desse momento. |
| `limit` | De 1 a 100. Padrão: 25. |
| `starting_after` | O `id` do último evento da página anterior. |

* Cada item é o mesmo objeto `event` de `GET /v1/events/{event_id}`.
* Um evento aparece na listagem assim que é aceito, sem esperar.
* A listagem cobre os 13 meses de histórico. Uma chave de teste lista os
  eventos de teste; uma chave de produção, os de produção.
* O histórico vive em um armazenamento analítico. Se ele estiver indisponível,
  as listagens respondem `503`; `GET /v1/events/{event_id}` continua
  respondendo para eventos recentes.

## No painel

* **Configurações → Eventos → Chamadas recusadas** mostra, por 7 dias, cada
  chamada que a API recusou: o erro, o campo, o `request_id`, a chave usada e o
  corpo exatamente como foi enviado. Num lote, cada evento recusado aparece com
  o próprio corpo. Depois de 7 dias, o registro é apagado.
* A aba **Eventos** do cliente, no CRM, mostra a linha do tempo dele.
  Proprietários e administradores podem apagar ali o histórico de eventos de um
  cliente (LGPD): as propriedades saem da Bevits na hora e o histórico é
  removido em até um dia. O cliente continua no CRM.
* **Segmentos por evento.** No filtro de clientes, a condição **Evento
  personalizado** seleciona quem fez um evento ao menos, no máximo ou
  exatamente N vezes, ou nunca, em todo o histórico, nos últimos N dias ou entre
  duas datas, com até 5 filtros por propriedade (`items[].sku` inclui `CAM-01`,
  `total` maior que 100). Combina com as outras condições por E e OU. Eventos
  de teste nunca contam; eventos de `backfill` contam. "Nunca" vale dentro dos
  13 meses de histórico.

## Tipos de evento

`GET /v1/event-types` lista os nomes de evento que a loja já enviou, com as
propriedades inferidas dos eventos recebidos.

```bash theme={null}
curl https://api.bevits.com/v1/event-types \
  -H "Authorization: Bearer $BEVITS_API_KEY"
```

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "event_type",
      "name": "order_shipped",
      "nature": "utility",
      "archived": false,
      "first_seen_at": "2026-11-18T17:03:01.000Z",
      "last_seen_at": "2026-11-18T19:40:12.000Z",
      "properties": [
        { "path": "order_number", "type": "string", "example": "10293" },
        { "path": "tracking", "type": "object" },
        { "path": "tracking.code", "type": "string", "example": "BR123" },
        { "path": "items", "type": "list" },
        { "path": "items[]", "type": "object" },
        { "path": "items[].quantity", "type": "number", "example": 2 }
      ]
    }
  ],
  "has_more": false
}
```

* `properties[].path` usa pontos para objetos e `[]` para itens de lista.
  `type` é `string`, `number`, `boolean`, `date`, `list` ou `object`.
* As propriedades são uma ajuda, não uma restrição: um evento com outro
  formato continua sendo aceito. Elas aparecem pouco depois de o evento ser
  recebido.
* `nature` é `utility` ou `marketing`. Os nomes do
  [catálogo de eventos recomendados](https://docs.bevits.com/pt-BR/api-reference/recommended-events.md)
  já nascem com a natureza do catálogo; os outros nascem sem esse campo.
* A lista vem inteira, sem paginação. Tipos arquivados só aparecem com
  `?include_archived=true`.

## Chave só de envio

O escopo `events:write` pode existir sozinho em uma chave. É a chave indicada
para o backend que só alimenta eventos: ela envia, e não consegue ler a base de
clientes.

| Rota | Escopo aceito |
| - | - |
| `POST /v1/events` | `write` ou `events:write` |
| `POST /v1/events/bulk` | `write` ou `events:write` |
| `POST /v1/events/validate` | `read` |
| `GET /v1/events/{event_id}` | `read` |
| `GET /v1/events` | `read` |
| `GET /v1/customers/{customer_id}/events` | `read` |
| `GET /v1/event-types` | `read` |

Com uma chave só de envio:

* Qualquer outra rota responde `403` com `missing_scope`.
* A resposta do envio traz apenas `customer.id`. `customer.matched_by` e
  `customer.created` são omitidos.
* Os avisos de identidade (`ambiguous_identifier`, `identifier_conflict`,
  `identifier_mismatch`) são omitidos. Só `payload_mismatch` aparece.

Assim, uma chave vazada não serve para descobrir se um e-mail ou telefone é
cliente da loja.

## Limites de requisição

As rotas de envio têm um limite próprio, por segundo, separado do limite geral
de 600 requisições por minuto.

| Rota | Limite por API key |
| - | - |
| `POST /v1/events` | 100 requisições por segundo |
| `POST /v1/events/validate` | 100 requisições por segundo |
| `POST /v1/events/bulk` | 2000 eventos por segundo, contados por evento |

As respostas trazem `X-RateLimit-Limit`, `X-RateLimit-Remaining` e
`X-RateLimit-Reset`. Ao receber `429`, aguarde os segundos indicados em
`Retry-After`. As rotas de leitura (`GET /v1/events`, `GET /v1/events/{event_id}`,
`GET /v1/customers/{customer_id}/events` e `GET /v1/event-types`) usam o limite
geral.

## Modo de teste

Com uma chave de teste (`bvt_test_…`), o evento passa por toda a validação e
resolução, mas não muda nada em produção:

* **Nunca cria nem altera clientes.** A resposta devolve o cliente que casaria,
  ou `"customer": { "would_create": true }` quando o envio criaria um.
* **Nunca envia mensagem.** Os flows aparecem como `skipped` com
  `reason: "test_mode"`.
* **Fica separado.** O evento é gravado com `livemode: false`. Eventos, tipos
  de evento e a unicidade do `external_id` são separados entre teste e
  produção, e cada chave só lê os eventos do seu modo. Nomes vistos só em teste
  não contam no limite de 500.

## Consentimento na criação do cliente

* Um evento **nunca altera** o opt-in ou o opt-out de um cliente que já existe.
* Um cliente criado por um evento nasce **sem opt-in de marketing**, a menos
  que a chamada traga `customer.consent`.
* `customer.consent` só é lido quando o evento cria o cliente.

```json theme={null}
{
  "name": "account_created",
  "customer": {
    "email": "ana@exemplo.com.br",
    "phone": "+5511988887777",
    "consent": { "email": true, "whatsapp": true }
  }
}
```

`consent.whatsapp` vale para WhatsApp e SMS. `consent.email` vale para e-mail.

### Quem recebe as mensagens do flow

O que um flow pode enviar depende da [natureza do
evento](https://docs.bevits.com/pt-BR/api-reference/recommended-events.md#1-natureza-do-evento) que o
iniciou e do consentimento do cliente em cada canal:

| Cliente | Evento de marketing | Evento de utilidade |
| - | - | - |
| Aceitou receber mensagens | recebe | recebe |
| Nunca aceitou (inclusive o criado sem `consent`) | não recebe | recebe |
| Pediu para sair | não recebe | não recebe |

* **Utilidade é sobre algo que o cliente fez**, como o rastreio de um pedido ou
  o código de um Pix. Por isso alcança quem não aceitou marketing.
* **No WhatsApp oficial, o template também precisa ser de utilidade.** Uma
  mensagem só conta como utilidade quando o evento é de utilidade e a Meta
  aprovou o template na categoria de utilidade. Um template de marketing segue
  a regra de marketing, mesmo num flow iniciado por um evento de utilidade.
* **Eventos sem natureza seguem a regra de marketing.** A natureza de cada tipo
  de evento pode ser alterada em Configurações → Eventos.
* **E-mail e WhatsApp são independentes.** `consent: { "email": true,
  "whatsapp": false }` recebe e-mails de marketing e só WhatsApp e SMS de
  utilidade. Quem pediu para sair de todas as mensagens não recebe e-mail.

Um flow que não alcançaria o cliente por nenhum canal aparece como `skipped`
com `no_consent`.

## Referência de erros

Todo erro segue o envelope da API. Nos eventos, `error.code` nomeia o motivo,
`error.param` traz o caminho completo do campo (`customer.email`,
`events[3].name`) e `error.suggestion`, quando existe, traz um valor que seria
aceito. Um evento recusado não grava nada e não toca em nenhum cliente.

| HTTP | `error.code` | `error.param` | Significado |
| - | - | - | - |
| `422` | `invalid_event_name` | `name` | O nome não segue o formato. `suggestion` traz o nome corrigido, quando há um. |
| `422` | `missing_customer_identifier` | `customer` | `customer` não tem nenhum identificador. |
| `422` | `unknown_field` | o campo | O corpo tem um campo que a API não conhece. |
| `422` | `invalid_tax_id` | `customer.tax_id` | `tax_id` não é um CPF ou CNPJ válido. Para outros documentos, use `external_id`. |
| `422` | `invalid_phone` | `customer.phone` | O telefone não é um número válido. |
| `422` | `attribute_type_mismatch` | `customer.attributes.<chave>` | O valor não cabe no tipo do atributo que já existe. |
| `422` | `event_too_large` | | O evento tem mais de 64 KB. |
| `422` | `too_many_properties` | `properties` | `properties` tem mais de 200 chaves no total. |
| `422` | `properties_too_deep` | o caminho | `properties` tem mais de 5 níveis. |
| `422` | `array_too_long` | o caminho | Uma lista tem mais de 100 itens. |
| `422` | `occurred_at_in_future` | `occurred_at` | `occurred_at` está mais de 5 minutos no futuro. |
| `422` | `occurred_at_too_old` | `occurred_at` | `occurred_at` é mais antigo que 13 meses. |
| `422` | `too_many_event_names` | `name` | A loja já tem 500 nomes de evento ativos. |
| `422` | `event_type_archived` | `name` | O tipo de evento está arquivado. |
| `422` | `batch_too_large` | `events` | O lote tem mais de 1 MB. |
| `404` | `customer_not_found` | `customer.id` | Nenhum cliente ativo tem esse `id`. |
| `403` | `missing_scope` | `scope` | A chave não tem o escopo que a rota exige. |

Outros erros de validação, como um e-mail mal formado ou um `occurred_at` sem
offset, respondem `422 validation_error` com `param` e sem `code`. Os demais
erros seguem os [fundamentos](https://docs.bevits.com/pt-BR/api-reference/fundamentals.md#erros):

| HTTP | `error.type` | Quando |
| - | - | - |
| `400` | `invalid_request` | O corpo não é um objeto JSON, ou o `event_id` da rota é inválido. |
| `404` | `not_found` | O evento não existe, é de outro modo (teste ou produção) ou já passou do prazo de leitura. |
| `409` | `conflict` | O `Idempotency-Key` já foi usado com outro corpo. |
| `429` | `rate_limited` | O limite por segundo foi excedido. Aguarde `Retry-After`. |
| `503` | `service_unavailable` | O histórico de eventos está indisponível. Tente de novo em alguns minutos; a leitura de um evento recente pelo ID continua funcionando. |

## Próximos passos

> [card] [Eventos recomendados](https://docs.bevits.com/pt-BR/api-reference/recommended-events.md)
>
> Nomes e propriedades sugeridos para os eventos mais comuns de e-commerce.

> [card] [Autenticação](https://docs.bevits.com/pt-BR/api-reference/authentication.md)
>
> Crie uma chave só de envio com o escopo `events:write`.


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