Rastreamento server-side no Magento e Adobe Commerce: observers, eventos e a fila de conversão

O Magento — hoje também vendido como Adobe Commerce na versão paga — é uma plataforma de e-commerce robusta, orientada a eventos, e escrita em PHP. Para rastreamento server-side, isso a coloca numa posição parecida com a do WooCommerce: você tem acesso ao servidor, à camada de eventos e ao banco, e portanto pode desenhar a captura de conversão como engenharia interna, sem depender de um app de terceiro. A diferença é que o Magento é uma plataforma de porte empresarial, com arquitetura de módulos, sistema de eventos e observers, e uma fila de mensagens nativa que se encaixa perfeitamente no envio confiável de conversões. Este texto percorre onde capturar a compra, como montar o payload e como usar a infraestrutura do próprio Magento para não perder evento nem travar o checkout.

A arquitetura orientada a eventos do Magento#

O Magento dispara eventos em pontos-chave do fluxo, e você escuta esses eventos com observers — classes que a plataforma chama quando o evento correspondente acontece. Essa é a maneira idiomática de estender o Magento sem alterar o núcleo. Para conversão, os eventos que interessam giram em torno do ciclo de vida do pedido: a colocação do pedido, a mudança de status e a criação da fatura.

O evento de colocação do pedido dispara quando o pedido é registrado, o que acontece antes da confirmação do pagamento em muitos fluxos. Já a criação da fatura, ou a transição para um status que representa pagamento capturado, é o ponto que corresponde ao dinheiro efetivamente garantido. Para a maioria das lojas, o momento certo de contar a conversão é a captura do pagamento — a fatura no vocabulário do Magento —, não a mera colocação do pedido, porque um pedido colocado ainda pode falhar no pagamento. Escutar o evento de save da fatura, ou a transição de status para "processing" após a captura, alinha a conversão à receita real.

O observer como ponto de captura#

O observer é uma classe registrada num arquivo de configuração de eventos, dentro de um módulo próprio que você cria para a mensuração. Manter isso num módulo separado é a prática correta: a lógica de conversão fica isolada, não polui o núcleo, e pode ser versionada e testada por si só. Quando o evento de fatura ou de status dispara, o Magento chama o seu observer passando o objeto do pedido, e dali você tem acesso a tudo: valor, itens, cliente e endereço.

Aqui entra uma decisão de arquitetura fundamental: o observer não deve chamar a API da Meta ou do Google diretamente e de forma síncrona. Se ele fizer isso, o processamento do pedido fica esperando a resposta da rede, e uma API lenta atrasa o checkout enquanto uma API fora do ar pode até derrubar a finalização. O papel do observer é apenas capturar o evento e enfileirá-lo. O envio de verdade acontece depois, em segundo plano.

A fila de mensagens nativa: envio desacoplado#

O Magento tem um sistema de mensageria embutido, com filas e consumers, projetado justamente para trabalho assíncrono. Ele é a peça perfeita para o envio de conversões. O fluxo fica assim: o observer captura o pedido faturado e publica uma mensagem numa fila de conversão com os dados necessários; um consumer, rodando em segundo plano, consome essa fila, monta o payload, chama a plataforma de anúncios e trata a resposta.

Essa separação traz três ganhos diretos. O checkout finaliza na hora, porque o observer só enfileira e volta. O envio se torna resiliente, porque se a API falhar o consumer pode retentar sem afetar o comprador. E o sistema ganha capacidade de absorver picos, porque numa promoção com muitos pedidos a fila acumula e o consumer processa no ritmo que a API aguenta, sem estourar limites de taxa. É a arquitetura de outbox implementada com a infraestrutura que o Magento já oferece de fábrica.

Montando o payload de conversão#

Do objeto do pedido você extrai os blocos que a Conversions API da Meta e o Measurement Protocol do GA4 esperam.

O valor e a moeda vêm do total do pedido. O Magento detalha grand total, subtotal, frete, descontos e impostos separadamente, então escolha o componente que corresponde à sua definição de receita. Mantenha essa escolha idêntica à do reconhecimento financeiro, porque valores diferentes entre anúncio e contabilidade são a causa clássica de divergência inexplicável na reconciliação.

Os itens vêm das linhas do pedido. Cada item tem SKU, quantidade e preço. O SKU do Magento é normalmente o identificador que casa com o feed de produtos dos anúncios dinâmicos, mas confirme, porque em lojas com produtos configuráveis (o pai) e simples (as variações), o item do pedido pode carregar tanto o SKU do configurável quanto o da variação, e o feed precisa estar alinhado com um dos dois.

Os dados de correspondência vêm do cliente e do endereço de cobrança: e-mail, telefone, nome, sobrenome, cidade, estado, CEP e país. Todos precisam ser normalizados — minúsculas, sem espaços, telefone só com dígitos e código do país — e hasheados com SHA-256 antes de sair do servidor. E-mail e telefone são os campos de maior peso na correspondência. Quanto mais campos válidos, maior a fração de conversões atribuídas aos anúncios.

