Que produto Lightspeed suporta a ROASaurus?

O Lightspeed eCom (C-Series), através da sua API em api.webshopapp.com (UE) e api.shoplightspeed.com (EUA). O Lightspeed eCom E-Series é um produto separado e não está abrangido por este conector.

Preciso do fragmento da página de agradecimento?

As encomendas são enviadas sem ele, mas o fragmento é a forma mais fiável de associar uma encomenda ao visitante e ao seu clique no anúncio. Sem ele, a ROASaurus só consegue associar por um email indicado antes no site ou por um endereço IP e um navegador únicos.

Porque precisa a ROASaurus 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/. Introduza um dos idiomas da sua loja; a ROASaurus usa nl quando o campo está vazio.

As encomendas por transferência bancária são registadas?

Sim, assim que o Lightspeed define o seu estado de pagamento como paid. O webhook e a verificação de 5 minutos veem ambos a atualização. A Meta rejeita eventos do servidor mais de 7 dias depois de a encomenda ter sido criada, por isso os pagamentos muito tardios não chegam à Meta.

O valor da compra é enviado com ou sem IVA?

Com IVA. A ROASaurus envia o preço da encomenda do Lightspeed com impostos incluídos, por isso divida o ROAS da sua plataforma de anúncios por 1 mais a sua taxa de IVA antes de o comparar com um ROAS de break-even.

A 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, a ROASaurus envia compras para a Meta, o TikTok, o Snapchat, o Pinterest, o Reddit, o X, o Microsoft Ads, a Taboola, o LinkedIn e as outras plataformas de anúncios que ligar.

Tracking de conversões do Lightspeed para lojas online eCom

Pontos-chave

O tracking de conversões do Lightspeed funciona melhor quando cada encomenda paga é enviada a partir dos dados da encomenda do Lightspeed no servidor, com um fragmento na página de agradecimento que associa a encomenda ao clique no anúncio.
A ROASaurus liga-se ao Lightspeed eCom (C-Series) através da sua API nos clusters da UE e dos EUA; o E-Series é um produto separado e não está abrangido.
Um clique em Create webhook regista um webhook de encomendas no Lightspeed, e a ROASaurus verifica também a cada 5 minutos se há encomendas atualizadas, por isso os pagamentos tardios são apanhados.
Só são enviadas as encomendas com o estado de pagamento paid, com o valor do preço da encomenda com impostos incluídos.
As encomendas do Lightspeed incluem o endereço IP e o navegador do comprador, por isso a ROASaurus ainda consegue associar algumas encomendas quando o fragmento da página de agradecimento não correu.

O tracking de conversões do Lightspeed consiste em reportar todas as encomendas pagas da sua loja online Lightspeed eCom a plataformas de anúncios como a Meta e o TikTok, para que possam atribuir o mérito aos anúncios certos e otimizar as suas campanhas. A forma fiável é enviar cada compra a partir dos dados da encomenda do Lightspeed no servidor e acrescentar à página de agradecimento um pequeno fragmento que associa a encomenda ao clique no anúncio.

Este guia explica a que produto Lightspeed se aplica, como as encomendas chegam à ROASaurus, o que é lido em cada encomenda, como as compras chegam à Meta e ao TikTok, a configuração, os testes e os limites que deve conhecer.

Que produto Lightspeed cobre este guia?

A Lightspeed vende mais do que um produto de ecommerce, por isso verifique primeiro o seu. A ROASaurus liga-se ao Lightspeed eCom (C-Series), a plataforma de lojas online cujo back office tem Settings › Website Settings › Web Extras. A sua API corre em dois clusters:

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

A Lightspeed documenta que a API funciona da mesma forma nos dois clusters. Só o endereço difere, por isso a definição da região tem de corresponder à sua loja.

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

A Lightspeed oferece também o eCom (E-Series). A Lightspeed descreve a passagem para o E-Series como uma atualização para um produto separado, atualmente oferecido a certos comerciantes norte-americanos. O conector Lightspeed da ROASaurus lê as encomendas apenas através da API do C-Series, por isso não abrange lojas E-Series.

Porque é que as compras do Lightspeed desaparecem na Meta e no TikTok?

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

Um comprador paga por redirecionamento, por exemplo com iDEAL ou PayPal, e fecha o separador antes de a página de agradecimento carregar.
Um bloqueador de anúncios ou uma definição de privacidade do navegador bloqueia o script do pixel.
O visitante recusa os cookies de marketing, pelo que o pixel não pode carregar.
A encomenda é paga mais tarde, por exemplo por transferência bancária, quando não há navegador envolvido.
O Safari limita o tempo de vida dos cookies criados por scripts, por isso o navegador pode esquecer um clique antigo num anúncio.

