Qual produto do Lightspeed o ROASaurus suporta?

O Lightspeed eCom (C-Series), pela API dele em api.webshopapp.com (UE) e api.shoplightspeed.com (EUA). O Lightspeed eCom E-Series é um produto separado e não é coberto por este conector.

Preciso do snippet da página de agradecimento?

Os pedidos são enviados sem ele, mas o snippet é a forma mais confiável de associar um pedido ao visitante e ao clique dele no anúncio. Sem ele, o ROASaurus só consegue associar por um e-mail informado antes no site ou por um endereço IP e navegador únicos.

Por que o ROASaurus precisa do idioma da minha loja?

Os endereços da API do Lightspeed incluem um código de idioma de duas letras, como /nl/ ou /en/. Informe um dos idiomas da sua loja; o ROASaurus usa nl quando o campo está vazio.

Os pedidos por transferência bancária são rastreados?

Sim, assim que o Lightspeed muda o status de pagamento deles para paid. O webhook e a verificação de 5 minutos veem a atualização. O Meta rejeita eventos de servidor com mais de 7 dias depois da criação do pedido, então pagamentos muito tardios não chegam ao Meta.

O valor da compra é enviado com ou sem VAT?

Com VAT. O ROASaurus envia o preço do pedido do Lightspeed com impostos, então divida o ROAS da sua plataforma de anúncios por 1 mais a sua alíquota de VAT antes de compará-lo com um ROAS de equilíbrio.

O ROASaurus envia conversões do Google Ads a partir do Lightspeed?

Não para compras. As conversões de compra do Google Ads são enviadas apenas a partir do checkout do Shopify. A partir do Lightspeed, o ROASaurus envia compras para Meta, TikTok, Snapchat, Pinterest, Reddit, X, Microsoft Ads, Taboola, LinkedIn e as outras plataformas de anúncios que você conectar.

Rastreamento de conversões no Lightspeed para lojas online eCom

Principais conclusões

O rastreamento de conversões no Lightspeed funciona melhor quando cada pedido pago é enviado a partir dos dados de pedidos do Lightspeed, no servidor, com um snippet na página de agradecimento que associa o pedido ao clique no anúncio.
O ROASaurus se conecta ao Lightspeed eCom (C-Series) pela API dele nos clusters da UE e dos EUA; o E-Series é um produto separado e não é coberto.
Um clique em Create webhook registra um webhook de pedidos no Lightspeed, e o ROASaurus também verifica pedidos atualizados a cada 5 minutos, então pagamentos tardios são capturados.
Apenas pedidos com o status de pagamento paid são enviados, com o valor do pedido incluindo impostos.
Os pedidos do Lightspeed incluem o endereço IP e o navegador do comprador, então o ROASaurus ainda consegue associar alguns pedidos quando o snippet da página de agradecimento não rodou.

Rastrear conversões no Lightspeed significa informar às plataformas de anúncios, como Meta e TikTok, cada pedido pago da sua loja online Lightspeed eCom, para que elas possam creditar os anúncios certos e otimizar as suas campanhas. A forma confiável é enviar cada compra a partir dos dados de pedidos do Lightspeed, no servidor, e adicionar um pequeno snippet à página de agradecimento que associa o pedido ao clique no anúncio.

Este guia explica a qual produto do Lightspeed ele se aplica, como os pedidos chegam ao ROASaurus, o que é lido de cada pedido, como as compras chegam ao Meta e ao TikTok, a configuração, os testes e os limites que você deve conhecer.

Qual produto do Lightspeed este guia cobre?

O Lightspeed vende mais de um produto de ecommerce, então confira primeiro o seu. O ROASaurus se conecta ao Lightspeed eCom (C-Series), a plataforma de loja online cujo back office tem Settings › Website Settings › Web Extras. A API dele roda em dois clusters:

Cluster	Endereço da API	Região no ROASaurus
EU1	`api.webshopapp.com`	`eu`
US1	`api.shoplightspeed.com`	`us`

