Le guide du développeur pour le suivi des affiliés côté serveur

Resumo rápido: O rastreamento de afiliados do lado do servidor substitui os pixels dependentes do navegador por chamadas diretas de API a partir do seu backend, capturando cada conversão independentemente de bloqueadores de anúncios, configurações de privacidade do iOS ou restrições de cookies.

• O rastreamento S2S armazena um ID de clique no servidor e envia um postback para o Tapfiliate quando ocorre uma conversão
• A API REST do Tapfiliate gerencia isso com duas chamadas principais: POST /clicks/ na chegada, POST /conversions/ na compra
• A parte mais complexa não é a chamada da API, mas o armazenamento correto do ID de clique no primeiro carregamento da página do usuário
• Uma vez em produção, as conversões atribuídas aumentam de 60–70% (pixel, mobile) para uma precisão quase total

Seu painel de afiliados mostra 847 conversões este mês. Seu sistema de gerenciamento de pedidos mostra 1.203.

A diferença representa 356 vendas que seu programa de afiliados não conseguiu atribuir. Isso equivale a 356 comissões calculadas com base em estimativas, ou 356 vendas geradas por afiliados que não foram recompensados porque um pixel não foi acionado.

Em ambos os casos, alguém perde dinheiro. Quando a equipe de marketing pergunta por que os números não correspondem, a resposta é sempre a mesma: “o pixel”.

Este guia explica por que os pixels falham, como o rastreamento do lado do servidor resolve o problema na arquitetura e como implementá-lo com a API REST do Tapfiliate usando um código funcional.

No final, a discrepância entre seu número de pedidos e suas conversões atribuídas será eliminada definitivamente.

Por que os pixels falham (e por que os desenvolvedores são culpados)

Os três modos de falha do rastreamento do lado do cliente

Um pixel de rastreamento é acionado a partir do navegador do comprador quando ele chega à sua página de confirmação. Na prática, ele falha de três maneiras distintas e previsíveis.

Bloqueadores de anúncios. Extensões como uBlock Origin e Privacy Badger bloqueiam scripts de rastreamento por padrão. A adoção de bloqueadores de anúncios ultrapassou 40% em desktops em 2025 e continua crescendo.

iOS e Safari ITP. A prevenção inteligente de rastreamento da Apple limita a vida útil dos cookies de terceiros a 24 horas após a última interação do usuário com o rastreador. Um comprador que clica em um link afiliado na segunda-feira e converte na quarta-feira não terá um cookie rastreável. O pixel é acionado, mas não há nada para ler.

Abandono da página antes do carregamento. Em conexões móveis lentas, páginas de confirmação pesadas em JavaScript podem levar de três a cinco segundos para carregar completamente. Compradores rápidos fecham a aba. O script do pixel nunca é executado.

O custo real da lacuna de atribuição

A diferença entre as conversões rastreadas por pixel e os pedidos reais pode chegar a 30–40% em um tráfego majoritariamente móvel quando se somam expiração de cookies ITP, bloqueadores de anúncios e abandono de página.

Em um programa que paga uma comissão média de US$ 20 para 1.000 conversões mensais, essa lacuna representa US$ 6.000–8.000 em comissões mal atribuídas. Os afiliados recebem crédito por vendas que não geraram ou não recebem crédito pelas que geraram. Nenhum desses cenários é viável.

O rastreamento do lado do servidor elimina totalmente a dependência do navegador. O evento de conversão é enviado do seu servidor para a API do Tapfiliate. Sem pixel. Sem dependência do navegador. Sem lacunas.

Como funciona o rastreamento de afiliados do lado do servidor

O ciclo de vida do ID de clique

Tudo no rastreamento de afiliados do lado do servidor deriva de um conceito: o ID de clique. Entender seu ciclo de vida torna a implementação evidente.

Aqui está o fluxo completo de ponta a ponta:

