Compra da Hotmart no LinkedIn Ads via Server-Side (Conversions API)

Por que fazer isso pelo servidor

O checkout da Hotmart não aceita a Insight Tag do LinkedIn. Sem rastreamento server-side, a compra simplesmente não aparece no Campaign Manager e o algoritmo otimiza no escuro. A solução é receber o webhook de compra aprovada da Hotmart no seu GTM Server e repassar o evento para a Conversions API do LinkedIn.

Para casar a compra com o clique no anúncio usamos dois identificadores:

• li_fat_id: o click ID do LinkedIn (o mais importante).
• E-mail do comprador (com hash SHA-256): o LinkedIn casa melhor com e-mail corporativo; em públicos B2C com muito Gmail, a correspondência só por e-mail tende a ser menor.

Entendendo o li_fat_id

O li_fat_id é o click ID do LinkedIn, o equivalente ao gclid do Google e ao fbclid da Meta. Quem gera esse ID é o próprio LinkedIn, no momento em que a pessoa clica no anúncio. Não é o seu site nem o seu servidor.

Onde ele aparece:

• Na URL do clique: com o enhanced conversion tracking (rastreamento de conversões aprimorado) da Insight Tag, o LinkedIn anexa o ID na URL de destino, por exemplo suaLP.com.br/?li_fat_id=a1b2c3... Segundo a documentação do LinkedIn, ele já vem ativado por padrão nas Insight Tags criadas recentemente.
• Num cookie primário: a Insight Tag grava o valor no cookie li_fat_id, no domínio da sua landing page. O cookie dura 30 dias a partir do último clique, mas o LinkedIn guarda a ligação do ID com o perfil por 365 dias, então ele ainda serve na Conversions API depois que o cookie expira.

Por que ele nasce no lado web: só o navegador vê a URL do clique. O seu servidor não recebe nada do LinkedIn nesse momento. Por isso a captura sempre começa no GTM Web.

Por que a Hotmart não traz o ID sozinha: o webhook só conhece os dados do checkout (comprador, valor, transação). O checkout fica em outro domínio (pay.hotmart.com) e não consegue ler os cookies da sua landing page.

Como o ID chega ao servidor:

1. Landing page (web): o GTM lê o li_fat_id da URL (ou do cookie) e guarda no cookie _li_fat_id.
2. Link do checkout: o mesmo script coloca o valor no parâmetro xcod do link da Hotmart.
3. Hotmart: guarda o xcod junto com a venda e devolve no webhook em data.purchase.origin.xcod.
4. Servidor: a tag do GTM Server lê o xcod e envia ao LinkedIn como LinkedIn First Party Ads Tracking UUID.

Quando o ID não chega:

• A pessoa não veio de um anúncio (orgânico, direto, outro canal).
• O enhanced conversion tracking está desligado (pode acontecer em Insight Tags antigas).
• O link do checkout não passou pelo script (botão criado depois, iframe, link encurtado ou checkout montado por formulário).
• A pessoa comprou dias depois, em outro aparelho.

Nesses casos o evento ainda vai com o e-mail com hash, e o LinkedIn tenta casar só por ele.

Arquitetura

O que você precisa antes de começar

• Conta no LinkedIn Campaign Manager com a Insight Tag instalada na landing page.
• GTM Server-Side rodando (ex.: Stape) com o Data Client ativo.
• Acesso de produtor na Hotmart para cadastrar webhooks.
• Acesso de administrador à conta de anúncios, para gerar o token da Conversions API no próprio Campaign Manager.

Passo 1

Criar a conversão no Campaign Manager

1. Em Account Assets > Insight Tag, confirme que a tag está ativa no domínio da landing page.
2. Confira o enhanced conversion tracking (rastreamento de conversões aprimorado), que faz o LinkedIn anexar o li_fat_id na URL do clique. Ele vem ativado por padrão nas Insight Tags criadas recentemente. Se a sua tag é antiga, ative nas configurações da Insight Tag. Para testar, clique num anúncio seu e veja se a URL da landing page chega com ?li_fat_id=.
3. Em Medir > Conversões, crie uma nova conversão com método "Conversions API", categoria Compra (Purchase), valor dinâmico e a janela de atribuição que faz sentido para o seu produto.
4. Anote o ID da conversão. Ele vai para a variável de ID da conversão no GTM Server.

Passo 2

Gerar o token de acesso (pelo Campaign Manager)

O caminho mais simples é gerar o token direto no Campaign Manager. Não precisa criar app no LinkedIn Developers nem pedir acesso à Conversions API.

1. No menu da conta de anúncios, abra Dados > Gerente de sinais (Signals Manager).
2. Clique em Direct API e depois em Generate access token.
3. Entre com a sua conta do LinkedIn e siga as instruções.
4. Quando o token aparecer, clique nele para copiar e cole na variável constante do token no GTM Server.

Passo 3

Capturar o li_fat_id na landing page (GTM Web)

O li_fat_id chega na URL do clique. Precisamos guardá-lo e repassá-lo para o checkout da Hotmart no parâmetro xcod, que a Hotmart devolve no webhook em data.purchase.origin.xcod.

No GTM Web, monte 4 peças:

1. Tag Insight Tag (base): modelo "LinkedIn InsightTag 2.0" da galeria, com o seu Partner ID (Campaign Manager > Gerente de sinais > Insight Tag), disparando em All Pages. É ela que grava o cookie li_fat_id no seu domínio.
2. Variável 02.05 li_fat_id: tipo URL, componente Consulta, chave li_fat_id.
3. Variável 01.09 li_fat_id: tipo Cookie primário, nome _li_fat_id.
4. Tag HTML personalizada disparando em All Pages, com o script abaixo. Ele grava o cookie _li_fat_id por 90 dias e coloca o valor no xcod dos links da Hotmart.