Só o pixel do navegador

Precisa que a página de agradecimento carregue
Bloqueado por bloqueadores de anúncios e por alguns navegadores
Não acontece nada quando uma transferência bancária é paga mais tarde
Valor e número da encomenda só se a página for alcançada

Dados da encomenda do Lightspeed

Todas as encomendas com o estado de pagamento paid
Enviado de servidor para servidor, não a partir do navegador
Os pagamentos tardios chegam com a atualização de encomendas seguinte
Valor, produtos e dados do cliente a partir da encomenda

O servidor envia a compra. O fragmento do navegador continua a ser importante, porque associa a encomenda ao visitante que clicou no anúncio.

Como chegam as encomendas do Lightspeed à ROASaurus?

Encomenda atualizadaO Lightspeed chama o endereço de webhook da sua loja

ROASaurusLê a encomenda e os seus produtos a partir da API

Verificação do pagamentoSó continua o estado de pagamento paid

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

O percurso dos dados de cada encomenda. A verificação de 5 minutos segue o mesmo percurso para as encomendas que o webhook não apanhou.

Quando prime Create webhook, a ROASaurus regista no Lightspeed um webhook para o grupo orders e a ação updated, em formato JSON. A partir daí, o Lightspeed chama a ROASaurus sempre que uma encomenda muda.

Porque é que a ROASaurus volta a ler a encomenda

O Lightspeed só acrescenta um cabeçalho x-signature a um webhook quando foi criado por uma app. Um webhook criado com uma simples chave de API, como aqui, não é assinado. Por isso, o endereço do webhook contém um token exclusivo da sua loja, e a ROASaurus não confia no conteúdo recebido. Lê a encomenda e os seus produtos a partir da API do Lightspeed e verifica ela própria o estado de pagamento.

A verificação de 5 minutos

A cada 5 minutos, a ROASaurus pede também ao Lightspeed as encomendas atualizadas desde a sua última verificação, com 30 minutos de sobreposição, e regista as encomendas pagas que ainda não tem. Como esta verificação usa a hora da atualização, uma encomenda paga dias depois de feita é apanhada mesmo que a entrega do seu webhook tenha falhado. As encomendas que a ROASaurus já tem são ignoradas, por isso o webhook e a verificação nunca criam duas compras.

Do lado do Lightspeed, um webhook tem de receber uma resposta 2xx em 5 segundos. As entregas falhadas são repetidas, até 10 tentativas no total, e um webhook cuja taxa de erros se mantenha acima de 50% durante 50 horas é desativado. A verificação de 5 minutos mantém as encomendas a chegar durante uma interrupção destas.

5 minCom que frequência a ROASaurus verifica se há encomendas atualizadas

10Tentativas de entrega por chamada de webhook no Lightspeed

300Pedidos à API por 5 minutos por chave de API (limite do Lightspeed)

O que lê a ROASaurus de uma encomenda do Lightspeed?

Campo do Lightspeed	O que a ROASaurus faz com ele
`number`	O ID da encomenda, por exemplo ORD01042. Torna-se o ID de evento `order-ORD01042`, porque a página de agradecimento mostra o mesmo número.
`paymentStatus`	Só as encomendas pagas são enviadas. As encomendas não pagas, parcialmente pagas e canceladas são ignoradas.
`priceIncl`	O valor da compra, com impostos incluídos. A moeda é a moeda da loja que definiu na ROASaurus.
`createdAt`	A hora do evento
Email, telefone ou telemóvel, nome próprio e apelido	Com hash SHA-256 e enviados como dados do cliente
Cidade, código postal e país de faturação	Com hash e enviados como dados do cliente
`remoteIp`, `userAgent`	Enviados com o evento e usados na associação por IP
ID do cliente	Com hash e enviado como ID externo
Produtos da encomenda	ID da variante (ou ID do produto), quantidade, preço com impostos incluídos, título e SKU

Tudo vem da API do Lightspeed. A ROASaurus só precisa de acesso de leitura às encomendas.

O valor da compra inclui IVA

O priceIncl do Lightspeed é o preço da encomenda com impostos incluídos, e é esse o valor que a ROASaurus envia. As suas plataformas de anúncios reportam, por isso, a receita com IVA incluído. Eis o efeito com 21% de IVA:

Exemplo: 30 encomendas	Valor enviado (com IVA)	Receita sem IVA
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 reportado é 21% superior ao ROAS sobre a receita sem IVA.

