TikTok Events API: o guia técnico para enviar conversões server-side

Quem investe em tráfego no TikTok e mede conversão apenas pelo pixel do navegador está operando com um instrumento que perde parte do sinal por natureza. Bloqueadores, restrições de navegador, falhas de rede e a simples ausência do JavaScript em determinadas condições fazem uma fatia dos disparos nunca chegar ao destino. A Events API do TikTok é a resposta a esse problema: um canal para enviar eventos direto do seu servidor para o TikTok, em paralelo ou em complemento ao pixel, com muito mais resiliência.

Quem já conhece a Conversions API da Meta vai reconhecer a estrutura — o conceito é o mesmo, muda o vocabulário e alguns detalhes de payload. Este guia percorre a anatomia da Events API do TikTok de forma prática: o que enviar, como identificar o usuário, como não contar a mesma conversão duas vezes e como validar antes de ligar em produção.

Por que enviar eventos server-side#

A promessa da Events API é paridade e resiliência. Paridade significa registrar os mesmos eventos que o pixel registraria — visualização de conteúdo, adição ao carrinho, compra —, mas por um caminho que você controla. Resiliência significa que a chamada sai da sua infraestrutura direto para a API do TikTok, sem depender do navegador do usuário para a transmissão final, o que a torna imune a extensões que bloqueiam scripts e a perdas de rede do lado do cliente.

Há ainda um ganho de qualidade de dados. Do servidor, você tem acesso a informações confiáveis que o navegador pode não ter no momento do disparo — o valor exato de um pedido confirmado pelo back-end, o e-mail do cliente logado, o identificador interno da transação. Isso alimenta uma correspondência melhor e uma atribuição mais fiel.

Anatomia do payload#

Um evento enviado à Events API é um objeto estruturado. Os campos principais organizam-se em três grandes blocos: a identificação do evento, o contexto do usuário e as propriedades da conversão.