1. Um usuário clica em um link afiliado. A URL contém o código de referência do afiliado, por exemplo, ?ref=sarah123.
2. Seu servidor recebe a solicitação da página de destino e detecta o parâmetro ref na URL.
3. Seu backend faz uma chamada POST /clicks/ para a API REST do Tapfiliate, transmitindo o código de referência.
4. O Tapfiliate cria um registro de clique e retorna um ID de clique único para esse evento específico.
5. Seu backend armazena o ID de clique, vinculado à sessão do servidor do usuário ou a uma linha de banco de dados.
6. O usuário finaliza uma compra. Seu gerenciador de confirmação de pedido faz uma chamada POST /conversions/, transmitindo o ID de clique armazenado.
7. Tapfiliate associa o ID do clique ao afiliado de origem, calcula a comissão e credita a conta do afiliado.
8. O afiliado vê a comissão aparecer em tempo real no seu painel Tapfiliate.

As etapas 1 a 5 ocorrem durante a solicitação da página de destino. As etapas 6 a 8 acontecem no evento de confirmação do pedido. O navegador do comprador está envolvido apenas na etapa 1, para transmitir o parâmetro ref na URL.

Lado do cliente vs lado do servidor: a diferença estrutural

No rastreamento do lado do cliente, o navegador do comprador é a fonte da verdade. Ele detém o cookie, dispara o pixel e reporta a conversão. Qualquer falha no dispositivo do comprador resulta em atribuição perdida.

No rastreamento do lado do servidor, seu backend é a fonte da verdade. Ele captura o código de indicação na chegada, cria o clique, armazena o ID do clique e dispara o evento de conversão na compra. Os parâmetros do navegador do comprador são irrelevantes, sejam cookies, bloqueio de JavaScript ou contexto web vs aplicativo.

	Lado do cliente (Pixel)	Lado do servidor (API S2S)
Fonte do sinal de conversão	Navegadores do comprador	Seu servidor backend
Impacto do bloqueador de anúncios	Bloqueia o script de rastreamento	Sem impacto
Impacto do ITP iOS	Expiração do cookie em 24h	Sem impacto
Precisão da atribuição (mobile)	60–70 %	Quase completa
Rastreamento multi-dispositivo	Não	Sim (via sessão/conta)
Complexidade de implementação	Baixa	Média
Exposição ao GDPR	Maior (dados armazenados no navegador)	Menor (controlado no servidor)

A API REST Tapfiliate: sua caixa de ferramentas para implementação

Autenticação

Cada solicitação à API REST Tapfiliate requer um cabeçalho:

X-Api-Key: YOUR_API_KEY

Sua chave API está disponível na sua conta Tapfiliate em Configurações. Armazene-a em uma variável de ambiente. Nunca a codifique diretamente no código-fonte. Nunca a envie para um repositório de controle de versão. Nunca a exponha no JavaScript do lado do cliente.

A chave API permite criar conversões e aprovar comissões. Uma chave exposta representa um risco financeiro, não apenas um risco de rastreamento.

# Correct: environment variableexport TAPFILIATE_API_KEY="your_key_here"# Wrong: hardcodedconst apiKey = "tap_live_abc123xyz"; // Do not do this

Todos os endpoints usam Content-Type: application/json. Todas as respostas são em JSON. A API está atualmente na versão 1.6. Para referência completa dos endpoints, consulte a documentação da API REST Tapfiliate.

Uma checklist rápida de segurança para sua chave API antes de escrever qualquer linha de código de rastreamento:

• Armazene a chave em uma variável de ambiente ou gerenciador de segredos (AWS Secrets Manager, Vault, GCP Secret Manager).
• Renove a chave se ela já foi enviada para um repositório, mesmo que brevemente, mesmo em um repositório privado.
• Configure um alerta se a chave for detectada em um novo commit via uma ferramenta como GitGuardian ou o scanner de segredos do GitHub.
• Use chaves distintas para staging e produção. Um teste em staging disparado com uma chave de produção gera comissões reais.

Nada disso é específico do Tapfiliate. Isso se aplica a todas as chaves API que seu backend gerencia. Mas as chaves das plataformas de afiliados são particularmente sensíveis, pois estão na interseção entre dinheiro e confiança dos parceiros.