Um ROAS de break-even usa a receita sem IVA. Divida o ROAS da plataforma por 1 mais a sua taxa de IVA antes de comparar os dois.

Como é associada uma encomenda do Lightspeed ao clique no anúncio?

Para atribuir o mérito a um anúncio, a plataforma precisa dos identificadores de clique do visitante que encomendou: o ID de clique da Meta e o ID do navegador (fbc, fbp), o ID de clique do TikTok (ttclid) e o cookie do TikTok (ttp). O script da ROASaurus guarda-os para cada visitante quando chega a partir de um anúncio. A ROASaurus não obtém esse ID de visitante a partir da encomenda do Lightspeed, por isso associa cada encomenda a um visitante de outra forma. Tenta três métodos, por esta ordem:

Método	Como funciona	O que precisa
1. Fragmento da página de agradecimento	O fragmento dispara uma compra da ROASaurus com o número da encomenda. A ROASaurus encontra esse evento pelo seu ID de evento, `order-ORD01042`.	O fragmento na caixa Tracking
2. Email anterior	Um email com hash que o visitante indicou antes no seu site, num formulário em popup ou através de uma chamada Identify	Um formulário de subscrição ou uma chamada Identify
3. Endereço IP e navegador	O mesmo endereço IP e navegador vistos desde 3 horas antes até 15 minutos depois da encomenda, só quando corresponde exatamente a um visitante	Nada de extra

O fragmento é o método mais fiável. Os outros dois apanham algumas das encomendas que ele deixa escapar.

O fragmento também transmite o total da encomenda, a moeda e o email do cliente. A ROASaurus guarda no visitante um hash desse email, o que ajuda a associar a encomenda seguinte do mesmo comprador. A ROASaurus espera um pouco antes de enviar cada compra, para que o evento da página de agradecimento possa chegar primeiro, e volta a tentar a associação no momento 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 encomenda foi associada, na coluna Matched by: thank_you, email, ip ou not matched. Uma encomenda não associada vai na mesma para as suas plataformas de anúncios com os dados da encomenda, mas sem identificadores de clique, e a atribuição da ROASaurus mostra-a como direta ou desconhecida.

Enviar as compras do Lightspeed para a Meta e o TikTok

Cada encomenda paga torna-se um evento do servidor por plataforma ligada: um Purchase para a Conversions API da Meta e um CompletePayment para a Events API do TikTok, ambos com o ID de evento order-ORD01042. O TikTok mostra agora o CompletePayment como Purchase nos seus relatórios. Quando marca a opção de carregar também o pixel do navegador, o fragmento da página de agradecimento dispara os mesmos eventos no navegador com o mesmo ID de evento. A Meta e o TikTok guardam então uma só cópia.

Meta: Purchase

ID do evento, hora do evento, valor e moeda
IDs de produto, quantidades e preços
Email, telefone, nome, cidade, código postal e país com hash
Endereço IP e navegador
fbc e fbp quando a encomenda é associada

TikTok: CompletePayment

ID do evento, hora do evento, valor e moeda
Produtos com ID, nome, quantidade e preço
Email e telefone com hash
Endereço IP e navegador
ttclid e ttp quando a encomenda é associada

O que uma encomenda do Lightspeed envia. Ambos os eventos trazem também um ID externo com hash, a partir do ID do cliente ou do ID do visitante.

As mesmas encomendas vão para o Snapchat, o Pinterest, o Reddit, o X, o Microsoft Ads, a Taboola, o LinkedIn e as outras plataformas de anúncios quando as ligar. As conversões de compra do Google Ads são enviadas apenas a partir do checkout do Shopify, por isso a ROASaurus não as envia a partir do Lightspeed. Para a parte da configuração do lado da Meta, consulte o guia da Meta Conversions API.

Como configurar o tracking de conversões do Lightspeed

Adicione a loja na ROASaurus
Vá a Add a store, escolha Lightspeed eCom e introduza o endereço da sua loja. O separador Connection mostra então a sua tag de script e o fragmento da página de agradecimento.
Adicione o script a todas as páginas
No back office do Lightspeed, vá a Settings › Website Settings › Web Extras › Custom JavaScript e cole a tag de script. O Lightspeed executa este código em todas as páginas.
Adicione o fragmento da página de agradecimento
Na mesma página, na área Tracking, ative Status e cole o fragmento. O Lightspeed executa-o na página Thank You depois de uma encomenda.
Crie uma chave de API
Vá a Settings › Store Settings › Developers › New API key. Ative a chave, assinale o acesso de leitura às encomendas, guarde e selecione Show para ver o segredo.
Ligue a API
No separador Connection, introduza a chave, o segredo, a região e o idioma da loja. Guarde, prima Test connection e depois Create webhook.
Ligue as suas plataformas de anúncios
Em Tracking & platforms, use Connect with Facebook ou Add pixel para a Meta e Add pixel para o TikTok, com o código do pixel e um token de acesso da Events API. Assinale a opção de carregar também o pixel do navegador.