O Lightspeed documenta que a API funciona da mesma forma nos dois clusters. Só o endereço muda, então a configuração de região precisa corresponder à sua loja.

Cada endereço da API também contém um código de idioma de duas letras, por exemplo /nl/ ou /en/. O ROASaurus pede esse código como idioma da loja e usa nl quando você o deixa vazio.

O Lightspeed também oferece o eCom (E-Series). O Lightspeed descreve a mudança para o E-Series como uma migração para um produto separado, atualmente oferecido a certos comerciantes norte-americanos. O conector do ROASaurus com o Lightspeed lê pedidos apenas pela API do C-Series, então não cobre lojas E-Series.

Por que compras do Lightspeed somem no Meta e no TikTok?

Um pixel no navegador só informa uma compra quando o navegador do comprador carrega a página de agradecimento e o script do pixel roda. Isso falha em várias situações comuns:

Um comprador paga por redirecionamento, por exemplo com iDEAL ou PayPal, e fecha a aba antes de a página de agradecimento carregar.
Um bloqueador de anúncios ou uma configuração de privacidade do navegador bloqueia o script do pixel.
O visitante recusa os cookies de marketing, então o pixel não pode carregar.
O pedido é pago depois, por exemplo por transferência bancária, quando nenhum navegador está envolvido.
O Safari limita quanto tempo duram os cookies definidos por scripts, então o navegador pode esquecer um clique em anúncio mais antigo.

Apenas pixel do navegador

Precisa que a página de agradecimento carregue
Bloqueado por bloqueadores de anúncios e por alguns navegadores
Nada acontece quando uma transferência bancária é paga depois
Valor e número do pedido apenas se a página for alcançada

Dados de pedidos do Lightspeed

Todo pedido com status de pagamento paid
Enviado de servidor para servidor, não pelo navegador
Pagamentos tardios chegam com a atualização de pedido seguinte
Valor, produtos e dados do cliente a partir do pedido

O servidor envia a compra. O snippet do navegador continua importante, porque associa o pedido ao visitante que clicou no anúncio.

Como os pedidos do Lightspeed chegam ao ROASaurus?

Pedido atualizadoO Lightspeed chama o endereço de webhook da sua loja

ROASaurusLê o pedido e os produtos dele pela API

Verificação de pagamentoSó o status de pagamento paid continua

Plataformas de anúnciosCompra com ID de evento order-ORD01042

O caminho dos dados de cada pedido. A verificação de 5 minutos segue o mesmo caminho para os pedidos que o webhook perdeu.

Quando você pressiona Create webhook, o ROASaurus registra no Lightspeed um webhook para o grupo orders e a ação updated, em formato JSON. A partir daí, o Lightspeed chama o ROASaurus sempre que um pedido muda.

Por que o ROASaurus lê o pedido de novo

O Lightspeed adiciona um cabeçalho x-signature a um webhook apenas quando um app o criou. Um webhook criado com uma chave de API simples, como aqui, não é assinado. Por isso o endereço do webhook contém um token exclusivo da sua loja, e o ROASaurus não confia no conteúdo recebido. Ele lê o pedido e os produtos dele pela API do Lightspeed e confere o status de pagamento por conta própria.

A verificação de 5 minutos

A cada 5 minutos, o ROASaurus também pergunta ao Lightspeed pelos pedidos atualizados desde a última verificação, com 30 minutos de sobreposição, e registra os pedidos pagos que ainda não tem. Como essa verificação usa o horário da atualização, um pedido pago dias depois de ser feito é capturado mesmo que a entrega do webhook tenha falhado. Os pedidos que o ROASaurus já tem são ignorados, então o webhook e a verificação nunca criam duas compras.

Do lado do Lightspeed, um webhook precisa receber uma resposta 2xx em até 5 segundos. As entregas com falha são repetidas, até 10 tentativas no total, e um webhook cuja taxa de erro fica acima de 50% por 50 horas é desativado. A verificação de 5 minutos mantém os pedidos chegando durante uma lacuna assim.

5 minCom que frequência o ROASaurus verifica pedidos atualizados

