Entrar Começar grátis
/
📦 Containers

Eventos e Parâmetros — Referência

Lista canônica de eventos suportados pelo Track Combo e parâmetros aceitos em cada um

Atualizado em 20 de mai. de 2026 Leitura de 5 min

Lista canônica de eventos suportados pelo Track Combo e parâmetros aceitos em cada um. Esta é a fonte da verdade — todos os outros artigos (integrações, pixels, webhook custom, disparo via JavaScript) referenciam esta página.

Use sempre estes nomes em minúsculo (snake_case). A tag/servidor converte automaticamente para o nome de cada plataforma (Facebook, GA4, TikTok, Pinterest, Taboola). Não use nomes do Facebook como Purchase ou InitiateCheckout — eles não funcionam.

Campos no nível raiz do payload

Além do nome do evento e dos blocos aninhados (user_data, tracking, custom_data, items), o payload aceita:

Campo Tipo Obrigatório Descrição
event string Sim Nome canônico do evento (ver tabela abaixo)
event_id string Não ID único para deduplicação entre Web e server-side (CAPI). Gerado automaticamente pela tag web se omitido. Em webhooks server-side, use o ID da transação/lead para garantir idempotência (mesma compra disparada 2x não duplica)

Sobre event_id: é o que evita que o Facebook conte uma mesma venda duas vezes quando você dispara o purchase pelo navegador e pelo webhook server-side. Se ambos os disparos enviam o mesmo event_id, o Facebook deduplica automaticamente. Boa prática: usar o transaction_id/order_id da venda como event_id.

Eventos canônicos

Evento Quando disparar Campos recomendados
page_view Carregamento de página. Disparado automaticamente pela tag web — não dispare manualmente —
view_item_list Visualização de listagem de produtos / categoria items
view_item Visualização de página de produto items, value, currency
search Usuário fez uma busca interna search_term
add_to_cart Produto adicionado ao carrinho items, value, currency
initiate_checkout Início do processo de checkout items, value, currency
add_payment_info Dados de pagamento preenchidos items, value, currency, payment_type
add_shipping_info Endereço/frete preenchido items, value, currency
purchase Compra finalizada (página de obrigado ou webhook do gateway) transaction_id, items, value, currency, user_data
lead Cadastro / captura de lead / formulário enviado user_data

user_data — identificação do usuário

Identifica quem disparou o evento. Quanto mais campos enviar, melhor a qualidade do match no Facebook CAPI, Google Enhanced Conversions e demais APIs server-side. Email, telefone e doc são hasheados em SHA-256 no servidor — envie em texto puro.

Campo Tipo Exemplo Descrição
email string cliente@exemplo.com Email do usuário
phone string 5511999999999 Telefone com DDI+DDD+número, apenas dígitos
name string João Silva Nome completo (alternativa a first_name + last_name)
first_name string João Primeiro nome
last_name string Silva Sobrenome
address string Av. Paulista, 1000 Endereço (logradouro + número)
city string São Paulo Cidade
state string SP UF (2 letras)
zipcode string 01310-100 CEP / código postal
country string BR País (ISO-2)
doc string 12345678900 Documento universal — CPF, CNPJ, passaporte, tax ID, SSN. Alfanumérico, hasheado em SHA-256
user_id string 12345 ID interno do cliente no seu sistema (external_id no Facebook)
user_ip string 200.123.45.67 IP do usuário. Capturado automaticamente pela tag web; preencha apenas em disparos server-side
user_agent string Mozilla/5.0... User-Agent do navegador. Capturado automaticamente pela tag web; preencha apenas em disparos server-side
gender string m ou f Gênero (uma letra minúscula)
birthday string 19900131 Data de nascimento no formato YYYYMMDD

Sobre doc: sempre use o nome doc, nunca cpf, cnpj, document ou doc_number. É o campo universal — o Track Combo opera internacionalmente, então o mesmo campo aceita qualquer tipo de identificador. O valor é hasheado em SHA-256 no servidor (irreversível) e usado apenas para atribuição/matching, nunca exibido como PII.

tracking — origem do tráfego

Normalmente a tag web preenche sozinha lendo cookies e URL. Só passe esses campos se quiser sobrescrever ou se estiver enviando o evento via servidor (webhook) — nesse caso, recupere os valores dos cookies (no checkout) e propague junto com o evento de purchase.

UTM (origem da campanha)

Campo Tipo Descrição
utm_source string Origem da campanha
utm_medium string Meio (cpc, organic, email…)
utm_campaign string Nome da campanha
utm_term string Palavra-chave
utm_content string Variação de criativo

Facebook / Meta

Campo Tipo Cookie/Param Descrição
fbc string _fbc Click ID do Facebook — essencial para o CAPI casar com o evento web
fbp string _fbp Browser ID do Facebook
Campo Tipo Cookie/Param Descrição
gclid string ?gclid= Click ID do Google Ads (campanhas Search/Display)
gbraid string ?gbraid= Click ID Google Ads para tráfego iOS (app-to-web)
wbraid string ?wbraid= Click ID Google Ads para web-to-app
gcl_au string _gcl_au Cookie first-party do Google Ads (Enhanced Conversions)
ga string _ga Client ID do Google Analytics

