Instalação
Requisitos
Magento 2.4.x — testado na 2.4.9, compatível com versões 2.4.* anteriores. PHP 8.1–8.5. Compatível tanto com o tema Luma predefinido como com o tema Hyvä. Requer a presença dos módulos nativos Magento_ReCaptcha* para a proteção reCAPTCHA opcional (já incluídos no core do Magento).
Passos de configuração
- Adicione as credenciais que receberá por email a
auth.jsonna raiz do seu projeto Magento:{ "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } } composer config repositories.codingrow composer https://repo.codingrow.comcomposer require codingrow/module-withdrawal-buttonbin/magento module:enable Codingrow_WithdrawalButtonbin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush- Cole a sua chave de licença em Admin → Stores → Configuration → Codingrow Extensions → Withdrawal Button → License → License Key, guarde e depois
bin/magento cache:flush. - Coloque o link de pedido onde os clientes o consigam encontrar — veja Colocar o widget abaixo.
Todo o formulário frontend, os emails e a interface de administração estão disponíveis em 7 idiomas, selecionados automaticamente de acordo com o idioma da loja/administração:
Configuração admin
A configuração completa está em Stores → Configuration → Codingrow Extensions → Withdrawal Button: Licença, Geral (ativação, email de notificação, estados de encomenda elegíveis, prazo de desistência, texto/cores do botão, campos personalizados), Modelos de email e a etiqueta de devolução opcional.
Desinstalação
composer remove codingrow/module-withdrawal-button depois
bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush.
Os pedidos já registados em codingrow_withdrawalbutton_request nunca são
eliminados automaticamente — exporte primeiro a grelha se precisar de manter um registo.
Guia de utilizador
A página de pedido de desistência
Uma página, dois passos, exatamente como exigido pela diretiva de referência: o cliente preenche primeiro os campos fixos (nome, email, número de encomenda, data de receção) mais quaisquer campos personalizados ativados, vê um resumo apenas de leitura de tudo o que foi inserido, e só então confirma num botão final separado. Os campos ocultos que transportam os dados entre os dois passos são revalidados no servidor na confirmação — um cliente nunca pode contornar as verificações forçando diretamente o passo "confirmado".
Verificação da encomenda
Antes de aceitar um pedido, o módulo verifica que o número de encomenda realmente existe e que o endereço de email corresponde ao dessa encomenda (sem distinção entre maiúsculas/minúsculas, funciona tanto para encomendas de convidado como de cliente registado). Se qualquer uma das verificações falhar, é mostrada em ambos os casos a mesma mensagem genérica de "não encontrado" — isto é deliberado: revelar "email incorreto" em vez de "a encomenda não existe" permitiria testar números de encomenda válidos por tentativa e erro.
Status do pedido e prazo de desistência
Duas configurações em Stores → Configuration → Codingrow Extensions → Withdrawal Button → General controlam quais solicitações são aceitas, além da verificação obrigatória de pedido/email descrita acima.
- Order statuses eligible for withdrawal — uma seleção múltipla nativa do Magento (Pending / Processing / Complete / Closed / Canceled / On Hold). Uma solicitação só é aceita se o status atual do pedido for um dos selecionados; pré-selecionados na instalação em Pending, Processing, Complete, Closed e On Hold. Deixar a lista vazia bloqueia todas as solicitações independentemente do status do pedido — uma escolha deliberada do lojista, não um bug.
- Withdrawal period (days) — quantos dias são permitidos entre a data de receção declarada e o momento em que a solicitação é enviada (14 por padrão, o mínimo previsto pela legislação da UE sobre desistência). Passado esse prazo, a solicitação é rejeitada com uma mensagem que convida o cliente a contatar diretamente a loja; a coluna de dias decorridos na grelha de administração assinala as solicitações que ultrapassam esse mesmo limite.
Prevenção de pedidos duplicados
Uma encomenda só pode ter um pedido de desistência ativo, independentemente do seu estado — mesmo um "Rejeitado". Um cliente que discorde de uma rejeição não pode simplesmente reenviar o mesmo pedido para a contornar; se for necessária uma exceção real, o administrador elimina primeiro o pedido anterior da grelha.
Data de receção e dias decorridos
O prazo de desistência (configurável, 14 dias por padrão) começa a partir do momento em que os bens foram recebidos, não da data de compra ou fatura — uma informação que o Magento não tem forma de conhecer por si só, uma vez que depende da transportadora. O formulário pede-a através de um seletor de data HTML5 nativo (sem dependência de jQuery UI que pudesse entrar em conflito com um tema), limitado para que não se possa inserir uma data futura. A data da encomenda é lida automaticamente a partir da encomenda associada — o cliente nunca precisa de a digitar. Ambas as datas, mais os dias decorridos desde a receção, são mostradas na grelha de administração (assinaladas após esse prazo) e disponíveis como variáveis de email.
Construtor de campos personalizados
Além dos quatro campos exigidos por lei (nome, email, número de encomenda, data de receção — sempre obrigatórios, nunca removíveis), pode adicionar um número ilimitado de campos próprios em Stores → Configuration → Codingrow Extensions → Withdrawal Button → Custom Fields: etiqueta, tipo, se é obrigatório, e se está atualmente mostrado no formulário — a ordem das linhas nessa lista é a ordem de visualização no formulário.
| Tipo | Apresentado como |
|---|---|
| Texto | Campo de uma linha |
| Área de texto | Caixa multilinha |
| Lista pendente | Um <select> com as opções digitadas, uma por linha |
| Caixa de verificação | Uma única caixa (ex.: "Ainda tenho a embalagem original") |
Os valores submetidos para um campo que é posteriormente desativado permanecem no histórico do pedido e continuam a ser mostrados onde foram registados — apenas a etiqueta do campo é recalculada por ID, pelo que renomear um campo mais tarde atualiza a etiqueta em todos os locais onde as suas respostas antigas também são mostradas.
Cores e texto do botão
Dois campos de cor hexadecimal (texto e fundo) permitem adaptar o botão à sua marca — só as cores mudam; a forma, o padding e o tipo de letra mantêm-se sempre os do seu tema (Luma ou Hyvä), pelo que o botão nunca pode ficar visualmente danificado. Um valor hexadecimal inválido é simplesmente ignorado, voltando à cor predefinida do tema. O texto do botão também é configurável, mostrado exatamente como escrito (maiúsculas/minúsculas preservadas, sem capitalização automática) — deixe-o vazio para manter a etiqueta traduzida predefinida.
Proteção reCAPTCHA
O Withdrawal Button regista-se como formulário protegível no sistema reCAPTCHA nativo do Magento — Stores → Configuration → Customers → Google reCAPTCHA → Storefront → "Enable for Withdrawal Button". A versão já configurada para o resto da loja (v2 caixa de verificação, v2 invisível, ou v3) aplica-se automaticamente; não existe nenhuma configuração de captcha separada a manter.
Grelha de administração e ações em massa
Cada pedido chega a Codingrow Extensions → Withdrawal Button, paginado e filtrável, com colunas para número de encomenda, cliente, data de receção, dias decorridos (assinalados após 14), valores dos campos personalizados e estado. As ações em massa permitem atualizar o estado de vários pedidos selecionados de uma vez, ou eliminar linhas para limpar dados de teste.
| Estado | Significado |
|---|---|
| Pendente | Acabado de submeter, ainda não revisto. |
| Em processamento | A ser tratado pela loja. |
| Concluído | Devolução/reembolso terminado. |
| Rejeitado | A loja recusou o pedido. |
| Cancelado | O cliente retirou o seu próprio pedido. |
Modelos de email e variáveis
Dois modelos de email nativos do Magento — um recibo ao cliente (a confirmação em suporte
duradouro exigida por lei) e uma notificação interna ao administrador — enviados
automaticamente através de TransportBuilder, exatamente como os próprios emails
de encomenda do Magento. Clone qualquer um dos dois a partir de Marketing → Email
Templates, edite o texto com o editor WYSIWYG nativo, e depois selecione a sua cópia
em Configuration → Email Templates — sem envolver código de templating
personalizado.
| Variável | Conteúdo |
|---|---|
order_increment_id | O número da encomenda |
order_date | A data da própria encomenda, lida automaticamente |
receipt_date | A data em que o cliente declarou ter recebido a mercadoria |
days_since_receipt | Dias decorridos desde essa data |
request_id | Número de referência interno deste pedido |
submitted_at | Data e hora exatas em que o pedido foi confirmado |
custom_fields_text | Todos os campos personalizados preenchidos, formatados como linhas "Etiqueta: valor" |
Etiqueta de devolução em PDF
Um simples talão opcional (logótipo, nome do remetente, morada de devolução, instruções de
embalagem) gerado internamente com Zend_Pdf — a mesma biblioteca PDF que o
próprio core do Magento usa para faturas e envios, sem qualquer dependência de terceiros
adicionada — e anexado automaticamente ao email de receção do cliente uma vez ativado em
Configuration → Return Label. Carregue um logótipo, preencha a morada de
devolução e quaisquer instruções de embalagem, e todos os futuros emails de confirmação de
pedido trarão uma etiqueta pronta a imprimir com o número de referência, número de encomenda,
nome do cliente e data de receção desse pedido, além de quaisquer campos personalizados preenchidos pelo cliente.
Colocar o widget
O link de pedido nunca é fixado diretamente no tema — é colocado exclusivamente através do sistema nativo de Widgets do Magento, para que o lojista controle totalmente se, e onde, aparece. Duas formas de o fazer, consoante o alcance com que quer que seja mostrado:
| Método | Ideal para |
|---|---|
| Content → Elements → Widgets | Mostrar o link em muitas/todas as páginas de uma vez, ou numa posição fixa do layout (rodapé, barra lateral) em todo o site. |
| Insert Widget dentro do conteúdo de uma página CMS | Colocá-lo numa única página específica — por ex. a página inicial — exatamente onde quiser dentro do conteúdo dessa página, sem afetar as outras. |
Em todo o site, através de Content → Elements → Widgets:
- Content → Elements → Widgets → Add Widget, escolha o widget de link do Withdrawal Button.
- Atribua-o a "All Pages" ou "Specified Page(s)" e defina o contentor de visualização (ex.:
contentousidebar.additional) — em temas Hyvä, o contentor "Footer" pode não estar disponível no seletor de widgets; nesse caso use a área de conteúdo principal, mesmo antes do rodapé. - Guarde e recarregue a(s) página(s) de destino — não é necessário limpar a cache para uma instância de widget recém-guardada.
Apenas numa página específica, por ex. a página inicial:
- Content → Pages, abra a página (ex.: "Home page").
- No editor WYSIWYG do separador Content, coloque o cursor onde quer o botão e clique em Insert Widget.
- Escolha o widget de link do Withdrawal Button, defina o texto da etiqueta e a classe CSS, e depois Insert — isto insere uma diretiva
{{widget type="Codingrow\WithdrawalButton\Block\Widget\Link" ...}}diretamente no conteúdo dessa página, sem afetar as outras. - Guarde a página.
Licença
Sem uma chave de licença válida, a página de desistência permanece visível (um lojista nunca deve ficar sem o botão legalmente exigido apenas porque uma licença expirou) mas os novos envios são bloqueados até que seja introduzida uma chave em Configuration → License → License Key.