# AI Returns Predictor: guia completo

> O AI Returns Predictor analisa cada encomenda logo na validação e atribui-lhe uma pontuação de risco de devolução de 0 a 100, classificada em três níveis (Baixo, Médio, Elevado). A…

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

O AI Returns Predictor analisa cada encomenda logo na validação e atribui-lhe uma pontuação de risco de devolução de 0 a 100, classificada em três níveis (Baixo, Médio, Elevado). A pontuação é apresentada diretamente na ficha da encomenda, com o detalhe dos fatores, e a sua logística é avisada por e-mail antes da expedição sempre que uma encomenda ultrapassa o limiar de risco elevado. Este guia cobre a instalação, a configuração, o funcionamento do motor de pontuação e a camada de IA opcional.

## Instalação

1. Descarregue o ficheiro `dfreturnspredictor.zip` a partir da sua conta DataFirefly.
2. Back-office do PrestaShop → **Módulos** → **Carregar um módulo** → envie o ZIP.
3. Na instalação, o módulo cria a sua tabela `df_return_risk`, regista os seus hooks e acrescenta o separador **Expedição → Returns Predictor**.

Compatível com o PrestaShop 8.0 a 9.x, em PHP 7.4 a 8.3. Sem overrides do tema e sem dependências Composer. Compatível com multiloja e multilingue.

## Configuração geral

Vá a **Módulos → AI Returns Predictor → Configurar**.

### Limiares de risco

Dois limiares determinam o nível atribuído a cada encomenda a partir da sua pontuação:

- **Limiar Médio** (40 por predefinição): pontuação a partir da qual uma encomenda passa a risco _Médio_.
- **Limiar Elevado** (70 por predefinição): pontuação a partir da qual uma encomenda passa a risco _Elevado_ e despoleta o aviso à logística.

Abaixo do limiar Médio, a encomenda é classificada como _Baixo_. Os limiares têm de respeitar a regra 1 ≤ Médio < Elevado ≤ 100.

### Categorias com elevada taxa de devolução

Indique a lista dos identificadores das categorias conhecidas pelas devoluções frequentes (moda, têxtil, calçado...), separados por vírgulas. Os produtos pertencentes a essas categorias aumentam a pontuação da encomenda.

### Aviso à logística

- **E-mail de aviso à logística**: endereço notificado quando uma encomenda ultrapassa o limiar de risco elevado. Deixe o campo vazio para desativar os avisos por e-mail.

O aviso é enviado uma única vez por encomenda, na primeira deteção de risco elevado. Os recálculos posteriores não voltam a enviar e-mail.

### Camada de IA (opcional)

O módulo funciona sem IA graças ao seu motor heurístico. Pode ativar uma camada de IA opcional para afinar a pontuação e gerar uma explicação curta.

- **Ativar o afinamento por IA**: se estiver desativado, não é feita qualquer chamada externa.
- **Chave de API da Mistral**: guardada do lado do servidor, nunca exposta ao front-office.
- **Modelo Mistral**: por exemplo, `mistral-small-latest`.

Em caso de erro de rede, de API indisponível ou de tempo limite excedido (8 s), o módulo volta automaticamente à pontuação heurística. A pontuação nunca bloqueia a preparação das encomendas.

## Como é calculada a pontuação

O motor heurístico combina seis fatores explicáveis, cada um com um número máximo de pontos. O total é limitado entre 0 e 100.

- **Histórico de devoluções do cliente** (0–30): relação entre o número de devoluções anteriores e o número de encomendas válidas do cliente.
- **Encomenda de vários tamanhos ou variantes** (0–25): mesmo produto encomendado em várias combinações (tamanhos, cores), sinal de uma intenção de experimentar.
- **Valor do carrinho** (0–15): montante da encomenda face ao carrinho médio da loja.
- **Categorias de risco** (0–20): presença de produtos nas categorias que declarou.
- **Cliente novo** (0–8): ausência de histórico de compra utilizável.
- **Dimensão do carrinho** (0–10): número de artigos distintos na encomenda.

Cada fator apresenta a sua contribuição em pontos na ficha da encomenda, o que torna a pontuação inteiramente transparente: não há caixa negra.

## O painel de risco na encomenda

Em cada ficha de encomenda (hook `displayAdminOrderSide`), um painel «Risco de devolução» apresenta:

- a pontuação em 100 e o nível com cor (Baixo / Médio / Elevado);
- o detalhe dos fatores que contribuem, com os respetivos pontos;
- a explicação da IA, quando existe;
- um botão **Recalcular** que relança a pontuação por AJAX sem recarregar a página.

A pontuação é calculada automaticamente na validação da encomenda (hook `actionValidateOrder`) e atualizada nas mudanças de estado (hook `actionOrderStatusPostUpdate`).

## O painel logístico

O separador **Expedição → Returns Predictor** lista todas as encomendas pontuadas, ordenadas por pontuação decrescente. Encontra aí a referência, o cliente, o estado, a pontuação, o nível e o indicador de aviso. Filtre por nível para isolar as encomendas de risco elevado antes da preparação das embalagens. A ação «Ver» abre diretamente a ficha da encomenda em causa.

## O aviso por e-mail

Quando uma encomenda ultrapassa o limiar de risco elevado no momento da criação, parte um e-mail de resumo para o endereço logístico configurado: referência da encomenda, pontuação, nível, cliente, fatores contributivos e eventual nota da IA. Os modelos de e-mail são fornecidos em francês e em inglês, e o envio tem em conta o idioma do cliente e a loja de origem da encomenda.

O módulo informa e avisa, mas nunca altera o estado da encomenda nem impede a expedição. A decisão final continua a ser humana.

## Compatibilidade e notas técnicas

- PrestaShop 8.0 a 9.x, multiloja e multilingue.
- Controlador de administração legacy (sem controlador Symfony) para a compatibilidade PS8/PS9.
- Endpoint AJAX do back-office através do 4.º argumento de `getAdminLink()`; resposta JSON produzida por um método dedicado.
- Tabela `df_return_risk`: um registo por encomenda, com pontuação, nível, fatores (JSON) e indicador de aviso.
- Camada de IA opcional: só os dados necessários ao cálculo são transmitidos à Mistral; recurso automático à heurística.

## FAQ e resolução de problemas

**O painel de risco não aparece na ficha da encomenda.** Verifique se o módulo está mesmo ligado ao hook `displayAdminOrderSide` e se a encomenda foi criada depois da instalação. Utilize o botão «Recalcular» para forçar a pontuação.

**Não recebo nenhum aviso por e-mail.** Verifique se o endereço de aviso está preenchido e é válido e se a encomenda ultrapassa efetivamente o limiar Elevado. O aviso só é enviado uma vez por encomenda.

**A IA não devolve qualquer explicação.** Verifique a chave de API e o nome do modelo Mistral. O módulo passa de qualquer forma para a pontuação heurística; nenhuma pontuação se perde.

**Todos os clientes novos são considerados de risco?** Não. A ausência de histórico acrescenta apenas um ligeiro agravamento; a pontuação depende sobretudo dos outros fatores (várias variantes, categorias, valor do carrinho).