TikTok Ads

Campo Tipo Cookie/Param Descrição
ttclid string ?ttclid= Click ID do TikTok Ads — essencial para o Events API casar com o anúncio
ttp string _ttp Cookie do TikTok pixel

Pinterest

Campo Tipo Cookie/Param Descrição
epik string _epik Click ID do Pinterest

Taboola

Campo Tipo Cookie/Param Descrição
tbclid string ?tbclid= Click ID do Taboola

Track Combo (atribuição interna)

Campo Tipo Descrição
tc_code string Código de atribuição interno do Track Combo (formato tc_XXXXXXXX). Em webhooks server-side, pode ser inserido em qualquer campo do payload — o servidor procura pelo padrão tc_ + 8 dígitos no JSON inteiro
src string Parâmetro de atribuição alternativo (compatível com tracking estilo Hotmart ?src=)
sck string Sub-código de atribuição (compatível com tracking estilo Hotmart ?sck=)

custom_data — dados do evento

Campos com informações específicas do evento. Em disparos via JavaScript, esses campos vão no nível raiz do objeto (não dentro de custom_data:); em webhooks server-side, dentro de data.custom_data.

Campo Tipo Descrição
value number Valor monetário do evento. Deve ser número, não string (197.00, não "R$ 197,00")
currency string Moeda em ISO-4217. Default: BRL quando value é informado
items array Produtos envolvidos. Ver schema "items[]" abaixo
content_ids array IDs dos produtos. Gerado automaticamente a partir de items[].item_id
quantity number Quantidade total. Gerada automaticamente a partir de items[].quantity
transaction_id string ID único da venda. Obrigatório no purchase
order_id string Alias de transaction_id
search_term string Termo buscado. Use no search
payment_type string credit_card, pix, boleto etc

items[] — produtos

Array de produtos relacionados ao evento. Usado em view_item, add_to_cart, initiate_checkout, purchase etc.

Campo Tipo Descrição
item_id string SKU/ID do produto. Obrigatório — itens sem ID são descartados
item_name string Nome do produto
item_category string Categoria
price number Preço unitário
quantity number Quantidade

Aliases aceitos (a tag normaliza automaticamente): id → item_id, name → item_name, category → item_category.

Onde os parâmetros vão no payload

Dependendo de onde o evento é disparado, a estrutura muda:

Via JavaScript (window.tcData.executeEvent) — campos de custom_data ficam no nível raiz junto com event/event_id:

{
  event: 'purchase',
  event_id: 'PEDIDO-1',
  user_data: { email: '...', doc: '...' },
  tracking: { utm_source: '...' },
  transaction_id: 'PEDIDO-1',
  value: 197.00,
  currency: 'BRL',
  items: [/* ... */]
}

Via Webhook Custom (server-side) — tudo aninhado dentro de data. Em disparos server-side é importante incluir user_ip e user_agent, que normalmente seriam capturados pela tag web:

{
  "event": "purchase",
  "event_id": "PEDIDO-1",
  "data": {
    "user_data": {
      "email": "cliente@exemplo.com",
      "phone": "5511999999999",
      "doc": "12345678900",
      "name": "João Silva",
      "first_name": "João",
      "last_name": "Silva",
      "address": "Av. Paulista, 1000",
      "city": "São Paulo",
      "state": "SP",
      "zipcode": "01310-100",
      "country": "BR",
      "gender": "m",
      "birthday": "19900131",
      "user_id": "12345",
      "user_ip": "200.123.45.67",
      "user_agent": "Mozilla/5.0 (...)"
    },
    "tracking": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday",
      "utm_term": "curso-x",
      "utm_content": "criativo-a",
      "fbc": "fb.1.1700000000000.IwAR0...",
      "fbp": "fb.1.1700000000000.987654321",
      "gclid": "Cj0KCQjw...",
      "gcl_au": "1.1.123456789.1700000000",
      "ga": "GA1.2.123456789.1700000000",
      "ttclid": "E.C.P_xxxxx",
      "ttp": "01HABCDEF...",
      "epik": "dj0yJnU9...",
      "tbclid": "GiC0ABC123...",
      "tc_code": "tc_12345678",
      "src": "afiliado-x",
      "sck": "campanha-y"
    },
    "custom_data": {
      "transaction_id": "PEDIDO-1",
      "order_id": "PEDIDO-1",
      "value": 197.00,
      "currency": "BRL",
      "payment_type": "pix",
      "items": [
        {
          "item_id": "SKU-123",
          "item_name": "Curso X",
          "item_category": "cursos",
          "price": 197.00,
          "quantity": 1
        }
      ]
    }
  }
}

Ver também

eventosparâmetrosreferênciauser_datacustom_dataitemstrackingpurchaseleadadd_to_cartinitiate_checkoutdocsnake_case

Artigos relacionados