Os três endpoints essenciais

Para o rastreamento de afiliados do lado do servidor, você precisa de dois endpoints principais e um endpoint opcional:

POST /clicks/
Cria um registro de clique quando um usuário chega via link de afiliado. Envie o código de indicação do afiliado. Tapfiliate retorna um objeto clique contendo o ID do clique.

POST /conversions/
Registra uma conversão vinculada a um ID de clique armazenado. Tapfiliate atribui a conversão ao afiliado correto e coloca a comissão em fila para pagamento. Envie seu ID interno de pedido como external_id para evitar duplicatas.

POST /customers/ (opcional)
Cria um registro persistente do cliente. Relevante para programas de assinatura e SaaS onde você rastreia o valor vitalício do cliente e deseja atribuição recorrente de comissões em múltiplos eventos de faturamento, não apenas na primeira compra.

O Tapfiliate também suporta atribuição secundária via código de indicação ou código promocional diretamente no POST /conversions/. Se um usuário chegar sem o parâmetro ref, mas usar um cupom afiliado no pagamento, você pode enviar o código promocional na chamada de conversão e a atribuição será precisa.

Guia de Implementação: Configuração Completa S2S

Este guia utiliza Node.js. O mesmo modelo se aplica para Python, Go, Ruby ou qualquer outra linguagem backend. Substitua as chamadas fetch pelo seu cliente HTTP preferido.

Passo 1: Capture o parâmetro ref do afiliado na chegada

Cada visitante do seu site pode ou não conter um código de indicação afiliado na URL. Seu middleware de landing deve verificar isso a cada requisição e criar um clique quando presente.

// Express.js middleware, runs on every incoming page requestapp.use(async (req, res, next) => {  const affiliateRef = req.query.ref || req.query.tap_a;  if (affiliateRef) {    try {      const click = await createTapfiliateClick(affiliateRef);      // Store the click ID in the server-side session      req.session.tapClickId = click.id;    } catch (err) {      // Non-blocking: log the failure, do not prevent page load      console.error('Tapfiliate click creation failed:', err.message);    }  }  next();});

O bloco try/catch aqui é intencional e crucial. A criação do clique nunca deve bloquear o carregamento da página. Se a API do Tapfiliate estiver lenta ou temporariamente indisponível, o usuário ainda acessa seu site. Você registra a falha e continua.

Passo 2: Armazene o ID do clique no servidor

A função createTapfiliateClick chama POST /clicks/ e retorna o ID do clique.