O parâmetro de clique num fluxo server-side#

Como em qualquer plataforma, o desafio é levar o fbclid e o gclid do navegador até a conversão que se calcula no servidor. No Magento você captura o parâmetro de clique no início da visita, com um pequeno script no tema, e o persiste na sessão do comprador ou o grava como um dado adicional do quote (o carrinho do Magento). Quando o quote vira pedido, esse dado migra para o pedido, e no observer você o recupera junto com o restante. O user agent do comprador e o IP também devem ser capturados no lado do cliente e amarrados ao pedido, porque no envio server-side o IP visível é o do seu servidor, não o do comprador.

Deduplicação com o rastreamento de front#

Se a loja mantém o pixel do navegador ativo em paralelo com o server-side, é preciso deduplicar. A regra vale para o Magento como para todas: os dois lados enviam o mesmo identificador de evento. O identificador do pedido do Magento — o increment id, aquele número que o cliente vê — é o candidato ideal, porque é único e o mesmo dos dois lados. Faça o pixel na página de sucesso usar o increment id como event_id, e o consumer da fila usar o mesmo. Assim a plataforma reconhece os dois envios como o mesmo fato e conta uma vez só. Alternativamente, desligue o evento de compra do pixel e deixe o server-side como fonte única da conversão, mantendo o pixel só para eventos de topo de funil.

Idempotência e reprocessamento#

Eventos podem ser reprocessados. O consumer pode reiniciar no meio de uma mensagem, uma fatura pode ser salva mais de uma vez, e a fila pode entregar a mesma mensagem de novo. A defesa é a idempotência por identificador de pedido: antes de enviar, o consumer checa se aquele pedido já teve conversão enviada, e se sim, descarta. Gravar essa marca — no próprio pedido ou numa tabela de controle — na hora do envio bem-sucedido é o que evita o double counting quando a mesma mensagem passa duas vezes. Essa trava é barata de implementar e cara de esquecer.

Faturas parciais e estornos#

O Magento suporta faturamento parcial: um pedido pode ser faturado em partes. Isso complica a definição de conversão, porque cada fatura parcial poderia disparar um evento. A decisão precisa ser explícita — a maioria das lojas considera a conversão pelo valor total do pedido na primeira captura, ou soma as faturas até fechar o pedido, mas nunca conta cada parcial como uma compra nova. Da mesma forma, memos de crédito (os estornos do Magento) representam receita que voltou atrás; escutá-los para disparar um evento de reembolso, ou ao menos registrá-los, mantém a reconciliação com o financeiro honesta.

Múltiplas lojas e escopos de site#

O Magento suporta múltiplas lojas e visões de loja dentro de uma mesma instalação — o conceito de website, store e store view. Uma única instalação pode servir várias marcas ou vários países, cada um com sua moeda, seu idioma e, potencialmente, seu próprio pixel e conta de anúncios. A mensuração precisa respeitar esse escopo. Quando o observer captura o pedido, ele tem acesso ao escopo em que o pedido foi feito — a store view —, e o serviço de conversão deve usar esse escopo para escolher o pixel e o token corretos, além de respeitar a moeda daquele escopo ao montar o valor. Enviar a conversão de uma marca ao pixel de outra, ou reportar o valor na moeda errada, corrompe a atribuição e distorce a otimização de campanha de ambas. A prática correta é manter, na configuração da mensuração, um mapeamento de escopo para pixel, token e moeda, e resolver esse mapeamento a partir do pedido capturado. Como o Magento já carrega o escopo no objeto do pedido, essa resolução é direta e não exige adivinhação. Essa atenção ao escopo é o que permite a uma instalação Magento multi-marca medir cada operação separadamente, com a mesma base de código de mensuração servindo todas as lojas da instalação sem misturá-las.

Validando antes de confiar#

Antes de acreditar em qualquer número, valide de ponta a ponta num ambiente de teste. Coloque um pedido, fature, e acompanhe: o observer capturou, a mensagem entrou na fila, o consumer processou, e o evento chegou à plataforma com valor, itens e correspondência corretos. Use a aba de eventos de teste da Meta e o modo de depuração do GA4 para inspecionar os campos. Teste também o caminho de estorno e o de fatura parcial, para não descobrir em produção que a contagem infla ou que a receita reconhecida não bate.

O Magento recompensa a arquitetura#

O Magento entrega, de fábrica, quase tudo o que um rastreamento server-side maduro pede: eventos para enganchar, observers para capturar, um sistema de filas para desacoplar o envio, e acesso total ao pedido para montar um payload rico. O trabalho é orquestrar essas peças com disciplina — capturar na fatura, enfileirar em vez de chamar direto, montar o payload com dados de correspondência hasheados, unificar o event_id pelo increment id, travar a idempotência e tratar estornos e faturas parciais. Com isso no lugar, a sua mensuração reflete a receita real da loja e resiste tanto à falha de rede quanto à auditoria financeira.