Product Return Manager: guia completo
Guia completo: instalação, configuração, percurso do cliente, leitura de QR, estatísticas e integrações.
O DataFirefly Product Return Manager transforma a gestão de devoluções do PrestaShop 8 num fluxo automatizado de ponta a ponta: pedido do cliente em autosserviço (conta de cliente ou convidado), etiqueta em PDF com código QR, validação por leitura à receção, estatísticas em 13 eixos, vale de compra ou reembolso, devolução manual pelo administrador, tradução automática das razões através do ChatGPT e integração com ERP através de hook. Esta documentação cobre a instalação, a configuração completa e a utilização diária.
Prazo legal em Portugal. O prazo de devolução configurável no módulo é uma política comercial sua e não substitui o direito de livre resolução previsto no Decreto-Lei n.º 24/2014, que dá ao consumidor 14 dias a contar da receção do bem, sem necessidade de justificação. Se definir 30 dias, está a oferecer mais do que a lei exige, o que é perfeitamente possível. O que não pode é ficar abaixo dos 14 dias legais nem exigir uma razão para os exercer. As razões de devolução recolhidas pelo módulo servem para análise interna, não como condição de aceitação.
Instalação
Instalação normal do PrestaShop: vá a Módulos → Gestor de módulos → Carregar um módulo, selecione o ficheiro dfproductreturn.zip e confirme. O módulo cria automaticamente 9 tabelas com os prefixos df_return_* e df_product_return*, instala razões de devolução predefinidas, regista os seus hooks (displayCustomerAccount, displayMyAccountBlock, displayHeader, entre outros) e acrescenta duas entradas de menu ao back-office: Devoluções de produtos (gestão) e Estatísticas de devoluções.
Pré-requisitos: PrestaShop 8.0 a 8.99, PHP 8.0 a 8.3. O PrestaShop 1.7 não é suportado. A multiloja é gerida nativamente. A atualização a partir de uma versão anterior é idempotente (scripts de atualização incluídos, entre os quais a adição da coluna manual_amount na 1.7).
Configuração
Vá a Módulos → Gestor de módulos → DataFirefly Product Return Manager → Configurar. Definições principais:
- Prazo de devolução (dias): janela durante a qual o cliente pode pedir uma devolução depois da encomenda. 30 dias por predefinição. Só se aplica às devoluções iniciadas pelo cliente; a devolução manual pelo administrador ignora este prazo.
- Estados de encomenda elegíveis: só as encomendas nestes estados mostram o botão «Pedir uma devolução» (tipicamente «Entregue»).
- Ativar o vale de compra: propõe a opção de vale de compra como forma de compensação.
- Ativar o reembolso: propõe a opção de reembolso no meio de pagamento de origem.
- E-mail do administrador: endereço notificado a cada novo pedido de devolução.
- Estado de reembolso parcial / total: os dois estados de encomenda aplicados consoante o tipo de reembolso efetuado.
- Chave API da OpenAI: necessária apenas para a tradução automática das razões de devolução através do ChatGPT (ver a secção dedicada).
O Decreto-Lei n.º 24/2014 prevê o reembolso no mesmo meio de pagamento usado pelo consumidor, salvo acordo expresso deste. Um vale de compra só pode, por isso, ser proposto como alternativa que o cliente aceita, nunca imposto como única compensação numa livre resolução.
Razões de devolução e categorias
O módulo organiza as razões em dois níveis: categorias («Problema com o produto», «Problema logístico», «Mudança de ideias») e razões associadas a cada categoria («Tamanho incorreto», «Artigo com defeito», «Entrega demasiado demorada»). Esta hierarquia alimenta as estatísticas: vê a repartição macro por categoria e depois o detalhe por razão.
Faça a sua gestão no separador Razões da configuração: criação, edição, desativação e ordem de apresentação. São instaladas razões predefinidas com o módulo, que deve adaptar ao seu catálogo.
Boas práticas: mantenha-se abaixo de 10 razões visíveis por categoria, para não afogar o cliente, e formule as razões do ponto de vista dele («O artigo não corresponde à fotografia» em vez de «Não conformidade visual»).
Tradução automática através do ChatGPT
Depois de indicar a sua chave API da OpenAI na configuração, aparece um botão Traduzir em cada razão e categoria. Um clique traduz a designação para todos os idiomas ativos da loja, com vocabulário de comércio eletrónico contextualizado. As traduções continuam editáveis manualmente depois de geradas. Obtenha a sua chave em platform.openai.com: o custo por tradução é negligenciável (frações de cêntimo).
Releia as razões traduzidas para o português: confirme que saem em português europeu e que o vocabulário corresponde ao do seu setor antes de as deixar visíveis para o cliente.
Percurso do cliente (com conta)
O cliente com sessão iniciada vê uma ligação «As minhas devoluções» na sua área de cliente. Para iniciar uma devolução:
- Abre a encomenda elegível e clica em «Pedir uma devolução».
- Assinala os produtos a devolver e ajusta as quantidades.
- Escolhe uma categoria de razão, depois uma razão específica, e acrescenta um comentário opcional.
- Confirma: a devolução passa ao estado «Pendente» e são enviados dois e-mails, a confirmação ao cliente com o PDF da etiqueta em anexo e a notificação ao administrador.
O cliente acompanha depois o estado da sua devolução (pendente, aceite, recusada, reembolsada) em «As minhas devoluções», podendo voltar a descarregar a etiqueta em PDF a qualquer momento.
Devolução de convidado (v1.7+)
Os clientes que encomendaram sem criar conta acedem à devolução a partir do mesmo URL dos clientes com sessão iniciada. Um visitante não autenticado vê um formulário «Número de encomenda + e-mail» em vez da lista «As minhas encomendas». Funcionamento:
- A validação é feita do lado do servidor: o par referência de encomenda e e-mail tem de corresponder exatamente a uma encomenda existente (comparação do e-mail sem distinção de maiúsculas).
- Em caso de não correspondência, a mensagem de erro é propositadamente genérica, como proteção contra a enumeração: não é revelada qualquer informação sobre as referências existentes.
- Depois de validado, o visitante acede ao fluxo de devolução normal apenas para essa encomenda (sessão PrestaShop delimitada).
- O PDF da etiqueta continua acessível a partir da ligação recebida por e-mail sem início de sessão, protegido por um token aleatório de 64 caracteres único para aquela devolução.
- Uma faixa «Use a different order» permite reiniciar a sessão de convidado e passar a outra encomenda.
O PDF da etiqueta e o código QR
Cada devolução gera um PDF com a morada de devolução, o número da devolução, a lista dos produtos e quantidades, as instruções e um código QR único que inclui um token de verificação criptográfica. O cliente imprime-o e cola-o na encomenda.
Moradas de devolução múltiplas
Configure várias moradas no separador Moradas (armazém principal, centro de tratamento de grandes volumes, morada na UE ou fora da UE). Cada devolução fica associada a uma morada, que aparece na respetiva etiqueta.
Se vende para os Açores e para a Madeira, indique claramente na etiqueta e nas suas condições quem suporta os custos de devolução a partir das ilhas: o Decreto-Lei n.º 24/2014 permite imputar ao consumidor o custo direto da devolução, desde que essa informação lhe tenha sido dada antes da compra.
Validação por leitura de QR à receção
Quando a encomenda chega, o seu operador lê o QR com um telemóvel ou um leitor USB. A leitura abre a página de validação protegida: é necessária uma sessão de administrador do PrestaShop ativa; sem sessão, a página redireciona para o início de sessão do back-office. O operador vê então o detalhe completo da devolução, verifica o estado físico dos produtos e clica em Validar ou Recusar.
A validação desencadeia em cascata: passagem da encomenda ao estado configurado (reembolso parcial ou total), geração do vale de compra ou do reembolso, e-mail de atualização ao cliente e envio do hook actionOrderSlipAdd para as integrações de terceiros.
O token do QR é único por devolução e verificado do lado do servidor: um QR falsificado ou reutilizado é rejeitado. Nunca partilhe os URL de validação fora da sua equipa.
Devolução manual pelo administrador (v1.6+)
O apoio ao cliente pode criar uma devolução para qualquer encomenda, independentemente do prazo de devolução configurado e do estado da encomenda, o que foi pensado para gestos comerciais, devoluções negociadas por telefone e regularizações retroativas.
- Clique em «Create manual return» no cabeçalho da lista de devoluções no back-office.
- Passo 1: introduza a referência ou o ID da encomenda (é aceite uma encomenda de 2022, cancelada ou em rascunho).
- Passo 2: assinale os produtos a devolver, as quantidades, a razão, o tipo de compensação (vale de compra ou nota de crédito) e ajuste, se necessário, o montante reembolsado por linha.
- Confirme: a devolução é tratada de imediato, com vale de compra ou nota de crédito gerados na hora, stock reposto, estado de encomenda atualizado e hook enviado.
Uma caixa «Notificar o cliente» (desmarcada por predefinição) envia o e-mail de confirmação normal, se assim o quiser. Pode anexar-se uma nota livre de administração à devolução.
O montante reembolsado personalizável (v1.7+)
Cada linha da devolução manual tem um campo «Refund amount» editável. O valor predefinido (preço unitário × quantidade) é recalculado automaticamente quando a quantidade muda, até que haja introdução manual: a partir daí, o valor introduzido é respeitado tal como está. O rácio proporcional dos descontos da encomenda, aplicado às devoluções normais do cliente, fica desativado nas devoluções manuais: o montante introduzido é exatamente o montante reembolsado. É útil para um reembolso parcial (produto danificado reembolsado a 50 %), um gesto comercial ou uma regularização. A nota de crédito gerada mantém a repartição com e sem IVA proporcional à taxa de IVA da linha de origem.
A nota de crédito gerada pelo PrestaShop é um documento interno da loja. Em Portugal, o documento retificativo com valor fiscal tem de ser emitido pelo seu software de faturação certificado pela AT e comunicado nos termos aplicáveis. Use o documento do módulo como registo operacional e mantenha a emissão fiscal no software certificado.
Vale de compra ou reembolso
Consoante a sua configuração, a validação de uma devolução produz um vale de compra (regra de carrinho nativa do PrestaShop, utilizável numa próxima encomenda) ou um reembolso a tratar no meio de pagamento de origem. Os dois estados de encomenda dedicados (parcial e total) permitem distinguir os casos nas suas exportações e nos relatórios contabilísticos.
Painel de estatísticas
O menu Estatísticas de devoluções expõe 13 eixos de análise, todos filtráveis por período e por loja:
- KPI globais: volume de devoluções, taxa de devolução, valor devolvido, repartição entre vale de compra e reembolso.
- Por categoria de razão e por razão: identifique as causas dominantes.
- Por país: detete anomalias geográficas (transportadora com falhas numa zona).
- Produtos mais devolvidos: as referências a examinar (guia de tamanhos, qualidade do fornecedor).
- Cruzamentos razão × país e razão × produto: o nível de detalhe necessário para agir.
- Tendências mensal (12 meses) e diária: sazonalidade e picos.
- Tempo médio de tratamento: o desempenho do seu apoio ao cliente.
- Repartição por dia da semana e clientes com mais devoluções: deteção de abusos.
O botão Exportar CSV descarrega o conjunto das devoluções do período filtrado (n.º da devolução, encomenda, cliente, produtos, razão, estado, datas, montante) para análise externa ou importação em ferramentas de BI.
O eixo «clientes com mais devoluções» trata dados pessoais para uma finalidade de deteção de abusos: inscreva-a no seu registo de atividades de tratamento e limite o acesso a quem dela precisa, como exige o RGPD sob supervisão da CNPD.
Integração com Fastmag e com o ERP
A cada devolução validada, o módulo envia o hook do PrestaShop actionOrderSlipAdd com a encomenda, a lista de produtos e as quantidades. Qualquer módulo à escuta deste hook (o módulo Fastmag da DataFirefly, conectores de ERP, Systempay) recebe a notificação em tempo real. As devoluções manuais do administrador enviam o mesmo hook.
O botão «Re-sync past returns to Fastmag» (barra de ferramentas da lista de devoluções) volta a acionar o hook em todas as devoluções passadas, o que é indispensável depois de instalar um conector de ERP posteriormente a este módulo, ou depois de um incidente de sincronização.
O Fastmag é um software de gestão francês, sem presença estabelecida no mercado português. Numa loja portuguesa, o mecanismo continua a ser útil: o hook actionOrderSlipAdd é padrão e qualquer conector de ERP à escuta dele recebe as devoluções, incluindo os que integram soluções como o PHC, o Primavera ou o Moloni.
E-mails transacionais
São três e-mails automáticos, fornecidos em 6 idiomas (FR, EN, ES, IT, PT, DE): confirmação do pedido ao cliente (com PDF em anexo), notificação ao administrador e atualização de estado ao cliente (validação, recusa ou reembolso). Nas devoluções manuais do administrador, o e-mail ao cliente é opcional (caixa desmarcada por predefinição). Personalize os templates em modules/dfproductreturn/mails/<idioma>/ ou através do sistema nativo de tradução de e-mails do PrestaShop.
Ao contrário de vários módulos, este entrega os e-mails já em português: não é preciso criar a pasta mails/pt à mão. Reveja mesmo assim os textos, para os alinhar com a redação das suas condições de venda.
Multiloja
Todas as tabelas têm um id_shop: cada loja tem as suas razões, as suas moradas de devolução e as suas estatísticas próprias. O seletor multiloja do back-office filtra naturalmente a lista de devoluções e o painel.
Resolução de problemas
O botão «Pedir uma devolução» não aparece
Verifique três pontos: a encomenda está num estado elegível (configuração), o prazo de devolução não foi ultrapassado e o módulo está ativo na loja em causa (contexto multiloja). Nota: para uma devolução fora de prazo, use a devolução manual do administrador.
O formulário de convidado rejeita uma encomenda válida
O e-mail introduzido tem de ser exatamente o da encomenda (as maiúsculas são ignoradas, os erros de escrita não). Confirme a referência da encomenda: é a referência alfanumérica (por exemplo, XKBKNABJK), não o ID numérico.
A leitura do QR mostra «Access denied»
É o comportamento esperado sem sessão de administrador: o operador tem de estar autenticado no back-office do PrestaShop no mesmo navegador. Inicie sessão e volte a ler o código.
A tradução pelo ChatGPT falha
Verifique a chave API na configuração, o saldo disponível na sua conta OpenAI e se o seu servidor permite ligações de saída para api.openai.com (porta 443).
O ERP não recebe as devoluções
Confirme que o módulo conector está instalado e ligado ao hook actionOrderSlipAdd e use depois «Re-sync past returns to Fastmag» para recuperar o histórico.