10Tentativas de entrega por chamada de webhook no Lightspeed

300Requisições de API por 5 minutos por chave de API (limite do Lightspeed)

O que o ROASaurus lê de um pedido do Lightspeed?

Campo do Lightspeed	O que o ROASaurus faz com ele
`number`	O ID do pedido, por exemplo ORD01042. Ele vira o ID de evento `order-ORD01042`, porque a página de agradecimento mostra o mesmo número.
`paymentStatus`	Só os pedidos pagos são enviados. Pedidos não pagos, parcialmente pagos e cancelados são ignorados.
`priceIncl`	O valor da compra, incluindo impostos. A moeda é a moeda da loja que você definiu no ROASaurus.
`createdAt`	O horário do evento
E-mail, telefone ou celular, nome e sobrenome	Com hash SHA-256 e enviado como dados do cliente
Cidade, código postal e país de cobrança	Com hash e enviado como dados do cliente
`remoteIp`, `userAgent`	Enviados com o evento e usados para a associação por IP
ID do cliente	Com hash e enviado como ID externo
Produtos do pedido	ID da variante (ou do produto), quantidade, preço com impostos, título e SKU

Tudo vem da API do Lightspeed. O ROASaurus precisa apenas de acesso de leitura aos pedidos.

O valor da compra inclui VAT

O priceIncl do Lightspeed é o preço do pedido com impostos, e esse é o valor que o ROASaurus envia. As suas plataformas de anúncios, portanto, informam a receita com VAT incluído. Veja o efeito com 21% de VAT:

Exemplo: 30 pedidos	Valor enviado (com VAT)	Receita sem VAT
Investimento em anúncios	$1,000	$1,000
Valor da compra	$3,630	3,630 ÷ 1.21 = $3,000
ROAS	3.63	3.00

Números ilustrativos. O ROAS informado é 21% maior do que o ROAS sobre a receita sem VAT.

Um ROAS de equilíbrio usa a receita sem VAT. Divida o ROAS da plataforma por 1 mais a sua alíquota de VAT antes de comparar os dois.

Como um pedido do Lightspeed é associado ao clique no anúncio?

Para creditar um anúncio, a plataforma precisa dos identificadores de clique do visitante que fez o pedido: o ID de clique e o ID do navegador do Meta (fbc, fbp), o ID de clique do TikTok (ttclid) e o cookie do TikTok (ttp). O script do ROASaurus os guarda para cada visitante quando ele chega de um anúncio. O ROASaurus não obtém esse ID de visitante a partir do pedido do Lightspeed, então associa cada pedido a um visitante de outra forma. Ele tenta três métodos, nesta ordem:

Método	Como funciona	O que precisa
1. Snippet de agradecimento	O snippet dispara uma compra do ROASaurus com o número do pedido. O ROASaurus encontra esse evento pelo ID de evento, `order-ORD01042`.	O snippet na caixa Tracking
2. E-mail anterior	Um e-mail com hash que o visitante informou antes no seu site, em um formulário de popup ou por meio de uma chamada Identify	Um formulário de inscrição ou uma chamada Identify
3. Endereço IP e navegador	O mesmo endereço IP e navegador vistos de 3 horas antes até 15 minutos depois do pedido, somente quando exatamente um visitante se encaixa	Nada extra

O snippet é o método mais confiável. Os outros dois capturam parte dos pedidos que ele deixa passar.

O snippet também passa o total do pedido, a moeda e o e-mail do cliente. O ROASaurus guarda um hash desse e-mail no visitante, o que ajuda a associar o próximo pedido do mesmo comprador. O ROASaurus espera um pouco antes de enviar cada compra, para que o evento de agradecimento possa chegar primeiro, e tenta a associação de novo na hora do envio.

Variáveis da página de agradecimento

Lightspeed variables used by the ROASaurus snippet (Tracking box)

order.information.number      order id and event id order-<number>
order.information.price_incl  value
order.information.currency    currency
order.customer.email          email, hashed on the visitor