async function createTapfiliateClick(referralCode) {  const response = await fetch('https://api.tapfiliate.com/1.6/clicks/', {    method: 'POST',    headers: {      'Content-Type': 'application/json',      'X-Api-Key': process.env.TAPFILIATE_API_KEY,    },    body: JSON.stringify({      referral_code: referralCode,    }),  });  if (!response.ok) {    throw new Error(`Tapfiliate API returned ${response.status}`);  }  return response.json(); // Returns { id: "click_abc123...", ... }}

O campo id na resposta é o ID do clique. Armazene-o na sessão do servidor, em um cookie assinado com flags HttpOnly e Secure ativados, ou em uma linha de banco de dados vinculada ao identificador da sessão do usuário.

Não armazene em cookie acessível pelo cliente nem no localStorage. Esse armazenamento é visível por extensões de navegador e pode ser manipulado.

Passo 3: Dispare o postback de conversão

Quando uma compra for finalizada, chame POST /conversions/ a partir do seu gerenciador de pedidos backend. Nunca chame a partir de um script frontend ou gerenciador de tags.

async function recordTapfiliateConversion(clickId, orderId, orderValue) {  const response = await fetch('https://api.tapfiliate.com/1.6/conversions/', {    method: 'POST',    headers: {      'Content-Type': 'application/json',      'X-Api-Key': process.env.TAPFILIATE_API_KEY,    },    body: JSON.stringify({      click_id:    clickId,      external_id: orderId,    // Your internal order ID (used for deduplication)      amount:      orderValue, // Order value in your program's base currency    }),  });  if (!response.ok) {    const errorBody = await response.text();    console.error(`Tapfiliate conversion failed [${response.status}]: ${errorBody}`);    // Add to retry queue; do not silently discard  }}

Integre isso ao seu webhook pós-pagamento ou gerenciador de confirmação de pedido:

// Post-payment webhook endpointapp.post('/webhooks/payment-confirmed', async (req, res) => {  const { orderId, orderValue, sessionId } = req.body;  // Look up the click ID stored during the user's landing visit  const clickId = await getClickIdForSession(sessionId);  if (clickId) {    await recordTapfiliateConversion(clickId, orderId, orderValue);  }  res.sendStatus(200);});

Na minha experiência, o erro de implementação mais comum é disparar essa chamada de conversão na página “obrigado” frontend via script ou gatilho GTM. Se o comprador fechar a aba antes da página carregar completamente (o que acontece mais do que se imagina), a conversão é silenciosamente perdida. Sempre dispare a partir do evento de confirmação de pagamento backend.

Passo 4: Verifique no painel Tapfiliate

Após sua primeira transação de teste, faça login na sua conta Tapfiliate e acesse Conversões. Confirme que a conversão aparece com o afiliado correto, o valor do pedido e o status “Pendente”.

Uma resposta 400 ao POST /conversions/ geralmente significa que o ID do clique é inválido ou expirado. Um 401 indica que o cabeçalho da chave API está ausente ou incorreto. Para a lista completa de códigos de erro e parâmetros adicionais, incluindo como anexar metadados ou IDs de clientes às conversões, consulte os guias de integração para desenvolvedores do Tapfiliate.

Casos extremos enfrentados por desenvolvedores

IDs de clique ausentes (tráfego direto e dark social)

Nem todos os visitantes chegam via link afiliado. Tráfego direto, newsletters por e-mail, campanhas SMS e compartilhamentos dark social não contêm parâmetro ref. Seu middleware não encontra nada, nenhum ID de clique é armazenado e nenhum afiliado é registrado.

Percebi que as equipes frequentemente esquecem de tratar explicitamente esse caso. IDs de clique nulos enviados ao POST /conversions/ geram erros 400 que parecem falhas de integração. Isso não é verdade. São situações esperadas que requerem um ramo condicional.

// In your payment confirmation handlerif (clickId) {  await recordTapfiliateConversion(clickId, orderId, orderValue);} else {  // No affiliate referral detected; organic or direct conversion  logger.info('Conversion recorded without affiliate attribution', { orderId });}

Para compradores que chegam sem parâmetro ref mas usam um código promocional afiliado no pagamento, você pode enviar diretamente o código promocional na chamada de conversão em vez de um ID de clique. O Tapfiliate resolve a atribuição a partir do cupom.

Prevenção de conversões duplicadas

Os atrasos na rede causam reenvios de webhooks. Sem deduplicação, uma única compra dispara dois ou três eventos de conversão. Seu programa de afiliados credita várias vezes a mesma venda.

A solução é o campo external_id no POST /conversions/. O Tapfiliate rejeita qualquer conversão enviada com um external_id já existente na sua conta.

body: JSON.stringify({  click_id:    clickId,  external_id: orderId,   // Your stable internal order ID (safe to retry)  amount:      orderValue,}),

Use sempre seu ID interno de pedido como external_id. Sempre. Nunca gere um novo ID a cada tentativa de reenvio. Um ID de pedido estável garante que o endpoint seja idempotente. Você pode tentar quantas vezes precisar sem criar comissões duplicadas.

Atribuição multitouch e entre sessões

Um usuário frequentemente interage com vários links de afiliados antes de converter. Ele clica em uma publicação do Instagram do afiliado A na segunda-feira. Clica em um link de blog do afiliado B na quinta-feira. Ele realiza a compra na sexta-feira.

O modelo padrão do Tapfiliate atribui a comissão ao último clique, ou seja, ao afiliado B. Se o seu modelo de programa utiliza atribuição no primeiro contato, você pode manter o primeiro ID de clique armazenado verificando se ele já existe na sessão antes de sobrescrevê-lo:

// Only store a click ID if one is not already present for this sessionif (!req.session.tapClickId) {  const click = await createTapfiliateClick(affiliateRef);  req.session.tapClickId = click.id;}

O modelo que você utiliza depende das regras do seu programa. A implementação é idêntica em ambos os casos. A diferença está em sobrescrever ou não o ID de clique armazenado durante visitas subsequentes a links de afiliados.

Privacidade, segurança e LGPD

Nunca exponha sua chave API no lado do cliente

O cabeçalho X-Api-Key autentica as requisições que criam conversões e validam comissões. Não é um token de análise somente leitura.

Se a chave aparecer em uma requisição de rede do navegador (um componente React, uma tag HTML personalizada GTM ou uma função de origem Segment), qualquer usuário pode extraí-la através das ferramentas de desenvolvimento do navegador. Ele poderia então gerar conversões fraudulentas para qualquer afiliado do seu programa.

Todas as chamadas da API REST do Tapfiliate devem vir do seu backend. Seu JavaScript frontend não tem motivo legítimo para chamar a API Tapfiliate. Se você usa um gerenciador de tags do lado do cliente com sua implementação S2S, certifique-se de que a integração do gerenciador utilize uma camada de dados separada e isolada. Nunca transmita sua chave API por meio dela.

LGPD e minimização de dados para IDs de clique

Um ID de clique é um identificador pseudonimizado que, combinado com outros dados, pode ser vinculado a uma pessoa. Dependendo do contexto do processamento, pode ser considerado um dado pessoal sob a LGPD.

Medidas práticas de conformidade:

1. Defina um limite de retenção. A janela padrão de atribuição do Tapfiliate é de 30 dias. Exclua os IDs de clique armazenados em sua sessão ou banco de dados após 30 dias sem conversão.
2. Evite links desnecessários. Não armazene IDs de clique na mesma linha do banco de dados que dados diretamente identificáveis (nome, e-mail) sem base legal documentada.
3. Inclua a gestão dos IDs de clique no seu Contrato de Processamento de Dados com o Tapfiliate. O DPA cobre os dados que o Tapfiliate processa em seu nome.
4. Atenda às solicitações de exclusão. As solicitações de direito ao apagamento devem incluir a remoção dos IDs de clique armazenados relacionados a esse usuário.

Para programas com usuários da UE, documente o processamento dos IDs de clique em seus Registros de Atividades de Processamento. Para uma leitura aprofundada sobre a integração S2S no rastreamento de programas de influenciadores, consulte o rastreamento híbrido de influenciadores com software de afiliados.

Testando sua implementação S2S

Validação do rastreamento paralelo

Antes de desativar seu rastreamento por pixel existente, faça os dois sistemas funcionarem em paralelo por pelo menos 48 horas. Isso permite comparar as contagens de conversão e detectar problemas no armazenamento dos IDs de clique sem perda de dados de atribuição.

O protocolo de teste:

1. Ative seu código postback S2S em paralelo com o pixel do lado do cliente existente.
2. Gere de 10 a 20 transações de teste controladas usando seus próprios links de afiliados.
3. Compare o número de conversões no Tapfiliate com o do seu sistema de gestão de pedidos.
4. Se as contagens corresponderem para os 10 a 20 pedidos de teste: o S2S está funcionando corretamente. Desative o pixel.
5. Em caso de divergência: verifique primeiro a lógica de recuperação dos IDs de clique no gerenciador de pagamento. A causa mais comum é a expiração da sessão entre o acesso e a compra para compras que exigem mais tempo de decisão.

Um método prático para testar sem pedidos reais: use a conta de afiliado de teste do Tapfiliate e um ambiente de pré-produção. Crie um afiliado de teste, clique no seu próprio link de afiliado em modo de navegação anônima, faça uma compra de teste e depois verifique se a conversão aparece no painel do Tapfiliate. Isso oferece um teste completo de ponta a ponta sem afetar os dados de produção.

Um último ponto a verificar: certifique-se de que sua deduplicação external_id está funcionando. Envie duas vezes o mesmo ID de pedido de teste e confirme que a segunda chamada retorna um código 409 ou uma rejeição semelhante por duplicação. Se ambas as chamadas forem bem-sucedidas, sua deduplicação não está funcionando e você acumulará comissões duplicadas em novas tentativas de webhook.

A lista de conversões do Tapfiliate exibe a fonte de atribuição de cada registro. Você pode filtrar por intervalo de datas e confirmar que as conversões passaram pela API S2S. Se conversões via caminho JavaScript aparecerem durante o teste paralelo, seu middleware S2S não está capturando corretamente o ID do clique na landing page.

Para programas maiores migrados de outra plataforma de afiliados, consulte o guia de migração de programas de afiliados do Tapfiliate.

FAQ

O que é o rastreamento de afiliados do lado servidor?

O rastreamento de afiliados do lado servidor envia eventos de conversão diretamente do seu servidor backend para a API da plataforma de afiliados, em vez de depender de um pixel acionado no navegador do comprador. Como o sinal de conversão vem do seu servidor, ele não é afetado por bloqueadores de anúncios, restrições de cookies no iOS ou abandono da página antes do carregamento do JavaScript.

O que é uma URL de postback no marketing de afiliados?

Uma URL de postback é o endpoint da API que seu servidor chama para reportar uma conversão realizada. Quando um comprador realiza uma compra, seu backend envia o ID do clique armazenado para o endpoint da plataforma de afiliados. A plataforma associa esse ID ao clique original, atribui a conversão ao afiliado correspondente e calcula a comissão devida.

O que é um ID de clique no rastreamento de afiliados?

Um ID de clique é um identificador único gerado quando um usuário clica em um link de afiliado. Seu backend captura o código de referência na URL, faz uma chamada POST /clicks/ e recebe o ID de clique em retorno. Você o armazena no servidor. No momento da compra, você o envia junto com o evento de conversão, servindo como prova que conecta um clique específico a uma venda específica sem usar cookies.

Como implementar o rastreamento S2S sem cookies?

Capture o parâmetro ref da URL na primeira requisição na página de destino do usuário. Faça uma chamada POST /clicks/ com o código de referência e armazene o ID de clique retornado na sessão do servidor ou no banco de dados. Quando o usuário converter, faça uma chamada POST /conversions/ com o ID de clique armazenado a partir do seu gerenciador de pagamento backend. Nenhum cookie é usado em nenhuma etapa. Consulte a documentação da API REST do Tapfiliate para referência completa dos parâmetros e esquemas de resposta.

O rastreamento de afiliados do lado servidor está em conformidade com a LGPD?

Sim, quando implementado corretamente. O rastreamento S2S não utiliza cookies de terceiros e oferece controle direto sobre os identificadores armazenados, sua duração e base legal. Você deve documentar o processamento dos IDs de clique em seus Registros de Atividades de Tratamento, respeitar solicitações de exclusão e aplicar a minimização de dados. Comparado ao rastreamento por pixel, o rastreamento do lado servidor geralmente reduz sua exposição à LGPD, pois o navegador não é mais o ponto de coleta de dados.

Feche a lacuna

Seu sistema de gestão de pedidos já detém a verdade. Cada compra confirmada está registrada nele.

A única questão é se seu programa de afiliados também está informado.

Três chamadas API separam uma taxa de atribuição de 65% de uma atribuição quase completa. POST /clicks/ na landing page. ID de clique armazenado na sessão. POST /conversions/ na confirmação da compra.

O afiliado que gerou 847 dessas 1.203 vendas merece uma atribuição precisa para essas 847. Seu programa merece os dados para identificar quais fontes de tráfego realmente convertem e quais não convertem.

Comece seu teste gratuito no Tapfiliate e conecte diretamente seu backend à API REST do Tapfiliate. Nenhum cartão de crédito é necessário. Adotado por mais de 69.500 profissionais de marketing e equipes técnicas.