Campos do separador 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 da ROASaurus lê a escolha do visitante a partir de 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 os recusar. Enquanto o visitante não aceitar, não tem ID de visitante nem IDs de clique e nenhum pixel do navegador dispara. A encomenda paga continua a ser enviada a partir do servidor, com dados do cliente com hash a partir da encomenda e com o endereço IP e o navegador da encomenda. A página de ajuda sobre consentimento explica os detalhes.

Como testar o tracking de conversões do Lightspeed?

Abra a sua loja com ?roasaurus=connected no endereço. Um alerta confirma que o script está a funcionar. O ?roasaurus=debug regista na consola do navegador o que envia.
No Event log, em Collected events, as visualizações de página devem mostrar um ID de visitante.
Faça uma encomenda e confirme que o seu estado de pagamento é paid. Em Collected events, o Event log deverá então mostrar um Purchase com o número da sua encomenda nos dados. Se não aparecer, verifique se o Status está ativado na área Tracking.
No separador Connection, Last order received mostra a encomenda e Last sync mostra a última verificação de 5 minutos, com qualquer erro do Lightspeed.
Em Server deliveries no Event log, cada plataforma ligada tem uma linha com o estado sent e a resposta da plataforma.

PageView visitor 7d1e04b2Script em todas as páginas

Purchase order-ORD01042Fragmento da página de agradecimento, pixels do navegador disparados

webhook orders updatedEncomenda ORD01042, estado de pagamento paid

Meta Purchase sentAssociada por thank_you

TikTok CompletePayment sentMesmo ID de evento, sem duplicados

Exemplo de uma encomenda de teste saudável. O Fetch orders now no separador Connection executa a verificação de 5 minutos de imediato.

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

Limites e casos particulares

Só C-Series. As lojas Lightspeed eCom E-Series não podem usar este conector.
Só encomendas pagas. Uma encomenda parcialmente paga é enviada quando o seu estado de pagamento passa a paid.
Pagamentos tardios e o limite de 7 dias da Meta. A Meta aceita eventos do servidor até 7 dias depois da hora do evento. A ROASaurus usa a hora de criação da encomenda, por isso uma encomenda paga mais de 7 dias depois de feita é rejeitada pela Meta.
Compras no navegador antes do pagamento. O fragmento da página de agradecimento corre quando a encomenda é feita, por isso os pixels do navegador reportam uma encomenda por transferência bancária antes de ela ser paga. Se o pagamento chegar mais de 48 horas depois, a Meta e o TikTok não conseguem juntar as cópias do navegador e do servidor.
Os cancelamentos e reembolsos não são enviados. Depois de enviada, uma compra fica na plataforma de anúncios.
Apenas visualizações de página, sem código. As visualizações de produtos e as adições ao carrinho são detetadas automaticamente só no Shopify. No Lightspeed, um programador pode enviá-las com uma chamada de tracking tlq.
Limites da API. O Lightspeed permite 300 pedidos por 5 minutos, 3,000 por hora e 12,000 por dia por chave de API. Se outra ferramenta usar a mesma chave, partilham estes limites. O Lightspeed pede que o contacte para obter uma segunda chave.

A página de integração do Lightspeed reúne num só lugar os dados da ligação, e a página de ajuda para outras lojas online compara o Lightspeed com as outras plataformas a que a ROASaurus se liga.

Fontes

Na ROASaurus

Continue a ler

Plataformas de anúncios e lojas onlineTracking de conversões em pagamento contra reembolso e checkouts externosTracking de conversões em pagamento contra reembolso: porque é que os pixels falham as encomendas COD e de checkout externo, quando enviar a compra e como tratar as encomendas recusadas.Plataformas de anúncios e lojas onlineTracking de conversões no CCV Shop: um guia de configuraçãoTracking de conversões no CCV Shop: envie as encomendas pagas para a Meta e o TikTok com um webhook assinado, associe-as aos cliques em anúncios, configure, teste e trate os pagamentos tardios.Plataformas de anúncios e lojas onlineConversões avançadas do Google Ads no ShopifyAs conversões avançadas acrescentam dados de clientes com hash às compras do Google Ads no Shopify. Veja como funcionam, em que diferem das importações offline e como configurar.