Mensuração server-side na VTEX: eventos de pedido, orderForm e a máquina de estados

A VTEX é uma plataforma de e-commerce empresarial, e isso transparece em tudo: o pedido não é um registro simples, é uma máquina de estados com transições bem definidas, e a plataforma foi desenhada para se integrar com sistemas externos por meio de hooks e APIs robustas. Para quem vem de um WooCommerce ou de uma loja pequena, a curva é mais íngreme, mas a recompensa é uma capacidade de rastreamento server-side muito mais precisa e auditável. Este texto mostra como a VTEX estrutura o pedido, onde capturar a conversão de forma confiável, e como transformar isso em eventos para a Conversions API da Meta e o Measurement Protocol do Google.

O pedido como máquina de estados#

Na VTEX, um pedido passa por uma sequência de estados: do carrinho ao pagamento pendente, à análise, à autorização de pagamento, à faturação, ao envio e à entrega. Cada transição é um evento com significado próprio, e a plataforma permite que você seja notificado quando o pedido muda de estado por meio do chamado order hook — um webhook que a VTEX chama toda vez que um pedido avança na máquina de estados.

Essa granularidade é o que diferencia a VTEX. Em vez de um único momento vago de "conversão", você tem estados explícitos e pode escolher com precisão qual deles conta como a compra para efeito de mensuração. A decisão mais comum é usar o estado de pagamento aprovado (payment-approved) como o evento de conversão, porque é o ponto em que o dinheiro está garantido e o pedido vai seguir. Contar antes, na criação do pedido, infla a conversão com carrinhos que nunca serão pagos; contar depois, só na entrega, atrasa demais o sinal que a plataforma de anúncios precisa para otimizar.

O order hook: gatilho da conversão#

O order hook é uma configuração da conta VTEX que aponta para um endpoint seu. A cada mudança de estado do pedido, a VTEX faz uma chamada para esse endpoint informando o identificador do pedido e o novo estado. O seu serviço recebe essa notificação, verifica se o estado é o que você definiu como conversão, e só então age.

Como a notificação traz o identificador e o estado, mas não o pedido inteiro, o fluxo é: receber o aviso, confirmar que é a transição de interesse, e chamar a API de pedidos da VTEX (o endpoint que retorna o pedido pelo identificador) para obter o objeto completo. Dali saem os dados de valor, itens e cliente.

Um cuidado essencial na VTEX é a autenticação da chamada de volta à API. A VTEX usa chaves de aplicação — um par de chave e token de aplicação — que dão acesso à API administrativa. Essas credenciais são segredo de servidor e nunca podem aparecer em código de cliente, tema ou bundle de navegador. Elas moram no seu serviço, protegidas, e são usadas só na comunicação servidor-a-servidor com a VTEX.

orderForm: capturando o clique antes da conversão#

O grande desafio do server-side é levar o parâmetro de clique do anúncio — o fbclid e o gclid — desde a entrada do visitante até o momento da conversão, que acontece no servidor. Na VTEX, a peça que ajuda a resolver isso é o orderForm, a estrutura que representa o carrinho em andamento durante toda a jornada de compra.

O orderForm tem um campo de dados customizáveis (o customData e os marketingData) onde você pode gravar informação que persiste com o carrinho até virar pedido. A estratégia é capturar o parâmetro de clique no navegador assim que o visitante entra vindo de um anúncio, e gravá-lo no orderForm por meio da API de carrinho. Quando o pedido é fechado, esses dados migram do orderForm para o pedido, e ficam disponíveis quando o order hook dispara e você busca o pedido na API. Assim o clique que aconteceu no navegador chega até a conversão calculada no servidor, fechando a lacuna de atribuição.

O marketingData do orderForm, aliás, já foi pensado para carregar informação de origem de tráfego — utmSource, utmCampaign e afins. Usá-lo para os parâmetros de clique é aproveitar uma estrutura que a plataforma já mantém ao longo do funil.

Montando o payload de conversão#

Com o pedido completo em mãos, você monta o envio. O valor da conversão vem do total do pedido; a VTEX detalha o pedido em componentes de valor (itens, frete, descontos, impostos), então escolha o componente que corresponde à sua definição de receita e mantenha essa escolha alinhada com o financeiro. Enviar valores inconsistentes entre a plataforma de anúncios e o reconhecimento contábil é a origem mais comum de números que não batem na reconciliação.

Os itens vêm das linhas do pedido, cada uma com identificador do produto (o SKU na VTEX), quantidade e preço. Esse identificador precisa casar com o feed de produtos usado nos anúncios dinâmicos. A VTEX trabalha com uma distinção entre produto e SKU (a variação vendável); confirme qual dos dois o seu feed exporta, para não enviar um identificador que a plataforma de anúncios não reconhece.

Os dados de correspondência vêm do bloco de cliente e do endereço: e-mail, telefone, nome, cidade, estado, CEP e país. Todos precisam ser normalizados e hasheados com SHA-256 antes de sair do servidor. E-mail e telefone continuam sendo os campos de maior peso na qualidade da correspondência, e quanto mais campos válidos você enviar, maior a fração de conversões que a plataforma consegue atribuir aos anúncios.

