API de Eventos

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

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:

Modo Assíncrono (Padrão): O evento é enfileirado e processado em segundo plano. Não exige chave de API. Responde com sucesso quase imediatamente.
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):

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.

{
  "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.

Catálogo automático. Um config.name que ainda não existe no contêiner vira uma conversão com acionador API na página de Eventos, sem cadastro prévio, e passa a estar disponível como coluna na tabela de campanhas e como métrica no dashboard. Se o payload trouxer config.facebook.name, é esse nome que identifica o evento no Metrito.

Campos Opcionais Relevantes

`sourceKey` — a fonte do evento

Define como o evento aparece na coluna Fonte do histórico do lead. Eventos enviados por esta API são rotulados como API por padrão.

Valor	Quando usar
`api`	Padrão. Integrações de CRM, backend, automações.
`whatsapp`	O evento nasceu numa conversa de WhatsApp e você quer agrupá-lo como tal.
`website`	O evento representa uma ação no site.

Valores fora dessa lista são ignorados e o evento volta para api.

{
  "container_id": "MTC-55AEW53Y",
  "sourceKey": "whatsapp",
  "config": { "name": "QualifiedLead" }
}

`config.facebook.sourceKey` — o action_source da Meta

Campo diferente do anterior, apesar do nome parecido: este governa o action_source enviado à API de Conversões da Meta, não o rótulo de fonte no Metrito. Use "business_messaging" quando o evento pertencer a uma conversa de WhatsApp (Click to WhatsApp). Com ele, a Meta recebe o evento como mensagem — e não como evento de site — e a atribuição usa o dataset de WhatsApp.

{
  "config": {
    "name": "QualifiedLead",
    "facebook": { "name": "Lead", "sourceKey": "business_messaging" }
  }
}

O marcador só tem efeito se o contêiner tiver um pixel de WhatsApp vinculado. Sem esse dataset, o evento continua saindo como website.

Campos do `lead`

Todos opcionais. Além de identificar o lead (dedupe/upsert por e-mail, telefone e documento), esses campos alimentam o advanced matching da Meta — quanto mais campos, melhor a nota de correspondência (EMQ).

Campo	Descrição
`id`	ID do lead no Metrito (`lead_...`), quando você já o tem.
`name`	Nome completo.
`email`	E-mail.
`phone`	Telefone (E.164 de preferência).
`doc`	Documento (CPF/CNPJ).
`gender`	`m` ou `f`.
`birth`	Data de nascimento — `YYYY-MM-DD`, `DD/MM/YYYY` ou `YYYYMMDD`.
`address`	Endereço (rua/logradouro).
`city` / `state` / `country` / `postal`	Localização. Merge por campo com a geolocalização por IP: o que você mandar vence, o resto é preenchido automaticamente.

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:

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",
      "doc": "12345678900",
      "birth": "10/05/1990",
      "city": "Florianópolis",
      "state": "SC",
      "country": "BR",
      "postal": "88000-000"
    },
    "utm": {
      "source_id": "120242075681610084",
      "utm_medium": "ctwa_ad"
    },
    "meta": {
      "url": "https://sujaloja.com.br/checkout"
    }
  }'

Resposta de sucesso (modo síncrono):

{
  "success": true,
  "event_id": "1758388123_kk78h7u5sf",
  "lead_id": "lead_20250920_xyz789",
  "lead_status": "created",
  "timestamp": 1758388123
}

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.

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`).

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.

Próximos Passos

Integração com o CRM DataCrazy

Veja um tutorial prático de envio de eventos (incluindo Click to WhatsApp) a partir do CRM DataCrazy.

Testar a Integração

Verifique se os eventos estão sendo recebidos e processados corretamente.

Primeiros Passos

Conceitos Fundamentais

Dashboard

Análise de Dados

Integrações

Rastreamento

Endpoint

Autenticação e Sincronismo

Campos Obrigatórios

Campos Opcionais Relevantes

`sourceKey` — a fonte do evento

`config.facebook.sourceKey` — o action_source da Meta

Campos do `lead`

Exemplo Completo

config.name vs config.facebook.name

Próximos Passos

Integração com o CRM DataCrazy

Testar a Integração

​Endpoint

​Autenticação e Sincronismo

​Campos Obrigatórios

​Campos Opcionais Relevantes

​sourceKey — a fonte do evento

​config.facebook.sourceKey — o action_source da Meta

​Campos do lead

​Exemplo Completo

​config.name vs config.facebook.name

​Próximos Passos

Integração com o CRM DataCrazy

Testar a Integração

Endpoint

Autenticação e Sincronismo

Campos Obrigatórios

Campos Opcionais Relevantes

`sourceKey` — a fonte do evento

`config.facebook.sourceKey` — o action_source da Meta

Campos do `lead`

Exemplo Completo

config.name vs config.facebook.name

Próximos Passos