``json { "event": "CompletePayment", "event_time": 1718900000, "event_id": "ord_8f3a91c2", "context": { "user": { "email": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514", "phone": "e2b1f6...", "ttclid": "E.C.P...", "ttp": "aBcD1234..." }, "page": { "url": "https://loja.exemplo.com/checkout/sucesso" }, "ip": "203.0.113.10", "user_agent": "Mozilla/5.0 ..." }, "properties": { "currency": "BRL", "value": 259.90, "contents": [ { "content_id": "SKU-1029", "quantity": 1, "price": 259.90 } ] } } ``

Vale destacar cada peça:

• event — o nome do evento. O TikTok tem um conjunto de eventos padrão que a plataforma reconhece e otimiza melhor; usar os nomes canônicos é preferível a inventar nomes próprios.
• event_time — o instante da ação, em timestamp. Deve refletir o momento em que a conversão aconteceu, não o momento do envio, sobretudo quando o evento passa por uma fila.
• event_id — o identificador único da ocorrência, peça central da deduplicação contra o pixel.
• context.user — os sinais de identidade (detalhados adiante).
• context.page, ip, user_agent — contexto que reforça a correspondência.
• properties — os dados da conversão: value, currency, contents, quantidade, preço por item.

Correspondência avançada#

A correspondência avançada (advanced matching) é o que permite ao TikTok associar o evento a uma pessoa. Quanto mais sinais válidos e bem normalizados você envia, maior a probabilidade de a plataforma encontrar o usuário correspondente — e maior a qualidade da otimização.

Dados pessoais hasheados#

E-mail e telefone são os sinais mais fortes, mas nunca trafegam em texto puro. Você os normaliza (minúsculas e sem espaços no e-mail; formato internacional com código de país no telefone) e os hasheia em SHA-256 antes de colocá-los no payload. A normalização prévia é obrigatória: sem ela, o mesmo e-mail gera hashes diferentes e a correspondência falha silenciosamente.

Identificadores do TikTok#

Dois identificadores são específicos do ecossistema:

• ttclid (TikTok Click ID) — anexado à URL de destino quando alguém clica no anúncio. Capturá-lo no primeiro acesso e persistí-lo é decisivo para religar a conversão ao clique original.
• ttp — um cookie de primeira parte gerado pelo pixel do TikTok, que funciona como âncora de correspondência de navegador quando e-mail ou telefone não estão disponíveis.

Enviar ttclid e ttp junto com os dados hasheados dá à plataforma múltiplos caminhos de correspondência, elevando a taxa de acerto.

Autenticação server-side#

A chamada à Events API é autenticada por um Access Token emitido para a sua fonte de dados. Esse token é um segredo: vive exclusivamente no servidor, nunca no bundle do navegador nem em variável exposta ao cliente. Vazá-lo permitiria que terceiros enviassem eventos falsos em nome da sua conta, poluindo dados e otimização. Trate-o com o mesmo rigor de qualquer credencial de produção — em um cofre de segredos, injetado por variável de ambiente, rotacionável.

Deduplicação com o pixel#

A arquitetura recomendada é híbrida: o pixel dispara no navegador para cobertura imediata, e a Events API dispara do servidor para resiliência. Mas você não quer que a mesma compra seja contada duas vezes.

A solução é o event_id. Você atribui o mesmo identificador único à ocorrência tanto no disparo do pixel quanto no disparo server-side. Ao receber os dois, o TikTok reconhece que se referem à mesma conversão e conta apenas uma vez. Sem um event_id consistente entre os dois canais, a deduplicação não acontece e você infla os números.

A regra prática: gere o event_id num ponto único da verdade — o identificador do pedido, por exemplo — e propague-o para os dois caminhos. Nunca gere identificadores independentes em cada canal, porque aí eles nunca vão coincidir.

Eventos padrão#

O TikTok reconhece um conjunto de eventos padrão que representam etapas típicas do funil. Os mais usados em e-commerce e geração de leads:

• ViewContent — visualização de um produto ou conteúdo relevante.
• AddToCart — adição de item ao carrinho.
• InitiateCheckout — início do checkout.
• CompletePayment — pagamento concluído, o evento de conversão por excelência.
• CompleteRegistration / SubmitForm — cadastro ou envio de formulário, comuns em geração de leads.

Usar os nomes padrão importa porque a plataforma sabe otimizar para eles e os relaciona corretamente aos objetivos de campanha. Nomes customizados funcionam, mas ficam de fora de boa parte da inteligência de otimização.

Test Events e validação#

Antes de ligar a integração de verdade, você a valida com um Test Event Code — um código temporário incluído no payload que faz os eventos aparecerem em uma aba de testes, em tempo real, sem contaminar os dados de produção. É a ferramenta primária para confirmar que o payload está correto: nome do evento certo, parâmetros obrigatórios presentes, value e currency bem preenchidos, dados de usuário hasheados e a deduplicação funcionando.

O fluxo de validação: dispare uma conversão real de teste, confirme que ela aparece na aba de testes com todos os campos, verifique que o par pixel + servidor é reconhecido como um único evento e não como dois, e só então remova o código de teste e ligue em produção. Esquecer de remover o test code é um erro comum que mantém eventos legítimos fora da contagem de produção.

Boas práticas de confiabilidade#

Dois cuidados operacionais sustentam a integração no longo prazo. O primeiro é a normalização consistente de todos os campos de identidade — um pipeline único que trata e-mail e telefone da mesma forma toda vez, para que os hashes sejam estáveis. O segundo é uma fila com retry: eventos que falham na primeira tentativa (por indisponibilidade momentânea da API) devem ir para uma fila persistente e ser reenviados, sempre com o mesmo event_id para garantir idempotência. Assim, uma queda temporária da API vira atraso, não perda de conversão.

Onde rodar o envio e como lidar com volume#

A chamada à Events API sai da sua infraestrutura, e isso levanta duas questões práticas de operação. A primeira é onde disparar. Eventos de site (visualização, carrinho) podem ser encaminhados a partir de um endpoint próprio que o navegador aciona, mas os eventos que mais importam — pagamento confirmado — devem sair do back-end que tem a verdade da transação, tipicamente no momento em que o pedido é aprovado. Assim você usa o valor exato e evita depender do navegador para a conversão principal.

A segunda questão é volume. Uma operação com muitos eventos por segundo não deve disparar uma requisição HTTP síncrona por conversão no caminho crítico do checkout — isso acopla a latência do checkout à disponibilidade da API do TikTok, o que é frágil. O padrão robusto é desacoplar: a conversão vira um registro numa fila persistente, e um processo separado consome a fila e envia à API, agrupando eventos quando a API aceita lotes. Se a API estiver momentaneamente indisponível, a fila segura os eventos e o processo reenvia — sem travar o checkout nem perder conversão.

Mapeamento consistente#

Como acontece com qualquer destino, o que evita retrabalho é ter um contrato de evento interno — um formato canônico que a sua aplicação produz — e uma função de tradução que o converte para o formato da Events API. Quando você adiciona um novo evento ou um novo campo, mexe num lugar só. E quando precisa validar por que uma conversão não apareceu, sabe exatamente onde a tradução acontece.

Diferenças em relação à Meta CAPI#

Para quem já implementou a Conversions API da Meta, o mapa mental transfere quase inteiro, com traduções de vocabulário: onde a Meta usa user_data, o TikTok usa context.user; onde a Meta usa custom_data, o TikTok usa properties; o fbclid/fbc da Meta corresponde ao ttclid/ttp do TikTok; e o event_name da Meta é o event do TikTok. A lógica de hashing SHA-256, de event_id para deduplicação, de Access Token server-side e de Test Events é a mesma em espírito. A diferença está nos nomes de campo e nos identificadores próprios de cada plataforma — o que reforça o valor de ter uma camada de conversão que fala um contrato interno único e traduz por destino.

Síntese#

A Events API do TikTok é o caminho para medir conversão com resiliência no TikTok: eventos enviados do servidor, com correspondência avançada por e-mail e telefone hasheados mais ttclid e ttp, autenticados por um Access Token que nunca sai do back-end, e deduplicados contra o pixel por um event_id compartilhado. Combine o envio server-side com o pixel numa arquitetura híbrida, valide tudo pelo Test Event Code antes de ligar, normalize a identidade de forma consistente e proteja o envio com uma fila que reenvia falhas sem duplicar. Feito assim, o TikTok deixa de perder a fatia de conversão que o pixel sozinho não conseguia capturar.