Rastreamento de conversão na Nuvemshop: o que a plataforma entrega e o que você precisa construir

A Nuvemshop é uma das plataformas de e-commerce mais populares da América Latina, e a lógica de rastreamento nela é bem diferente da de um WooCommerce. Aqui você não tem acesso ao servidor, não escreve PHP no back-end da loja e não engancha hooks no banco de dados. É um SaaS fechado: a plataforma roda a loja, e você conversa com ela por fora, através de webhooks e da API pública. Isso não significa que o server-side esteja fora de alcance — significa que a arquitetura muda de "código dentro da loja" para "serviço próprio que escuta a loja". Este texto explica o que a Nuvemshop entrega nativamente, onde estão os limites, e como montar uma camada de conversão confiável por cima dela.

O modelo mental: você está do lado de fora#

Em plataformas open-source você mora dentro da aplicação. Na Nuvemshop você mora fora e observa. A loja emite sinais — um pedido foi criado, um pagamento foi confirmado, um pedido foi cancelado — e você recebe esses sinais como notificações. A sua camada de mensuração é um serviço separado, com endereço próprio, que fica ouvindo esses avisos e, a cada um relevante, decide se aquilo é uma conversão e monta o envio para a plataforma de anúncios.

Essa separação é na verdade saudável. O seu serviço de conversão não depende do tema da loja, não quebra quando o lojista troca o layout, e não some numa atualização da plataforma. Ele é uma entidade à parte, que sobe e funciona sozinha, e a única coisa que precisa da Nuvemshop é o fluxo de eventos e o acesso à API para consultar detalhes.

O que a Nuvemshop oferece nativamente#

A plataforma tem campos de configuração para colar o identificador do pixel da Meta e a tag do Google, e com isso ela dispara os eventos padrão do lado do cliente: visualização de página, visualização de produto, adição ao carrinho, início de checkout e compra. Para muitas lojas pequenas isso é suficiente como ponto de partida. O problema é o mesmo de qualquer rastreamento client-side: o evento de compra depende do navegador chegar à página final, e essa página nem sempre é vista, principalmente quando o pagamento acontece num gateway externo que redireciona.

Então a mensuração nativa serve como piso, mas não como fonte da verdade. Para conversão que reflita a receita real, o caminho é o webhook.

Webhooks: a fonte da verdade da conversão#

A Nuvemshop permite registrar webhooks para eventos de pedido. Os que interessam para conversão são os que representam dinheiro entrando:

• criação de pedido, que marca a intenção de compra mas ainda não o pagamento;
• pedido pago, que é o evento de conversão para a maioria das lojas;
• pedido cancelado ou pedido reembolsado, que servem para não contar receita que voltou atrás.

O padrão recomendado é tratar o evento de pagamento confirmado como a compra. Quando ele chega, o seu serviço recebe uma notificação com o identificador do pedido. E aqui vem um cuidado importante: o webhook costuma trazer só o essencial — o identificador e o tipo do evento —, não o pedido inteiro com dados do cliente. Então o fluxo correto é receber a notificação e, em seguida, chamar a API da Nuvemshop para buscar o pedido completo, com valor, itens e dados do comprador. Nunca confie apenas no corpo do webhook para montar o payload de conversão; use-o como gatilho e busque a verdade na API.

Verifique a autenticidade do webhook#

Um endpoint que recebe webhook é um endpoint público na internet, e qualquer um que descubra a URL pode mandar um POST forjado dizendo "o pedido tal foi pago". A Nuvemshop assina as notificações, e o seu serviço precisa verificar essa assinatura antes de processar qualquer coisa — calcular o HMAC do corpo com o segredo compartilhado e comparar com o cabeçalho de assinatura. Se não bater, descarte. Sem essa verificação, alguém pode inflar suas conversões de fora, ou pior, injetar dados falsos na sua mensuração.

Buscando o pedido: montando o payload#

Com o identificador do pedido em mãos, a chamada à API traz o objeto completo. Dali você extrai o que a Conversions API da Meta e o Measurement Protocol do GA4 precisam.

O valor e a moeda vêm do total do pedido. Como sempre, decida se o número inclui frete e desconto, e mantenha essa decisão consistente com o que o financeiro reconhece. A Nuvemshop separa subtotal, frete, descontos e total, então você tem o controle — use-o com disciplina.

Os itens vêm das linhas do pedido. Cada produto tem identificador, quantidade e preço. O identificador precisa casar com o do seu feed de produtos usado nos anúncios dinâmicos; confirme se é o identificador interno do produto ou o SKU que o seu feed exporta.

Os dados de correspondência vêm do bloco do comprador: e-mail, telefone, nome, e endereço com cidade, estado e CEP. Todos precisam ser normalizados e hasheados com SHA-256 antes de sair do seu servidor. E-mail e telefone são os que mais pesam na qualidade da correspondência. Como o webhook chega ao seu servidor e não ao navegador, você tem o IP do seu serviço, não o do comprador — então capture o parâmetro de clique e o user agent do comprador no lado do cliente, no momento da visita, e amarre-os ao pedido, porque no webhook eles já não estarão disponíveis.

