Pinterest Conversions API: implementação completa server-side do zero à otimização

Por que Pinterest exige um olhar próprio#

Pinterest é uma plataforma de descoberta com ciclo de decisão mais longo que redes de resposta imediata. O usuário salva um Pin, volta dias depois, e só então converte. Esse comportamento tem uma consequência direta na mensuração: a conversão quase sempre acontece longe do clique, muitas vezes em outra sessão e outro dispositivo. Depender só da tag de conversão no navegador, que perde o rastro na virada de sessão e no fim dos cookies de terceiros, é aceitar uma subcontagem estrutural.

A Conversions API do Pinterest (a API de eventos server-side, historicamente ligada à infraestrutura da tag e ao formato de eventos do Pinterest) manda o evento direto do seu servidor para o Pinterest. Ela restaura a atribuição perdida e — o ponto central da abordagem da casa — permite disparar a conversão só quando ela é real, não quando o usuário sinalizou intenção.

O modelo de eventos do Pinterest#

O Pinterest trabalha com um conjunto de eventos padronizados que a otimização entende:

• checkout — a compra concluída. É o evento de receita, com valor e moeda.
• add_to_cart — item adicionado ao carrinho.
• page_visit — visita a uma página relevante.
• signup — cadastro concluído.
• lead — lead qualificado.
• search, view_category, custom — sinais complementares de funil.

Cada evento carrega um envelope com campos de topo e um objeto de dados de usuário. Os campos estruturais:

• event_name — um dos nomes padronizados acima.
• action_source — a origem: web, app_android, app_ios ou offline. Para eventos de site server-side, é web.
• event_time — timestamp Unix em segundos, dentro da janela aceita.
• event_id — a chave de deduplicação contra a tag.
• user_data — as match keys.
• custom_data — valor, moeda, content_ids, contents, num_items, order_id.

Identidade: epik, click_id e os hashes#

A qualidade da correspondência no Pinterest depende de quantos e quão bons são os sinais de identidade que você envia em user_data. Assim como nas outras plataformas, PII vai hasheada em SHA-256 após normalização, e sinais de clique/contexto vão em claro.

Os campos hasheados:

• em — email normalizado (minúsculas, sem espaços) e depois SHA-256.
• ph — telefone em formato internacional, só dígitos, depois hash.
• hashed_maids — advertising ID móvel hasheado, quando aplicável.
• external_id — seu ID interno de cliente, hasheado. Sinal estável e valioso para ligar sessões distantes ao mesmo usuário.

Os campos em claro:

• click_id — o valor do parâmetro epik capturado da URL quando o usuário chega por um anúncio do Pinterest, e o cookie _epik que a tag grava. Esse é o sinal de correspondência mais forte. Capture-o no primeiro toque e persista em cookie first-party, porque a conversão pode vir muito depois.
• client_ip_address — o IP do cliente que originou a ação.
• client_user_agent — o user-agent do navegador do cliente.

O detalhe crítico do longo ciclo do Pinterest: como a conversão vem dias depois, você precisa ter guardado o epik no momento do clique. Se só captura na hora da compra, o parâmetro já sumiu da URL há muito tempo. A persistência em cookie first-party (ou atrelada ao registro do usuário) é o que segura a atribuição.

Deduplicação com a tag do Pinterest#

Se você roda a tag do Pinterest no navegador e a Conversions API no servidor em paralelo — a arquitetura recomendada para cobertura máxima —, a deduplicação evita contar a mesma compra duas vezes.

O Pinterest deduplica pelo event_id combinado com o event_name. As regras:

• Gere o event_id no servidor no momento em que o pedido é criado. O ID do pedido serve bem.
• Repasse esse mesmo event_id para a tag no navegador, de modo que os dois envios do checkout carreguem o valor idêntico.
• Mantenha o event_name igual nas duas pontas.

Quando o Pinterest recebe dois checkout com o mesmo event_id, mantém um só. Sem isso, cada conversão dobra e a otimização passa a perseguir um número inflado.

O padrão que importa: enviar na conversão real#

A tag no navegador dispara checkout no instante em que o usuário chega à página de obrigado — o que inclui compras que ainda vão falhar no processamento do pagamento, boletos que nunca serão pagos e assinaturas que não completam. Server-side, você inverte a lógica: o evento sai do webhook de pagamento confirmado.

O fluxo:

1. O usuário finaliza; o pedido é criado como pendente e você já capturou epik, email e o external_id.
2. O gateway processa e chama seu webhook quando aprova.
3. Seu backend valida a assinatura do webhook, confirma o pagamento e monta o payload do checkout com o valor real.
4. A chamada à Conversions API sai com o event_id do pedido e as match keys.

Esse desenho é o que faz o Pinterest otimizar para compradores de verdade. Uma plataforma que recebe o evento só na conversão real aprende a encontrar o público que gera receita, não o que abandona no pagamento.

Entrega confiável no ciclo longo#

Como a conversão do Pinterest é distante do clique, o desafio de entrega tem uma camada extra: você precisa reter os sinais de identidade por dias. O padrão de outbox continua valendo para a chamada em si, mas some a ele a persistência do contexto de clique.

