# Enviar eventos do seu backend

> Registre eventos do workspace e eventos personalizados dos seus servidores com a API de eventos, um de cada vez ou em lotes, com uma chave de API Events Only.

Envie eventos dos seus servidores para tudo o que não pode depender do navegador do visitante, como pedidos, pagamentos, mudanças de assinatura ou eventos de um back office. Esta página mostra como enviar um evento, como enviar vários e como tratar erros.

## Antes de começar

- O envio de eventos está incluído nos planos Pro, Business e Custom. Um workspace Pro pode usar 100 tipos de evento, e um workspace Business, 1.000. Consulte [Limites](/pt/docs/events/#limits).
- Crie uma chave de API com o escopo **Events Only** em **Email API → API Keys**. Ela pode enviar eventos e nada mais: não pode ler os seus dados, gerenciar definições de eventos nem enviar e-mails. Uma chave **Full Access** também funciona. Consulte [Chaves de API](/pt/docs/developers/api-keys/#scopes).
- Para enviar eventos do workspace, [defina-os](/pt/docs/events/workspace-events/) antes. Os eventos personalizados não precisam de configuração.

## Enviar um evento

Chame [Enviar um evento](/pt/docs/api-reference/events/send/) com o `type` do evento, as `properties` dele e a pessoa a que ele se refere:

```bash
curl -X POST https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "c:order.completed",
    "email": "jane@example.com",
    "properties": { "order_id": "1001", "total": 59.9, "currency": "EUR" },
    "occurred_at": "2026-10-19T09:30:00Z"
  }'
```

- `email` vincula o evento ao contato com esse endereço. Se você já souber o ID do contato, envie `contact_id` no lugar.
- `occurred_at` indica quando o evento aconteceu, por exemplo, quando você envia eventos a partir de uma fila. Omita-o para usar o horário atual.
- A resposta é `201` com o evento armazenado e o ID `evt_` dele. Uma chave Events Only recebe o evento de volta sem `data`.

## Enviar vários eventos de uma vez

[Enviar eventos em lote](/pt/docs/api-reference/events/batch/) aceita até 100 eventos em uma requisição, o que é adequado para importações e sincronizações agendadas:

```bash
curl -X POST https://api.emailit.com/v2/events/batch \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "c:order.completed", "email": "jane@example.com", "properties": { "order_id": "1001", "total": 59.9 } },
      { "type": "c:order.completed", "email": "omar@example.com", "properties": { "order_id": "1002", "total": 18 } }
    ]
  }'
```

Um lote é tudo ou nada: se um evento for inválido, nenhum é armazenado. A resposta `422` lista cada problema em `events.<index>`, para que você corrija ou remova esses eventos e envie o lote de novo.

## Tratar erros

| Status | Significado | O que fazer |
| --- | --- | --- |
| `201` | Armazenado. | Nada. |
| `400` | O corpo não é um objeto JSON, ou o lote está vazio ou tem mais de 100 eventos. | Corrija a requisição. |
| `401` | A chave de API está ausente ou incorreta. | Verifique a chave. |
| `403` | O escopo da chave não permite enviar eventos, ou o workspace está no Pay as you go (`"error": "plan_required"`). | Use uma chave Events Only ou Full Access, ou faça upgrade para o Pro ou o Business. |
| `422` | Um evento é inválido: um evento `w:` que não está definido, uma propriedade com o tipo errado, um `contact_id` desconhecido, uma data mais de 24 horas no futuro ou um tipo de evento novo quando o workspace já usa o número de tipos do plano. `errors` indica cada campo. | Corrija o evento ou faça upgrade para ter mais tipos de evento. Tentar de novo sem alterá-lo falha outra vez. |
| `5xx` | Um problema temporário do lado do Emailit. | Tente de novo com backoff. |

Os eventos não têm chave de idempotência, então tentar de novo uma requisição que já foi processada armazena o evento duas vezes. Coloque o seu próprio ID nas propriedades, como `order_id`, para que quem lê os eventos possa reconhecer duplicados.

## Verificar se os eventos chegam

Abra **Email API → Events**. A aba **Log** lista os eventos novos no topo; defina **Scope** como **Custom** ou **Workspace** para ocultar os eventos do sistema. Selecione um evento para ver as propriedades dele, o contato a que pertence e de onde veio. Os eventos vinculados a um contato também aparecem no **Activity log** do contato.

## Veja também

  - [Rastreamento de eventos](/pt/docs/events/): Escopos, nomes e para onde vão os eventos.
  - [Script de rastreamento](/pt/docs/events/tracking-script/): Envie eventos do seu site.
  - [Enviar um evento](/pt/docs/api-reference/events/send/): Todos os parâmetros e respostas.
  - [Chaves de API](/pt/docs/developers/api-keys/): Crie uma chave Events Only.

---
Fonte: https://emailit.com/pt/docs/events/send-events/