<script>
(function () {
  var params = new URLSearchParams(location.search);
  var fromUrl = params.get('li_fat_id');
  if (fromUrl) {
    document.cookie = '_li_fat_id=' + encodeURIComponent(fromUrl) +
      ';path=/;max-age=' + 60 * 60 * 24 * 90 + ';SameSite=Lax';
  }
  var match = document.cookie.match(/(?:^|; )_li_fat_id=([^;]+)/);
  var liFatId = fromUrl || (match && decodeURIComponent(match[1]));
  if (!liFatId) return;
  document.querySelectorAll('a[href*="pay.hotmart.com"]').forEach(function (a) {
    var u = new URL(a.href);
    u.searchParams.set('xcod', liFatId);
    a.href = u.toString();
  });
})();
</script>

Passo 4

Cadastrar o webhook na Hotmart

1. Na Hotmart, vá em Ferramentas > Webhook (API e notificações) e crie uma nova configuração na versão 2.0.0.
2. Evento: Compra aprovada.
3. URL: o endpoint do seu GTM Server com um caminho exclusivo, por exemplo https://SEU-SERVER/linkedin-ads-compra
4. Copie o hottok exibido pela Hotmart. Ele será usado como trava de segurança no acionador.

O Data Client da Stape recebe o JSON do webhook e transforma tudo em dados do evento. Os campos ficam aninhados, então usamos o caminho completo (ex.: data.buyer.email).

Passo 5

Criar as variáveis no GTM Server

Constantes:

• 1.08 LinkedIn Token — access token gerado no Passo 2.
• 1.09 LinkedIn Conversion ID — ID da conversão criada no Passo 1.

Dados do evento (caminho da chave):

• 6.01 Hotmart email → data.buyer.email
• 6.02 Hotmart transaction → data.purchase.transaction
• 6.03 Hotmart value → data.purchase.price.value
• 6.04 Hotmart currency → data.purchase.price.currency_value
• 6.07 Hotmart approved_date → data.purchase.approved_date
• 6.08 Hotmart xcod (li_fat_id) → data.purchase.origin.xcod
• 6.09 Hotmart first_name → data.buyer.first_name
• 6.10 Hotmart last_name → data.buyer.last_name
• 6.11 Hotmart event → event

Cabeçalho da solicitação:

• 2.10 x-hotmart-hottok → cabeçalho X-HOTMART-HOTTOK

Confira cada caminho no modo Visualizar do GTM Server com um webhook de teste antes de publicar.

Passo 6

Criar o acionador com 3 travas

Tipo: Evento personalizado, nome do evento .* (regex), disparando em alguns eventos quando TODAS as condições forem verdadeiras:

1. Request Path é igual a /linkedin-ads-compra
2. 2.10 x-hotmart-hottok é igual ao hottok da sua conta (segurança: sem ele, qualquer pessoa que descobrisse a URL poderia enviar uma "compra")
3. 6.11 Hotmart event é igual a PURCHASE_APPROVED (impede que boleto gerado, reembolso e outros eventos virem conversão)

Passo 7

Configurar a tag LinkedIn Conversion API (Stape)

Na Galeria de modelos da comunidade, adicione o modelo "LinkedIn Conversion API" da stape-io e configure:

• Event Type: Conversion
• Access Token: {{1.08 LinkedIn Token}}
• Conversion ID: {{1.09 LinkedIn Conversion ID}}
• Event Data: Conversion Happened At = {{6.07 Hotmart approved_date}}; Amount = {{6.03 Hotmart value}}; Currency = {{6.04 Hotmart currency}}; Event ID = {{6.02 Hotmart transaction}}
• User IDs: Email = {{6.01 Hotmart email}} (a tag aplica o hash automaticamente); LinkedIn First Party Ads Tracking UUID = {{6.08 Hotmart xcod (li_fat_id)}}
• User Info: First Name = {{6.09 Hotmart first_name}}; Last Name = {{6.10 Hotmart last_name}}
• Acionador: o criado no Passo 6.

O Event ID usa o número da transação da Hotmart. Assim, se a Hotmart reenviar o mesmo webhook, o LinkedIn não conta a compra duas vezes.

Passo 8

Testar e validar

1. Abra o modo Visualizar do GTM Server.
2. Na Hotmart, envie um teste do webhook (ou faça uma compra de teste) e veja a requisição chegar no path /linkedin-ads-compra.
3. Confira se as variáveis 6.xx estão preenchidas e se a tag disparou.
4. Uma resposta 201 do LinkedIn significa sucesso.
5. No Campaign Manager, a conversão passa para o status ativo. Isso pode levar algumas horas.
6. Só então publique o contêiner.

Erros mais comuns

• Token errado ou trocado: se você gerar um token novo, substitua na constante do GTM Server e publique o contêiner. Tokens de app próprio no LinkedIn Developers expiram e precisam ser renovados.
• Data em formato errado: conversionHappenedAt precisa estar em milissegundos e dentro de 90 dias.
• Disparar em qualquer evento da Hotmart: sem a trava PURCHASE_APPROVED, boleto impresso vira compra.
• xcod vazio: o link do checkout não recebeu o li_fat_id (link criado depois do script, botão em iframe, ou usuário que não veio do anúncio).
• Esperar remover reembolsos: a Conversions API não apaga conversões já enviadas.