Magic Link na Nuvemshop: Como Funciona a Aplicação de Cupom no Checkout
Divulgação e Aplicação do Cupom
Ao divulgar apenas um código, o comprador precisa lembrar ou copiar o texto e aplicá-lo no carrinho ou checkout. Essa etapa pode gerar dúvidas, erros de digitação ou uma busca por outro desconto.
Código e URL podem circular além da campanha. Um pedido com cupom não comprova que o cliente viu o anúncio nem que comprou por causa do incentivo. Esse limite está discutido em cupons divulgados em sites de desconto.
A Nuvemshop também oferece aplicação automática por link nativo. A comparação com Magic Link separa esse recurso dos controles de URL e do relatório do app.
A Arquitetura: Link Público e Token Temporário
O Magic Link separa a URL divulgada da tentativa de aplicação no checkout. Quando a aplicação funciona, a pessoa não precisa digitar o cupom; em falha ou conflito, pode receber um código copiável.
Link Público e Token de Checkout
O Magic Link público é a URL estável que você compartilha, inclusive em links sem expiração. Quando o destino está no domínio da loja, o painel copia esse destino com o parâmetro magiclink:
https://sualoja.com.br/produto?magiclink={public-token}
O endereço https://magiclink.nexopath.com/go/{public-token} continua disponível como link alternativo e é a única forma quando o destino fica fora do domínio da loja.
Esse link público aponta para um destino e tem sua configuração guardada no servidor:
- Código do cupom — o cupom criado como percentual no Magic Link ou um existente, cujas regras permanecem inalteradas.
- Expiração opcional (em Opções avançadas) — data/hora após a qual o link fica Expirado; sem essa regra, ele pode ser permanente.
- Limite de cliques opcional (em Opções avançadas) — número máximo de acessos permitidos; ao alcançá-lo, o link fica Esgotado. Sem limite, ele pode receber cliques ilimitados.
Ao acessar o link alternativo /go, a pessoa é redirecionada para o destino com um token temporário de checkout:
https://loja.com.br/produto?ml={redeem-token}
O redeem-token é um identificador opaco e temporário, válido por aproximadamente 90 minutos. Ele não carrega nem define a expiração ou o limite de cliques da campanha: essas regras pertencem ao Magic Link público e continuam no servidor.
Na forma com o domínio da loja não há redirecionamento: o app da loja lê magiclink, o link é validado no servidor e o app recebe o mesmo tipo de token temporário. A partir daí, o fluxo é o mesmo.
O Magic Link é uma URL compartilhável: qualquer pessoa que a receba pode acessá-la enquanto estiver ativa e dentro das regras configuradas. Um link com expiração de 7 dias fica Expirado no dia 8; um link com limite de 500 cliques fica Esgotado depois de atingir o limite. O cupom subjacente (FRETE10) continua existindo na Nuvemshop, mas o Magic Link tenta aplicá-lo apenas quando há um redeem-token válido.
Captura do Token no Storefront
Na integração atual via NubeSDK, o app lê ml da URL (ou obtém o token a partir de magiclink) e guarda um registro do token no asyncLocalStorage para a navegação até o checkout. Sua validade é verificada pelo backend no checkout.
O código roda em Web Worker, sem acesso direto ao DOM ou ao armazenamento da página. As Browser APIs oficiais do NubeSDK oferecem armazenamento assíncrono; o Magic Link usa nube.getBrowserAPIs().asyncLocalStorage. A validade do token no servidor é de aproximadamente 90 minutos, independente das regras do link público.
Tentativa de Aplicação no Checkout via NubeSDK
Quando o comprador chega ao checkout, o fluxo atual é:
- No evento
checkout:ready, o app recupera o registro do token e verifica o cupom já presente no carrinho. - Consulta
GET /api/redeem/preview?token={redeem-token}&channel=ml, sem consumir o token. - O backend verifica validade e uso do token, vínculo entre token, link e loja, canal correto, link ativo e acesso válido ao app.
- Se puder prosseguir, o app envia
coupon:addcom o código. Um cupom diferente já aplicado não é sobrescrito. - Após confirmar que o cupom foi aplicado, registra essa confirmação e solicita o consumo do token em
POST /api/redeem, com token e canal. Uma falha nessa confirmação ao backend pode ser retomada no checkout.
Expiração e limite de cliques do link são verificados no acesso à URL pública, antes da emissão do token. A consulta no checkout não repete esses dois controles: um token emitido no último clique permitido não se torna inválido apenas porque a URL ficou Esgotada.
Falha na aplicação pode gerar uma alternativa copiável; não há promessa de nova tentativa automática para toda falha. Aplicar o cupom ou consumir o token não confirma pedido nem pagamento.
Quando a aplicação funciona, o comprador vê o desconto no resumo sem precisar digitar o código. Se houver conflito ou falha na aplicação automática, o app pode mostrar um código copiável como alternativa.
Regras de Acesso e Validação
Regras da URL — expiração e limite de cliques são opcionais. Links sem esses limites podem continuar ativos.
Limites separados — duas URLs podem ter limites de cliques diferentes mesmo usando o mesmo cupom. Isso organiza a divulgação, como em links para influenciadores, sem separar suas vendas no relatório por cupom. Para ver vendas por link, dê a cada link um cupom próprio.
Validação no servidor — tokens inexistentes, vencidos ou consumidos são rejeitados. Vínculos de loja, canal, atividade e acesso ao app também são verificados. As condições do cupom continuam sendo validadas pela Nuvemshop; desativar ou expirar um link não desativa o cupom.
Comparação: Fluxo Manual vs. Magic Link
| Aspecto | Cupom Manual | Magic Link |
|---|---|---|
| Input do usuário no checkout | Digitar código + clicar “Aplicar” | Tentativa automática; código copiável pode aparecer em caso de falha ou conflito |
| Risco de vazamento | Código pode ser compartilhado | A URL é compartilhável; regras opcionais podem limitar sua vigência ou cliques |
| Relatório disponível | Cupom registrado no pedido da loja | Contadores por link e Cliques, Pedidos e Valor pago por cupom; sem atribuição individual |
| Dependência de GTM | Não é requisito para usar um cupom normal | Não é requisito para a tentativa via NubeSDK |
Cliques por Link e Resultados por Cupom
Como cada campanha usa um link próprio, o painel do Nexopath mostra, por link:
- Cliques — quantos acessos o link recebeu.
- Status — Ativo, Desativado, Esgotado (limite de cliques atingido) ou Expirado (data de expiração passada).
Isso permite comparar cliques, inclusive acessos repetidos. O relatório reúne Cliques, Pedidos e Valor pago por cupom: uso manual também conta, e links com o mesmo código compartilham as vendas; com um cupom próprio por link, as vendas ficam separadas. Consulte as definições de período e pagamento, sem interpretar esses dados como atribuição individual ou lucro. Links comuns são administrados no Magic Link; links de parceiros são administrados no Parceiros e já fazem parte da assinatura desse app, com o domínio da loja por padrão. Para recuperação de carrinho via WhatsApp e CRM, veja Automações de WhatsApp com Cupom Tentado no Checkout.
Limitações
- Checkout headless — lojas com checkout totalmente customizado (headless, fora da Nuvemshop) não usam NubeSDK. O Magic Link funciona apenas com o checkout nativo da Nuvemshop.
- Cupom já aplicado — se já houver um cupom diferente no carrinho, o Magic Link não o sobrescreve e pode mostrar um código copiável como alternativa.
- Sem token guardado — se alguém chega à loja sem passar por um link com
?ml=ou?magiclink=(ou depois de o TTL expirar), não há token noasyncLocalStoragee o app não tenta aplicar o cupom. Acesse a URL pública para iniciar uma nova tentativa com token válido.
Próximo Passo
O Nexopath Magic Link está na Nuvemshop App Store. O teste grátis de 14 dias permite criar links. Autorize os recursos de criação de cupons e leitura de pedidos quando necessário; depois configure a oferta e use a URL gerada na divulgação.