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 a correspondência de usuário de cada destino. Quanto mais campos, melhor a nota de correspondência (EMQ) na Meta. Cada fonte aproveita um subconjunto diferente:

Fonte	Campos do lead usados na correspondência
Meta	`name`, `email`, `phone`, `gender`, `birth`, `city`, `state`, `country` e `postal`.
Google Ads	`email`, `phone` e endereço. O endereço só entra quando o lead tem nome e sobrenome, país e CEP (`postal`): o CEP é obrigatório para o Google.
TikTok Ads	Só `email`, `phone` e o ID externo do lead. O TikTok não aceita nome nem endereço.

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, o Google Ads e o TikTok Ads, 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": "Compra",
      "facebook": { "name": "Purchase", "trackCustom": false },
      "google": { "name": "Compra Metrito" },
      "tiktok": { "name": "CompletePayment" }
    },
    "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..name

O config tem um nome para o Metrito e um bloco por fonte de anúncio. Os três blocos têm a mesma forma, e em todos o identificador é name:

"config": {
  "name": "Cliente Quente",
  "facebook": { "name": "AddToWishlist" },
  "google":   { "name": "Cliente Quente" },
  "tiktok":   { "name": "AddToWishlist" }
}

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. Siga o padrão oficial (ex.: `Purchase`, `Lead`, `Contact`).
`config.google.name`	Google Ads	Nome da ação de conversão na conta do Google Ads. Se ainda não existir uma ação com esse nome, o Metrito cria.
`config.tiktok.name`	TikTok Ads	Nome do evento no TikTok: um evento padrão (ex.: `CompletePayment`, `SubmitForm`, `Contact`) ou um nome personalizado.

Bloco ausente = não envia para aquela fonte. Sem config.facebook, o evento é registrado no Metrito mas não vai para a Meta. O mesmo vale para config.google e config.tiktok. Para a conversão ser atribuída numa plataforma, o bloco dela é obrigatório e o contêiner precisa ter um destino ativo daquela fonte (veja Destinos e pixels).

A mesma conversão pode ter um nome diferente em cada fonte. Uma compra costuma ser Purchase na Meta e CompletePayment no TikTok, e no Google é o nome que você quer ver na coluna de conversões da conta.

Detalhes do `config.google.name`

A ação de conversão é criada automaticamente quando não existe na conta, do tipo importação de cliques, com 90 dias de janela de conversão após o clique. Mudar a janela depois, no Google Ads, só vale para cliques posteriores à mudança.
A busca pelo nome ignora maiúsculas e minúsculas: cliente quente reaproveita a ação Cliente Quente em vez de criar outra.
Renomear o evento no Metrito não renomeia a ação de conversão no Google. Um nome novo encontra ou cria outra ação, e a antiga para de receber conversões.
Uma ação criada agora pode levar alguns minutos até começar a aceitar conversões.

Detalhes do `config.tiktok.name`

Eventos personalizados servem para relatório e público, mas o TikTok não otimiza campanha por eles. Para otimizar, use um evento padrão.
Pageview não é um evento reportável pela API do TikTok.

O event_id do evento é o mesmo em todas as fontes. É ele que deduplica o evento do navegador com o do servidor na Meta e no TikTok, e que evita conversão repetida no Google.

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

IA

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..name

Detalhes do `config.google.name`

Detalhes do `config.tiktok.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..name

​Detalhes do config.google.name

​Detalhes do config.tiktok.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..name

Detalhes do `config.google.name`

Detalhes do `config.tiktok.name`

Próximos Passos