# Product Return Manager: guia completo

> Instalação, configuração e utilização do módulo DataFirefly Product Return Manager para PrestaShop 8: devoluções em autosserviço, etiqueta em PDF com QR, validação por leitura, estatísticas em 13 eixos, tradução pelo ChatGPT e integração com ERP.

- Página: <https://www.datafirefly.com/pt/documentation/datafirefly-product-return-manager-prestashop-8/>
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-product-return-manager-prestashop-8/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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:

1. Abre a encomenda elegível e clica em «Pedir uma devolução».
2. Assinala os produtos a devolver e ajusta as quantidades.
3. Escolhe uma categoria de razão, depois uma razão específica, e acrescenta um comentário opcional.
4. 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.

1. Clique em **«Create manual return»** no cabeçalho da lista de devoluções no back-office.
2. **Passo 1**: introduza a referência ou o ID da encomenda (é aceite uma encomenda de 2022, cancelada ou em rascunho).
3. **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**.
4. 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//` 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.