• Persistência do epik. Grave-o assim que o usuário chega por anúncio, com um TTL generoso (compatível com a janela de atribuição do Pinterest). Recupere na conversão.
• Outbox transacional. O webhook grava o evento na fila persistente na mesma transação do pedido; um worker consome com retry e backoff.
• Idempotência. O event_id estável garante que reprocessamentos não geram contagem dupla; marque o item como enviado com atualização atômica.
• Tratamento de erro honesto. Payload malformado não se resolve com retry; erro transitório sim. Nunca engula a falha — logue com trace_id e alerte.

Conversões offline no Pinterest#

Nem toda conversão do Pinterest é online. Loja física, venda por telefone, fechamento de contrato — tudo isso pode ser reportado com action_source igual a offline, ligando o público do Pinterest a resultados do mundo real. O mecanismo é o mesmo: você casa a venda offline com a identidade (email ou telefone do cliente capturados no PDV ou no CRM), hasheia e envia. Sem o epik disponível offline, o email e o telefone tornam-se os principais elos de correspondência — mais uma razão para capturar identidade de qualidade no atendimento.

Validação e monitoramento#

Antes de confiar nos números, valide:

• Ferramenta de teste de eventos. O Pinterest oferece um modo de conferência no Events Manager/Conversions setup para inspecionar se os eventos chegam com o formato certo e quais campos de correspondência foram reconhecidos.
• Taxa de correspondência. Acompanhe a proporção de eventos que o Pinterest conseguiu casar. Uma taxa baixa denuncia payload pobre — falta de epik, hashes inconsistentes, IP do servidor no lugar do IP do cliente.
• Reconciliação com o financeiro. O número de checkout reportado deve bater, dentro de uma margem, com os pedidos pagos do período. Divergência grande é sinal de dedupe quebrado ou de evento disparado fora do webhook.

Eventos de funil que valem a pena instrumentar#

No Pinterest, a decisão é lenta e o funil tem várias paradas. Instrumentar só o checkout desperdiça a capacidade da plataforma de aprender com sinais intermediários. Vale a pena reportar, na ordem do funil:

• page_visit em páginas de produto e de categoria — mostra ao Pinterest quais interesses o usuário demonstrou.
• view_category — quando o usuário navega uma categoria inteira, sinal de intenção mais amplo.
• add_to_cart — o sinal de intenção mais forte antes da compra; alimenta remarketing e otimização de conversão.
• signup e lead — para modelos que capturam contato antes de vender.
• checkout — a conversão de receita, sempre no webhook de pagamento.

Cada evento intermediário pode ir client-side pela tag (onde o risco de dupla contagem é baixo, porque não são receita) e o checkout server-side pela Conversions API. Essa divisão dá cobertura de funil sem inflar o número que importa. O cuidado é manter a nomenclatura padronizada: um evento com nome fora do vocabulário do Pinterest não é otimizável, vira apenas um custom sem inteligência associada.

Enriquecer <code>custom_data</code> para otimização por valor#

Reportar só que houve uma compra é o mínimo. O Pinterest otimiza melhor quando recebe o valor e o conteúdo da conversão. No custom_data, capriche em:

• value e currency — o valor real cobrado, na moeda certa. Sem isso, a otimização por valor (ROAS) não funciona.
• content_ids — os IDs dos produtos comprados, que precisam casar com os IDs do seu catálogo/feed para ligar a conversão ao produto anunciado.
• contents — detalhamento com quantidade e preço por item, útil para cestas com múltiplos produtos.
• num_items — a quantidade total de itens.
• order_id — o identificador do pedido, que também ancora a deduplicação e a idempotência.

A consistência entre content_ids reportados aqui e os IDs do feed de produtos é o que permite ao Pinterest fechar o ciclo entre o anúncio dinâmico (que mostrou o produto) e a conversão (que o comprou). Feed desalinhado com os IDs da conversão quebra a atribuição de produto, mesmo com o evento chegando corretamente.

Erros comuns que sabotam a implementação#

Alguns problemas recorrentes derrubam a qualidade sem dar erro visível:

• Não persistir o epik. Capturar só na conversão, quando o parâmetro já sumiu, é o erro número um no Pinterest pelo ciclo longo. Persista no primeiro toque.
• Hash inconsistente entre tag e API. Se a tag normaliza o email de um jeito e o servidor de outro, a deduplicação por identidade falha e o EMQ despenca.
• IP do servidor no lugar do IP do cliente. Em arquitetura com proxy, ler o IP errado zera um sinal de correspondência importante.
• Reportar checkout fora do webhook. Disparar na tela de sucesso conta compras que vão falhar no pagamento e infla a receita reportada.
• Campos vazios em vez de omitidos. Mandar em como string vazia é pior que não mandar; omita o campo quando não houver o dado.

Checklist de implementação#

• Eventos padronizados (checkout, add_to_cart, lead, signup) com nomes corretos.
• epik capturado no primeiro toque e persistido em cookie first-party por dias.
• Match keys (em, ph, external_id) hasheadas com normalização única.
• IP e user-agent do cliente, nunca do servidor.
• event_id estável compartilhado entre tag e Conversions API.
• Conversão disparada no webhook de pagamento aprovado.
• Outbox com retry, idempotência e alerta.
• Conversões offline reportadas quando houver venda fora do site.
• Taxa de correspondência e reconciliação financeira monitoradas.

Pinterest recompensa quem trata a mensuração como um sistema de longo prazo. O clique de hoje vira compra na semana que vem; quem persiste a identidade e envia o evento só na conversão real transforma descoberta em receita atribuível.