Módulo Magento 2 para recuperação de carrinhos abandonados com funcionalidades de:
- deteção de carrinhos abandonados
- scoring do carrinho com recurso a AI ou heurística
- geração de mensagens de e-mail para recuperação do carrinho
- geração opcional de cupões
- conversas com um assistente de compras AI
- painel de administração e análises
- endpoints REST API e comandos CLI
Visão geral
O módulo ajuda a recuperar carrinhos abandonados no Magento 2 através da deteção de carrinhos inativos, da avaliação da intenção de compra e do envio de mensagens de e-mail com uma ligação segura para restaurar o carrinho. Dependendo da configuração, pode funcionar em dois modos:
- modo
heuristic, sem AI externa - modo
OpenAI, com análise por AI, geração de conteúdo de e-mail e conversas com o assistente
Fluxo de funcionamento típico:
- O cliente adiciona produtos ao carrinho.
- O cliente sai da loja sem realizar a encomenda.
- Após o período de inatividade configurado, o carrinho é assinalado como abandonado.
- O módulo atribui um scoring ao carrinho.
- Se a pontuação for suficientemente elevada, é enviado um e-mail de recuperação.
- O e-mail pode incluir um cupão de desconto e uma ligação para a página do assistente de AI.
- Se o cliente regressar e realizar a encomenda, o carrinho é assinalado como recuperado.
Requisitos
Antes da instalação, certifique-se de que a loja cumpre os seguintes requisitos:
- Magento 2 com acesso a CLI
- cron Magento a funcionar corretamente
- envio de e-mails transacionais configurado no Magento
- HTTPS ativo na storefront
- se for utilizado o modo AI: conta OpenAI API com faturação ativa e chave API
Recomendações operacionais:
- modo de produção para uma loja live
- template de e-mail testado e remetente corretamente configurado
- política de privacidade que contemple a utilização de serviços de AI, se o modo OpenAI estiver ativo
Instalação
* = em produção, utilize a opção --keep-generated
Tipo: Composer
Adicione o repositório Composer à configuração:
composer config repositories.ai.abandoned.cart vcs https://github.com/kowalco/ai-abandoned-cartAdicione o token de acesso ao repositório privado GitHub:
composer config --global --auth github-oauth.github.com Instale o módulo via Composer:
composer require kowal/module-ai-abandoned-cart
Em seguida, execute:
bin/magento module:enable Kowal_AiAbandonedCartbin/magento setup:upgradebin/magento setup:di:compilebin/magento cache:flushChecklist após a instalação
Após a instalação, verifique:
- se o módulo está ativo no Magento
- se o esquema da base de dados foi instalado por
setup:upgrade - se o cron Magento funciona corretamente
- se a loja envia e-mails transacionais
- se a storefront utiliza endereços HTTPS corretos
Comandos úteis de verificação:
bin/magento module:status Kowal_AiAbandonedCartbin/magento cron:runbin/magento cache:flushConfiguração
Magento Admin:
Stores -> Configuration -> Kowal -> AI Abandoned Cart
Páginas de administração:
Marketing -> AI Abandoned Cart
Campos de configuração
Definições mais importantes:
Enable ModuleAtiva ou desativa todo o módulo.Cart Inactivity Threshold (minutes)Define após quantos minutos de inatividade um carrinho ativo deve ser considerado abandonado.AI ProviderValores disponíveis:Heuristic FallbackOpenAI
OpenAI API KeyNecessário apenas quandoAI Providerestá definido comoOpenAI.Minimum Intent ScoreApenas os carrinhos com pontuação igual ou superior a este valor se qualificam para o envio de e-mail de recuperação.Enable Dynamic CouponsAtiva a geração de cupões de utilização única para carrinhos abandonados selecionados.Maximum Coupon DiscountDefine o limite superior do desconto percentual gerado automaticamente.Maximum Failed Email AttemptsDefine quantas tentativas de envio falhadas são permitidas antes de o módulo deixar de repetir o envio.Email Address for Message CopiesDestinatário BCC opcional para mensagens de recuperação.Enable AI Assistant LinkSe a opção estiver ativa, o e-mail de recuperação incluirá uma ligação segura para a página do assistente de AI.Conversation Expiration Time (minutes)Define durante quanto tempo a ligação para o assistente de AI permanece válida.Batch SizeDefine quantos carrinhos são processados numa única execução de deteção, scoring e envio de e-mails.Cart Analysis PromptUtilizado quando o scoring por AI está ativo.Email Generation PromptUtilizado para gerar o conteúdo das mensagens de e-mail no modo AI.Conversation PromptUtilizado pelo assistente de AI durante a conversa com o cliente.
Configuração inicial recomendada
Para começar, um conjunto seguro de definições é:
Enable Module:YesCart Inactivity Threshold (minutes):30AI Provider:Heuristic FallbackouOpenAIMinimum Intent Score:0.45Enable Dynamic Coupons:YesMaximum Coupon Discount:5Maximum Failed Email Attempts:3Enable AI Assistant Link:YesConversation Expiration Time (minutes):1440Batch Size:100
Modo Heuristic vs modo OpenAI
Modo Heuristic
Utilize este modo se quiser começar sem integração com AI externa.
Neste modo, o módulo:
- deteta carrinhos abandonados
- calcula o intent score com base em regras de negócio integradas
- envia e-mails de recuperação
- pode gerar cupões
- pode continuar a disponibilizar a página do assistente, mas as respostas serão baseadas na lógica integrada em vez de no OpenAI
Modo OpenAI
Utilize este modo se pretender uma maior personalização.
Neste modo, o módulo pode ainda:
- analisar o contexto do carrinho com recurso ao OpenAI
- gerar conteúdo de e-mail mais personalizado
- gerir conversas com o assistente de AI sobre produtos do carrinho
- utilizar descrições de produtos, produtos relacionados, up-sell e cross-sell nas respostas
Configuração do OpenAI
Para ativar o modo OpenAI:
- Crie uma chave API na conta OpenAI Platform.
- No Magento Admin, aceda a
Stores -> Configuration -> Kowal -> AI Abandoned Cart. - Defina
AI ProvidercomoOpenAI. - Cole a chave no campo
OpenAI API Key. - Guarde a configuração.
- Limpe a cache do Magento.
Informações importantes:
- as subscrições ChatGPT e a faturação API são coisas separadas
- a utilização da API é cobrada de forma independente pela OpenAI
- no modo AI, o prompt e o contexto do carrinho são enviados para a OpenAI
Cron Jobs
O módulo utiliza crons do Magento para processamento automático.
Tarefas cron configuradas:
kowal_ai_abandoned_cart_detectkowal_ai_abandoned_cart_scorekowal_ai_abandoned_cart_email
O que fazem:
detect: procura carrinhos inativos que se qualificam como abandonadosscore: calcula o intent score e o reason codeemail: envia e-mails de recuperação e guarda registos
Se o cron Magento não estiver a funcionar, o módulo não processará carrinhos automaticamente.
Primeiro teste após a configuração
Após a instalação e configuração, realize um teste end-to-end completo:
- Abra a storefront como cliente não autenticado.
- Adicione um ou vários produtos ao carrinho.
- Inicie o checkout e introduza o endereço de e-mail.
- Saia do checkout sem realizar a encomenda.
- Aguarde até passar o limite de inatividade configurado.
- Execute o cron ou os comandos CLI manualmente.
- Confirme que o carrinho apareceu no painel de administração.
- Confirme que o e-mail de recuperação foi enviado.
- Abra a ligação de restauro do carrinho a partir da mensagem.
- Se a opção estiver ativa, abra a ligação para o assistente de AI e envie uma mensagem de teste.
Sequência CLI manual:
bin/magento kowal:ai:cart:detectbin/magento kowal:ai:cart:scorebin/magento kowal:ai:cart:send-emailsPáginas de administração
O módulo adiciona páginas de administração dedicadas em:
Marketing -> AI Abandoned Cart
Secções disponíveis:
DashboardVisão geral dos carrinhos detetados e recuperados.Recovery AnalyticsEstatísticas de eficácia da recuperação e métricas operacionais.ConversationsHistórico de conversas com o assistente de AI associadas a carrinhos abandonados.Email LogsRegisto de mensagens de recuperação enviadas e falhadas.
Estas páginas são especialmente úteis durante a implementação, pois permitem verificar se a deteção, o scoring, o envio de e-mails e o acompanhamento dos carrinhos recuperados funcionam corretamente.
Conteúdo dos e-mails e experiência do cliente
Cada e-mail de recuperação pode incluir:
- assunto personalizado
- conteúdo próprio da mensagem
- resumo dos produtos do carrinho
- valor do carrinho
- ligação segura para restaurar o carrinho
- cupão de desconto opcional de utilização única
- ligação opcional para o assistente de AI
Percurso do cliente:
- O cliente recebe um e-mail.
- O cliente clica na ligação de restauro e regressa ao carrinho guardado.
- O cliente pode, opcionalmente, abrir a página do assistente a partir da mensagem.
- O assistente pode responder a perguntas sobre produtos, comparar opções e encaminhar o cliente de volta para o checkout.
Como funcionam os cupões
Se os cupões dinâmicos estiverem ativos, o módulo pode gerar um cupão quando:
- o valor do carrinho é suficientemente elevado
- o intent score sugere que um desconto pode ajudar
- o desconto calculado não excede o máximo configurado
Regras integradas atuais:
- carrinhos abaixo de 100 unidades da moeda da loja não recebem cupão
- carrinhos com intent score elevado não recebem cupão
- carrinhos com menor intenção podem receber um desconto, normalmente 3% ou 5%, limitado pela configuração
Os cupões gerados são:
- de utilização única
- limitados por cliente
- associados a uma regra de carrinho partilhada do Magento para o nível de desconto e loja em questão
CLI
Pode executar o módulo manualmente a partir da CLI, especialmente durante testes e diagnósticos.
bin/magento kowal:ai:cart:detectbin/magento kowal:ai:cart:scorebin/magento kowal:ai:cart:send-emailsSignificado dos comandos:
kowal:ai:cart:detectDeteta carrinhos abandonados.kowal:ai:cart:scoreAtribui scoring e reason code aos carrinhos.kowal:ai:cart:send-emailsEnvia mensagens de recuperação para carrinhos qualificados.
Segurança
As ligações para restaurar o carrinho e para o assistente utilizam tokens assinados.
O payload do token contém:
quote_idemailstore_idexpires_at
O token é validado através de:
- verificação da assinatura
- verificação da data de expiração
- verificação da propriedade do carrinho
Assim, o cliente recebe uma ligação segura associada a um carrinho específico e limitada no tempo.
Resolução de problemas
Os carrinhos não são detetados
Verifique:
- se o quote ainda está ativo
- se o carrinho contém produtos
- se o quote não tem uma encomenda concluída associada
- se o endereço de e-mail do cliente foi capturado
- se o limite de inatividade já passou
- se o cron Magento está a funcionar
Os carrinhos são detetados, mas os e-mails não são enviados
Verifique:
- se
Enable Moduleestá ativo - se
Minimum Intent Scorenão está definido demasiado alto - se o envio de e-mails funciona no Magento
- se o limite
Maximum Failed Email Attemptsnão foi atingido - se o endereço de e-mail atribuído ao carrinho está correto
O modo OpenAI está ativo, mas o resultado da AI não é utilizado
Verifique:
- se
AI Providerestá definido comoOpenAI - se
OpenAI API Keyestá corretamente preenchido - se o servidor permite ligações de saída para a API OpenAI
- se a conta OpenAI tem faturação ativa
Se a chamada OpenAI falhar, o módulo muda para o comportamento heurístico integrado.
A ligação para o assistente de AI abre, mas as respostas são genéricas
Verifique:
- se o modo OpenAI está ativo
- se o prompt de conversa está corretamente configurado
- se a ligação ainda está válida e não expirou
Notas para utilização em produção
Antes de lançar em produção, recomenda-se:
- verificar o conteúdo das mensagens de e-mail e o branding
- testar a política de cupões com regras de negócio reais
- verificar os requisitos de privacidade e compliance
- testar os prompts de AI no catálogo e no tom de comunicação da loja
- monitorizar os primeiros dias de funcionamento em
Dashboard,ConversationseEmail Logs
Informações necessárias ao submeter um pedido de suporte
Ao reportar um problema, prepare:
- versão do Magento
- versão do PHP
- modo da loja: developer ou production
- informação sobre se o cron está a funcionar
- informação sobre se o problema ocorre no modo
heuristicouOpenAI - exemplo de quote ID ou endereço de e-mail do cliente afetado pelo problema
- entradas relevantes dos registos de exceções ou dos registos de sistema do Magento



