Deduplicação com o rastreamento de front#

Muitas lojas VTEX mantêm o rastreamento do lado do cliente ativo, seja pelo pixel da Meta seja pela camada de dados que a plataforma expõe. Rodar isso em paralelo com o server-side exige deduplicação, senão a mesma compra é contada duas vezes. A regra é a de sempre: os dois lados precisam mandar o mesmo identificador de evento. O identificador do pedido da VTEX é o candidato natural, porque é único e o mesmo dos dois lados. Faça o front usar o identificador do pedido como event_id na página de confirmação, e o seu serviço server-side usar o mesmo identificador quando o order hook dispara. A plataforma de anúncios então reconhece que os dois envios são o mesmo fato e conta uma vez só.

Idempotência: o order hook dispara muitas vezes#

Como o order hook é chamado a cada transição de estado, e um pedido passa por vários estados, o seu endpoint vai ser chamado múltiplas vezes para o mesmo pedido. Se você não filtrar, pode enviar a conversão mais de uma vez. Duas travas resolvem: primeiro, aja apenas na transição específica que você definiu como conversão, ignorando as demais; segundo, guarde quais pedidos já geraram conversão enviada e ignore uma segunda ocorrência da mesma transição, que pode acontecer se a VTEX reenviar a notificação por não ter recebido confirmação. Essa combinação de filtro por estado e trava de idempotência por identificador de pedido é o que mantém a contagem íntegra.

Entrega confiável e o comportamento do hook#

O order hook da VTEX espera uma resposta de sucesso do seu endpoint. Se você demorar demais ou responder com erro, a VTEX vai retentar a notificação. Isso é bom para a confiabilidade — nenhuma transição se perde —, mas exige que o seu endpoint seja rápido e idempotente. O padrão robusto é: ao receber a notificação, gravar o evento numa fila e responder sucesso imediatamente; um worker separado processa a fila, busca o pedido na API, monta o payload e chama a plataforma de anúncios, retentando em caso de falha. Assim você separa a obrigação de responder rápido ao hook da obrigação de entregar o evento à API de conversão, e nenhuma das duas prejudica a outra.

Reembolsos, cancelamentos e a receita real#

A máquina de estados da VTEX também representa cancelamentos e estornos. Um pedido que foi pago e depois cancelado gerou uma conversão que não deveria mais contar como receita viva. O ideal é escutar essas transições e disparar um evento de reembolso para a plataforma de anúncios, ou pelo menos registrar o cancelamento para que a reconciliação com o financeiro não acuse divergência inexplicável. A vantagem da VTEX é que esses estados são explícitos, então você não precisa adivinhar quando uma venda voltou atrás — a plataforma te avisa.

Consistência entre ambientes e contas#

A VTEX costuma ser operada com ambientes distintos — produção, e um ou mais ambientes de homologação — e às vezes com múltiplas contas para diferentes marcas ou países dentro do mesmo grupo. Isso impõe disciplina de configuração à mensuração. O order hook de homologação nunca deve apontar para o mesmo endpoint que dispara conversões reais em produção, ou você vai enviar pedidos de teste à plataforma de anúncios e sujar os números. A recomendação é ter configurações separadas por ambiente: o endpoint de conversão de produção só recebe pedidos de produção, e o de homologação envia com o código de teste da Meta, para que os eventos apareçam apenas na aba de eventos de teste e nunca contem como conversão viva. Para grupos com várias contas VTEX, o serviço de mensuração precisa mapear cada conta ao seu pixel e token corretos, exatamente como no cenário multi-loja de qualquer plataforma. Guardar esse mapeamento por identificador de conta, no serviço, e nunca hardcodar o token de uma marca no fluxo de outra, é o que mantém a conversão de cada operação atribuída à campanha certa. A máquina de estados da VTEX é a mesma em todos os ambientes, então a lógica é reaproveitada — muda apenas a configuração de destino, e é justamente essa separação de configuração que evita o vazamento de dados de teste para os relatórios reais.

Validação de ponta a ponta#

Antes de confiar nos números, teste o fluxo inteiro num ambiente de homologação. Faça um pedido passar por toda a máquina de estados, confirme que o order hook dispara na transição certa, que a busca na API traz o pedido completo, e que o parâmetro de clique gravado no orderForm chegou até o pedido. 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 correspondência corretos. Só depois de o fluxo estar limpo em homologação você liga em produção.

O ganho de escolher a VTEX com disciplina#

A VTEX pede mais engenharia que uma loja simples, mas devolve controle e precisão à altura. A máquina de estados torna a definição de conversão explícita, o order hook entrega o gatilho confiável, o orderForm carrega o parâmetro de clique pelo funil, e a API administrativa fornece o pedido completo para um payload rico. Some a isso deduplicação por identificador de pedido, idempotência por estado, fila de retentativa e tratamento de estorno, e você tem uma mensuração server-side que reflete a receita real, resiste a falhas de rede e sobrevive à auditoria da reconciliação financeira.