O desafio do parâmetro de clique numa loja fechada#

Esse é o ponto mais delicado do server-side em SaaS fechado. O fbclid e o gclid chegam na URL quando o comprador entra vindo de um anúncio, mas quem enxerga isso é o navegador, não o webhook. Para levar esse dado até a conversão você precisa capturá-lo cedo e persisti-lo de forma que possa ser recuperado no momento do webhook.

Na Nuvemshop, uma abordagem é usar um script no tema que grava o parâmetro de clique num cookie de primeira parte assim que o comprador entra, e depois, na finalização, anexa esse valor a um campo de observação ou nota do pedido — ou o envia a um endpoint seu que o associa ao carrinho. Quando o webhook de pagamento chega, você recupera esse valor pelo identificador do pedido ou do cliente. Não é tão elegante quanto capturar direto no servidor, mas é o que fecha a lacuna entre o clique e a conversão numa plataforma onde você não controla o back-end.

Deduplicação com o pixel nativo#

Se você deixa o pixel nativo da Nuvemshop ligado e ainda envia server-side pelo webhook, corre o risco de contar a mesma compra duas vezes. A deduplicação exige que os dois lados mandem o mesmo identificador de evento. O identificador do pedido da Nuvemshop é o candidato perfeito, porque é o mesmo dos dois lados e é único. O truque é fazer o pixel do lado do cliente usar o identificador do pedido como event_id, e o seu envio server-side usar o mesmo. Se a plataforma nativa não deixa você controlar o event_id do pixel, uma decisão mais limpa é desligar o evento de compra do pixel nativo e deixar apenas o server-side responsável pela conversão, mantendo o pixel só para os eventos de topo de funil, como visualização e carrinho.

Entrega confiável e reprocessamento#

O seu serviço de conversão precisa ser resiliente. Webhooks podem chegar fora de ordem, podem chegar duplicados (a Nuvemshop pode reenviar se não receber confirmação), e a API de anúncios pode estar indisponível na hora. Três defesas resolvem a maioria dos problemas.

• Idempotência por identificador de pedido: guarde quais pedidos já viraram conversão enviada e ignore o reenvio do mesmo. Assim, um webhook duplicado não gera conversão dobrada.
• Fila com retentativa: se a API da Meta ou do Google falhar, o evento fica pendente e é retentado com espera crescente, em vez de se perder.
• Confirmação rápida do webhook: responda ao webhook da Nuvemshop com sucesso assim que gravar o evento na sua fila, sem esperar o envio à plataforma de anúncios terminar. Se você demorar, a Nuvemshop pode considerar falha e reenviar, multiplicando o trabalho.

Múltiplas lojas Nuvemshop no mesmo serviço#

Quem administra um portfólio de lojas Nuvemshop — uma agência, ou um grupo com várias marcas — ganha muito ao centralizar a mensuração num único serviço que atende todas. Cada loja registra seu webhook apontando para o mesmo endpoint, e o serviço distingue de qual loja veio cada notificação para escolher o pixel e o token corretos. O ganho é operacional: você mantém uma base de código só, aplica correções uma vez para todas, e monitora a saúde da mensuração de forma consolidada. O cuidado é o isolamento: os tokens de conversão de cada loja precisam ficar separados e associados corretamente à origem, para que a conversão de uma loja nunca seja enviada ao pixel de outra. Um mapeamento por identificador de loja, guardado no serviço, resolve isso — e o mesmo mapeamento serve para saber a qual conta de API recorrer ao buscar o pedido completo. Essa arquitetura multi-loja é uma das razões pelas quais manter a mensuração como serviço à parte compensa: ela escala para muitas lojas sem multiplicar o esforço, algo impossível quando a lógica vive presa dentro de cada loja individual.

Validando antes de confiar#

Assim como em qualquer integração, valide de ponta a ponta antes de acreditar nos números. Faça um pedido real de teste, acompanhe a chegada do webhook no seu serviço, confirme que a busca na API trouxe o pedido completo, e use a aba de eventos de teste da Meta e o modo de depuração do GA4 para ver o evento chegar com valor, itens e dados de correspondência corretos. Teste também o caminho de cancelamento e reembolso, para garantir que receita que voltou atrás não fique contada como conversão viva.

Resumo do caminho na Nuvemshop#

Numa plataforma fechada como a Nuvemshop, o server-side deixa de ser código dentro da loja e vira um serviço à parte que escuta a loja. Registre o webhook de pagamento como gatilho da conversão, verifique a assinatura de cada notificação, busque o pedido completo na API para montar o payload, hasheie os dados de correspondência, resolva a captura do parâmetro de clique com um cookie de primeira parte no tema, unifique o event_id pelo identificador do pedido para deduplicar, e proteja tudo com idempotência e fila de retentativa. O resultado é uma mensuração que reflete a receita paga de verdade, independente de o comprador ter visto ou não a página de agradecimento.