A página Orders mostra como cada pedido foi associado, na coluna Matched by: thank_you, email, ip ou não associado. Um pedido não associado ainda vai para as suas plataformas de anúncios com os dados dele, mas sem identificadores de clique, e a atribuição do ROASaurus o mostra como direto ou desconhecido.

Enviar compras do Lightspeed ao Meta e ao TikTok

Cada pedido pago vira um evento de servidor por plataforma conectada: um Purchase para a Conversions API do Meta e um CompletePayment para a Events API do TikTok, ambos com o ID de evento order-ORD01042. O TikTok agora mostra o CompletePayment como Purchase nos seus relatórios. Quando você marca a opção de carregar também o pixel do navegador, o snippet de agradecimento dispara os mesmos eventos no navegador com o mesmo ID de evento. O Meta e o TikTok então mantêm uma única cópia.

Meta: Purchase

ID do evento, horário do evento, valor e moeda
IDs de produto, quantidades e preços
E-mail, telefone, nome, cidade, código postal e país com hash
Endereço IP e navegador
fbc e fbp quando o pedido é associado

TikTok: CompletePayment

ID do evento, horário do evento, valor e moeda
Produtos com ID, nome, quantidade e preço
E-mail e telefone com hash
Endereço IP e navegador
ttclid e ttp quando o pedido é associado

O que um pedido do Lightspeed envia. Os dois eventos também levam um ID externo com hash, a partir do ID do cliente ou do ID do visitante.

Os mesmos pedidos vão para o Snapchat, o Pinterest, o Reddit, o X, o Microsoft Ads, o Taboola, o LinkedIn e as outras plataformas de anúncios quando você as conecta. As conversões de compra do Google Ads são enviadas apenas a partir do checkout do Shopify, então o ROASaurus não as envia a partir do Lightspeed. Para a configuração do lado do Meta, veja o guia da Conversions API do Meta.

Como configurar o rastreamento de conversões no Lightspeed

Adicione a loja no ROASaurus
Vá em Add a store, escolha Lightspeed eCom e informe o endereço da sua loja. A aba Connection então mostra a sua tag de script e o snippet de agradecimento.
Adicione o script a todas as páginas
No back office do Lightspeed, vá em Settings › Website Settings › Web Extras › Custom JavaScript e cole a tag de script. O Lightspeed executa esse código em todas as páginas.
Adicione o snippet de agradecimento
Na mesma página, na área Tracking, ative o Status e cole o snippet. O Lightspeed o executa na página Thank You depois de um pedido.
Crie uma chave de API
Vá em Settings › Store Settings › Developers › New API key. Ative a chave, marque o acesso de leitura aos pedidos, salve e selecione Show para ver o secret.
Conecte a API
Na aba Connection, informe a chave, o secret, a região e o idioma da loja. Salve, pressione Test connection e depois Create webhook.
Conecte as suas plataformas de anúncios
Em Tracking & platforms, use Connect with Facebook ou Add pixel para o Meta, e Add pixel para o TikTok, com o código do pixel e um token de acesso da Events API. Marque a opção de carregar também o pixel do navegador.

Campos da aba Connection

API key          (Settings › Store Settings › Developers)
API secret       (select Show next to the key)
Region           eu  →  api.webshopapp.com
                 us  →  api.shoplightspeed.com
Shop language    nl, en, de ...  (the code in your API addresses)

Consentimento

Fora do Shopify, o script do ROASaurus lê a escolha do visitante em ferramentas de consentimento comuns: Cookiebot, OneTrust, banners IAB TCF e Google consent mode. Com outro banner de cookies, chame tlq('consent', true) quando o visitante aceitar os cookies de marketing e tlq('consent', false) quando ele os recusar. Enquanto o visitante não aceitar, ele não tem ID de visitante nem IDs de clique, e nenhum pixel do navegador dispara. O pedido pago ainda é enviado do servidor com dados do cliente em hash vindos do pedido e com o endereço IP e o navegador do pedido. A página de ajuda sobre consentimento explica os detalhes.

