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

# API de Eventos

> Envie eventos de rastreamento pelo servidor a partir de qualquer plataforma usando a API pública v3 do Metrito

A API de Eventos permite enviar eventos de rastreamento a partir de qualquer sistema — backends, ferramentas de automação (n8n, Make, Zapier), CRMs, plataformas de e-commerce ou integrações personalizadas.

Na versão **v3**, a API suporta envios assíncronos (padrão) e síncronos, e introduz o suporte à autenticação via Chave de API, recomendada para maior segurança e controle. IDs são gerados automaticamente quando não fornecidos.

## Endpoint

```http theme={null}
POST https://api.metrito.com/v3/tracking/events
```

| Propriedade      | Valor                                    |
| ---------------- | ---------------------------------------- |
| **Método**       | POST                                     |
| **Autenticação** | Opcional (Obrigatória para `?sync=true`) |
| **Content-Type** | `application/json`                       |

## Autenticação e Sincronismo

A API suporta dois modos de funcionamento:

1. **Modo Assíncrono (Padrão)**: O evento é enfileirado e processado em segundo plano. Não exige chave de API. Responde com sucesso quase imediatamente.
2. **Modo Síncrono (`?sync=true`)**: O evento é processado na hora da requisição. Retorna um objeto JSON com o ID do evento, ID do lead e status de criação no banco de dados. **Exige autenticação**.

Para autenticar a requisição, adicione o seguinte cabeçalho (header):

```text theme={null}
Authorization: Bearer SUA_CHAVE_DE_API
```

Você pode criar suas chaves de API no painel do Metrito em **Configurações → Chaves de API**. A chave deve ter permissão de escrita para rastreamento (`tracking:write`).

## Campos Obrigatórios

Toda requisição precisa de pelo menos a indicação do contêiner e do nome do evento.

```json theme={null}
{
  "container_id": "MTC-55AEW53Y",
  "config": {
    "name": "NomeDoEvento"
  }
}
```

| Campo          | Descrição                                                                         |
| -------------- | --------------------------------------------------------------------------------- |
| `container_id` | ID MTC (ex: `MTC-5X35GWQ`) ou o domínio do seu contêiner (ex: `sujaloja.com.br`). |
| `config.name`  | Nome do evento para exibição em dashboards e relatórios do Metrito.               |

## Exemplo Completo

Veja um exemplo de payload enviando dados de lead, informações de compra e encaminhamento para a Meta (Facebook), usando uma Chave de API no modo síncrono:

```bash theme={null}
curl -X POST "https://api.metrito.com/v3/tracking/events?sync=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mtk_live_SuaChaveAqui" \
  -d '{
    "container_id": "MTC-55AEW53Y",
    "config": {
      "name": "Purchase",
      "facebook": {
        "name": "Purchase",
        "trackCustom": false
      }
    },
    "data": {
      "value": 99.90,
      "currency": "BRL"
    },
    "lead": {
      "name": "João da Silva",
      "email": "joao@exemplo.com",
      "phone": "+5511999999999"
    },
    "utm": {
      "source_id": "120242075681610084",
      "utm_medium": "ctwa_ad"
    },
    "meta": {
      "url": "https://sujaloja.com.br/checkout"
    }
  }'
```

Resposta de sucesso (modo síncrono):

```json theme={null}
{
  "success": true,
  "event_id": "1758388123_kk78h7u5sf",
  "lead_id": "lead_20250920_xyz789",
  "lead_status": "created",
  "timestamp": 1758388123
}
```

<Info>
  O `eventId` e o `leadId` são gerados automaticamente quando não enviados no payload. O Metrito utiliza deduplicação e *upsert* de leads baseado em e-mail, telefone e documento para evitar registros duplicados.
</Info>

## config.name vs config.facebook.name

Esses dois campos têm finalidades distintas e é importante entender a diferença:

| Campo                  | Usado por                     | Descrição                                                                                                             |
| ---------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `config.name`          | **Metrito**                   | Nome interno do evento exibido nos dashboards do Metrito.                                                             |
| `config.facebook.name` | **Meta (Facebook/Instagram)** | Nome do evento enviado à API de Conversões da Meta. Deve seguir o padrão oficial (ex: `Purchase`, `Lead`, `Contact`). |

<Warning>
  Se o objeto `config.facebook` for omitido, o evento é registrado no Metrito mas **não** é enviado para a Meta. Se você deseja que a conversão seja atribuída no Meta Ads (CAPI), este bloco é obrigatório.
</Warning>

## Próximos Passos

<CardGroup cols={2}>
  <Card
    title="Integração com o CRM DataCrazy
"
    icon="plug"
    href="/tracking/datacrazy-crm"
  >
    Veja um tutorial prático de envio de eventos (incluindo Click to WhatsApp) a partir do CRM DataCrazy.
  </Card>

  <Card title="Testar a Integração" icon="bug" href="/tracking/testing">
    Verifique se os eventos estão sendo recebidos e processados corretamente.
  </Card>
</CardGroup>