Como testar o rastreamento de conversões no Lightspeed?

Abra a sua loja com ?roasaurus=connected no endereço. Um alerta confirma que o script está rodando. ?roasaurus=debug registra no console do navegador o que ele envia.
No Event log, em Collected events, as visualizações de página devem mostrar um ID de visitante.
Faça um pedido e confira se o status de pagamento dele é paid. Em Collected events, o Event log deve então mostrar um Purchase com o número do pedido nos dados dele. Se ele estiver faltando, confira se o Status está ativado na área Tracking.
Na aba Connection, Last order received mostra o pedido e Last sync mostra a última verificação de 5 minutos, com qualquer erro do Lightspeed.
Em Server deliveries no Event log, cada plataforma conectada recebe uma linha com o status sent e a resposta da plataforma.

PageView visitor 7d1e04b2Script em todas as páginas

Purchase order-ORD01042Snippet de agradecimento, pixels do navegador disparados

webhook orders updatedPedido ORD01042, status de pagamento paid

Meta Purchase sentMatched by thank_you

TikTok CompletePayment sentMesmo ID de evento, deduplicado

Exemplo de um pedido de teste saudável. Fetch orders now na aba Connection executa a verificação de 5 minutos na hora.

Para ver o evento no Meta, cole o código de Events Manager › Test events no campo Test event code do seu pixel do Meta no ROASaurus e remova-o quando terminar. As configurações do pixel do TikTok no ROASaurus têm o mesmo campo.

Limites e casos extremos

Só C-Series. Lojas Lightspeed eCom E-Series não podem usar este conector.
Só pedidos pagos. Um pedido parcialmente pago é enviado quando o status de pagamento muda para paid.
Pagamentos tardios e o limite de 7 dias do Meta. O Meta aceita eventos de servidor até 7 dias depois do horário do evento. O ROASaurus usa o horário de criação do pedido, então um pedido pago mais de 7 dias depois de ser feito é rejeitado pelo Meta.
Compras no navegador antes do pagamento. O snippet de agradecimento roda quando o pedido é feito, então os pixels do navegador informam um pedido por transferência bancária antes de ele ser pago. Se o pagamento chega mais de 48 horas depois, o Meta e o TikTok não conseguem unir as cópias do navegador e do servidor.
Cancelamentos e reembolsos não são enviados. Depois que uma compra é enviada, ela permanece na plataforma de anúncios.
Apenas visualizações de página, sem código. As visualizações de produto e as adições ao carrinho são detectadas automaticamente apenas no Shopify. No Lightspeed, um desenvolvedor pode enviá-las com uma chamada de rastreamento tlq.
Limites da API. O Lightspeed permite 300 requisições por 5 minutos, 3,000 por hora e 12,000 por dia por chave de API. Se outra ferramenta usa a mesma chave, elas compartilham esses limites. O Lightspeed pede que você entre em contato com eles para obter uma segunda chave.

A página da integração com o Lightspeed reúne os dados da conexão em um só lugar, e a página de ajuda para outras lojas online compara o Lightspeed com as outras plataformas às quais o ROASaurus se conecta.

Fontes

No ROASaurus

Continue lendo

Plataformas de anúncios e lojas onlineRastreamento de conversões com pagamento na entrega e checkouts externosRastreamento de conversões com pagamento na entrega: por que os pixels não enxergam pedidos COD e de checkouts externos, quando enviar a compra e como lidar com pedidos recusados.Plataformas de anúncios e lojas onlineRastreamento de conversões no CCV Shop: um guia de configuraçãoRastreamento de conversões no CCV Shop: envie pedidos pagos para o Meta e o TikTok com um webhook assinado, associe-os aos cliques em anúncios, configure, teste e lide com pagamentos tardios.Plataformas de anúncios e lojas onlineConversões otimizadas do Google Ads no ShopifyAs conversões otimizadas adicionam dados de clientes com hash às compras do Google Ads no Shopify. Como funcionam, como se diferenciam das importações offline e a configuração.