# Return Portal + Auto-Label: documentação completa

> Portal de devoluções self-service para o cliente, etiquetas de devolução de várias transportadoras geradas automaticamente, fluxo de inspeção na administração e motor de resolução (reembolso, nota de crédito bonificada, substituição)…

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

Portal de devoluções self-service para o cliente, etiquetas de devolução de várias transportadoras geradas automaticamente, fluxo de inspeção na administração e motor de resolução (reembolso, nota de crédito bonificada, substituição) para WooCommerce.

**Versão:** 1.0.7
**Compatibilidade:** WordPress 6.2+ • WooCommerce 8.0+ • PHP 8.0+ • HPOS e Cart/Checkout Blocks

## Visão de conjunto

O Return Portal + Auto-Label automatiza todo o ciclo de vida de uma devolução de produto na sua loja WooCommerce:

- **Do lado do cliente**: o cliente pede a devolução sem contactar o apoio, seleciona os artigos, escolhe um motivo e recebe de imediato a sua etiqueta em PDF.
- **Do lado da administração**: painel com linha temporal, inspeção linha a linha, registo de atividade completo e resolução automática.
- **6 transportadoras**: Manual (PDF nativo), Colissimo, Mondial Relay, Chronopost, UPS, DPD.
- **3 resoluções**: reembolso nativo do WooCommerce, nota de crédito bonificada (+X%) ou substituição automática.

As integrações por API disponíveis são as da Colissimo, da Mondial Relay e da Chronopost (operadores franceses), da UPS e da DPD (internacionais). Se a sua transportadora não estiver nesta lista, o modo **Manual** gera uma guia de devolução em PDF válida em qualquer país, sem API. Também pode acrescentar a sua própria transportadora através do filtro `dfrp_register_carriers` (ver mais abaixo).

### Estados de uma devolução

Uma devolução percorre até 7 etapas:

| Estado | Descrição |
| --- | --- |
| `requested` | Pedido recebido, à espera de validação |
| `approved` | Aprovado pela administração (ou aprovado automaticamente abaixo do limiar) |
| `label_sent` | Etiqueta gerada e enviada ao cliente |
| `in_transit` | Encomenda em trânsito |
| `received` | Encomenda recebida no armazém |
| `inspecting` | Inspeção dos artigos em curso |
| `resolved` | Resolução aplicada (reembolso / nota de crédito / substituição) |

Dois estados terminais adicionais: `rejected` (recusa) e `cancelled` (cancelamento).

## Instalação

### Método 1: através da administração do WordPress

1. Descarregue o ZIP `dfreturnportal.zip`.
2. No WordPress, vá a **Plugins → Adicionar → Carregar plugin**.
3. Selecione o ZIP e clique em **Instalar agora**.
4. Ative a extensão.

### Método 2: através de FTP/SSH

```bash
cd wp-content/plugins/
unzip dfreturnportal.zip
# Ative depois a partir da administração do WordPress
```

### Verificações pós-instalação

- Aparece um menu **Devoluções** na barra lateral do WordPress.
- É criado automaticamente um endpoint `/my-account/returns/` (o slug é personalizável, ver a secção de personalização).
- São criadas as tabelas personalizadas `wp_dfrp_returns`, `wp_dfrp_return_items`, `wp_dfrp_history` e `wp_dfrp_attachments`.

Se o separador «Devoluções» não aparecer em A minha conta, vá a **Definições → Permalinks** e clique em «Guardar» para atualizar as regras de reescrita.

## Configuração inicial

Vá a **Devoluções → Definições**.

### Geral

| Definição | Descrição |
| --- | --- |
| **Janela de elegibilidade** | Número de dias após a encomenda durante os quais é permitida uma devolução. Predefinição: 30 dias. |
| **Página do portal do cliente** | Página WordPress onde será apresentado o shortcode `[dfrp_portal]`. Opcional se usar apenas o endpoint de A minha conta. |
| **Notificações de administração** | Endereço de e-mail que recebe as notificações de novos pedidos. Predefinição: administrador do site. |

### Transportadora

Selecione a transportadora **ativa** entre as 6 disponíveis. Também pode configurar o **formato da etiqueta** (A4, A5, A6, 10x15).

### Morada de devolução

Indique a morada física para onde as encomendas devolvidas serão expedidas. **Obrigatória** para gerar as etiquetas. Campos: Empresa, Rua, Cidade, Código postal, País (código ISO de 2 letras), Telefone, E-mail.

### Credenciais das transportadoras

Para cada transportadora com API (Colissimo, Mondial Relay, etc.), um bloco expansível contém as credenciais necessárias. Preencha **apenas** as da transportadora que usa.

### Resolução

| Definição | Descrição |
| --- | --- |
| **Bónus da nota de crédito (%)** | Percentagem acrescentada ao montante reembolsado quando o cliente escolhe a nota de crédito bonificada. Predefinição: 10%. |
| **Limiar de aprovação automática** | Abaixo deste montante (moeda da loja), os pedidos são aprovados automaticamente e a etiqueta é gerada sem intervenção da administração. Coloque 0 para desativar. |
| **Resolução proposta por motivo** | Para cada motivo (8 motivos por predefinição), escolha a resolução proposta: reembolso / nota de crédito bonificada / substituição. |

### Exclusões

- **Categorias excluídas**: IDs do WooCommerce separados por vírgulas. Os produtos dessas categorias nunca serão elegíveis para devolução.
- **SKU excluídos**: um SKU por linha. Idem.

## Experiência do cliente

### Através da página A minha conta (clientes com sessão)

O mais simples e o mais usado. O separador **Devoluções** aparece automaticamente no menu `/my-account/` ao lado de «Encomendas», «Moradas», etc.

O cliente clica em Devoluções, vê a lista das suas encomendas elegíveis (sem precisar de introduzir e-mail nem número), clica em Iniciar uma devolução na encomenda em causa, seleciona os artigos, escolhe um motivo e uma quantidade por artigo, acrescenta eventualmente fotografias (se o motivo o exigir), escolhe a sua resolução preferida e recebe de imediato um número de RMA (por exemplo `RMA-20260523-A1B2C3`), mais um e-mail de confirmação.

### Através de uma página pública (clientes sem sessão)

Crie uma página WordPress e insira o shortcode:

```
[dfrp_portal]
```

O cliente tem de introduzir o seu **número de encomenda** e o seu **e-mail** para se autenticar. O resto do fluxo é idêntico.

### Seguimento de um pedido existente

Na página pública do portal, um bloco «Seguir um pedido existente» permite aos clientes convidados verificar o estado do seu RMA (estado, número de seguimento da transportadora, ligação para a etiqueta).

### Personalização do shortcode

```
[dfrp_portal title="Pedido de devolução" context="page"]
```

| Atributo | Valores | Descrição |
| --- | --- | --- |
| `title` | texto livre | Título do portal (raramente usado visualmente). |
| `context` | `page` ou `myaccount` | Força o contexto. `myaccount` salta a etapa de pesquisa nos utilizadores com sessão. |

## Fluxo do administrador

### Painel

Acessível em **Devoluções → Painel**. Contém 9 cartões de estatísticas coloridos (contagem por estado, clicáveis para filtrar a lista), os 10 últimos RMA com acesso rápido ao detalhe, e uma faixa com o URL do portal do cliente e um botão «Copiar» para partilhar.

### Lista de pedidos

Acessível em **Devoluções → Todos os pedidos**. Tabela com filtros por estado, pesquisa livre (RMA, e-mail do cliente, número de encomenda) e paginação (20 por página).

### Página de detalhe de um pedido

Componentes:

1. **Cabeçalho**: código RMA, distintivo de estado e regresso à lista.
2. **Linha temporal**: 7 pontos coloridos que mostram a progressão visual.
3. **Artigos a devolver**: tabela com produto, SKU, quantidade, preço unitário, motivo e inspeção por artigo (menu pendente Conforme / Parcialmente / Recusado, ativado depois do estado `received`).
4. **Fotografias do cliente**: galeria, se o cliente tiver carregado justificativos.
5. **Registo de atividade**: histórico cronológico completo.
6. **Informações**: e-mail do cliente, ligação para a encomenda, preferência de resolução, nota do cliente.
7. **Etiqueta de devolução**: transportadora, número de seguimento, botão de descarregar o PDF, botão de regerar.
8. **Ações**: botões «Passar a: [estado seguinte]» conforme a máquina de estados.
9. **Resolver** (visível se o estado for `received` ou `inspecting`): seletor de resolução e botão «Aplicar».

### Transições possíveis

A máquina de estados impede as transições inválidas:

```
requested  → approved | rejected | cancelled
approved   → label_sent | rejected | cancelled
label_sent → in_transit | cancelled
in_transit → received
received   → inspecting
inspecting → resolved | rejected
```

Os estados `resolved`, `rejected` e `cancelled` são terminais.

### Aprovação automática

Se tiver configurado um limiar de aprovação automática (por exemplo 50 €), qualquer pedido cujo montante total seja inferior ou igual ao limiar passa automaticamente de `requested` a `approved`, a etiqueta é gerada de imediato e enviada ao cliente, sem necessidade de intervenção da administração.

## Transportadoras suportadas

### Manual (sem API)

**Ideal para começar.** Gera uma guia em PDF nativa com QR code, sem qualquer dependência de API externa. Sem configuração, gratuito, funciona de imediato em qualquer país. Limite: sem seguimento automático. Utilização: o cliente imprime-a, você coloca-a na encomenda na expedição inicial, ou ele cola-a para uma devolução postal clássica.

### Colissimo (La Poste, França)

API REST oficial (serviço Sls `generateLabel`). Credenciais necessárias: Contract Number, Password. Particularidades: gera um código de barras `parcelNumber`, tipo de devolução «3» (devolução com correspondência), formato PDF por predefinição.

### Mondial Relay (França)

API SOAP (`WSI4_CreationEtiquette`). Credenciais necessárias: Enseigne, Private Key, Pickup Point. Particularidades: modo de recolha `CCC` (Colis Confié Client), assinatura MD5 obrigatória.

### Chronopost (França)

API SOAP (`shippingMultiParcelV5`). Credenciais necessárias: Account Number, Password, Subaccount. Particularidades: Product Code `8R` (devolução em ponto de recolha), modo de devolução `2`.

### UPS

API REST v2403 (`/ship`). Credenciais necessárias: Client ID (OAuth2), Client Secret, Shipper Number. Particularidades: `ReturnService.Code` = `8` (Electronic Return Label), formato GIF em base64 por predefinição.

### DPD

API REST (endpoint cargonet). Credenciais necessárias: Username, Password, Customer ID. Particularidades: autenticação Basic Auth, formato PDF A6.

## Resoluções

### Reembolso

Usa a função nativa `wc_create_refund()` do WooCommerce. Recredita o meio de pagamento inicial, repõe automaticamente o stock dos artigos (configurável), cria uma nota de reembolso na encomenda e gera um e-mail nativo de confirmação do WooCommerce.

### Nota de crédito bonificada (Store Credit)

Cria automaticamente um cupão WooCommerce:

- **Montante** = total da devolução mais bónus (% configurável, 10% por predefinição).
- **Restrição por e-mail**: utilizável apenas pelo e-mail do cliente.
- **Expiração**: 6 meses por predefinição.
- **Utilização única**.

O cliente recebe um e-mail com o código do cupão em destaque.

### Substituição

Cria uma **nova encomenda WooCommerce** a 0 € (gratuita para o cliente). Moradas de entrega e de faturação copiadas da encomenda de origem, artigos idênticos aos artigos devolvidos conformes, estado inicial `processing` (expede-a normalmente). O cliente recebe um e-mail com o número da nova encomenda.

### Proposta automática

O motor analisa os motivos dos artigos devolvidos e propõe a resolução mais pertinente. Configuração em **Devoluções → Definições → Resolução proposta por motivo**. Mapeamento por predefinição:

| Motivo | Resolução proposta |
| --- | --- |
| Artigo danificado | Substituição |
| Artigo defeituoso | Substituição |
| Artigo errado recebido | Substituição |
| Conforme à descrição mas não serve | Reembolso |
| Mudança de ideias | Nota de crédito bonificada |
| Tamanho ou cor incorretos | Nota de crédito bonificada |
| Entrega atrasada | Reembolso |
| Outro | Reembolso |

## Personalização

### Substituição dos templates

Todos os templates de e-mail podem ser substituídos através do seu tema. Copie o ficheiro de origem `templates/emails/*.php` para `oseutema/dfreturnportal/emails/*.php`.

### Hooks (ações)

```php
do_action('dfrp_after_return_created', int $returnId, array $return);
do_action('dfrp_status_changed', int $returnId, string $fromStatus, string $toStatus);
do_action('dfrp_label_generated', int $returnId, array $label);
do_action('dfrp_before_resolution', int $returnId, string $resolution);
do_action('dfrp_after_resolution', int $returnId, string $resolution, array $result);
```

### Filtros

```php
// Personalizar os estados de encomenda elegíveis (predefinição: ['completed', 'processing'])
add_filter('dfrp_eligible_order_statuses', function($statuses) {
    $statuses[] = 'on-hold';
    return $statuses;
});

// Personalizar os motivos de devolução
add_filter('dfrp_reasons', function($reasons) {
    $reasons[] = [
        'code'          => 'motivo_personalizado',
        'label'         => 'O meu motivo personalizado',
        'require_photo' => false,
    ];
    return $reasons;
});

// Personalizar o slug do endpoint de A minha conta (predefinição: 'returns')
add_filter('dfrp_myaccount_endpoint', function() {
    return 'as-minhas-devolucoes';
});

// Personalizar o texto do menu de A minha conta
add_filter('dfrp_myaccount_menu_label', function() {
    return 'As minhas devoluções de produtos';
});

// Acrescentar uma transportadora personalizada
add_filter('dfrp_register_carriers', function($carriers) {
    $carriers[] = new AMinhaTransportadoraPersonalizada();
    return $carriers;
});
```

### Desinstalação limpa

Por predefinição, a desinstalação **conserva** os dados (tabelas e opções). Para limpar por completo na desinstalação, acrescente ao `wp-config.php`:

```php
define('DFRP_DELETE_DATA_ON_UNINSTALL', true);
```

## API REST

Todos os endpoints estão no namespace `dfrp/v1`. URL base: `https://oseusite.com/wp-json/dfrp/v1/`.

### Endpoints públicos

| Endpoint | Método | Descrição |
| --- | --- | --- |
| `/lookup` | POST | Pesquisa uma encomenda por número e e-mail. |
| `/create` | POST | Cria um novo pedido de devolução. |
| `/track` | POST | Segue um RMA através do código e do e-mail. |
| `/upload-photo` | POST | Carrega uma fotografia justificativa (multipart). |

### Endpoints de cliente com sessão

| Endpoint | Método | Descrição |
| --- | --- | --- |
| `/my-orders` | GET | Lista as encomendas elegíveis do cliente com sessão iniciada. |

### Endpoints de administração (permissão `manage_woocommerce`)

| Endpoint | Método | Descrição |
| --- | --- | --- |
| `/admin/returns` | GET | Lista paginada com filtros. |
| `/admin/returns/{id}` | GET | Detalhe de uma devolução. |
| `/admin/returns/{id}/transition` | POST | Mudar o estado. |
| `/admin/returns/{id}/inspect-item` | POST | Resultado da inspeção de um artigo. |
| `/admin/returns/{id}/resolve` | POST | Aplicar uma resolução. |
| `/admin/returns/{id}/regenerate-label` | POST | Regerar a etiqueta. |

## Resolução de problemas

### O portal mostra «A carregar...» indefinidamente

- Verifique a consola do navegador (F12): deve ver `[Return Portal] script frontend.js exécuté`.
- Se não aparecer nada, um plugin de segurança (Wordfence, Sucuri, NinjaFirewall) está a bloquear o script inline. Desative-o temporariamente para testar.
- Verifique também os otimizadores de JS (WP Rocket «Delay JS», Autoptimize, Cloudflare Rocket Loader): o plugin já emite os atributos de exclusão necessários, mas algumas configurações agressivas ainda podem bloquear.

### O separador «Devoluções» não aparece em A minha conta

Vá a **Definições → Permalinks** e clique em «Guardar alterações» (sem alterar nada). Isso força o WordPress a regenerar as regras de reescrita.

### Erro «Constant DFRP_VERSION already defined»

A pasta do plugin está duplicada. Verifique:

```bash
ls -la wp-content/plugins/ | grep dfreturnportal
```

Elimine as cópias duplicadas (por exemplo `dfreturnportal-old/`, `dfreturnportal-1/`).

### O cliente não recebe os e-mails

- Verifique que o envio de e-mails funciona em geral.
- Configure um SMTP correto (WP Mail SMTP, FluentSMTP).
- Verifique os registos de spam do domínio de destino.

### A etiqueta em PDF está vazia ou corrompida

- Verifique que a morada de devolução está completamente preenchida.
- Nas transportadoras com API, verifique primeiro as credenciais em modo de teste.
- Consulte os registos do PHP (`/wp-content/debug.log`, se o `WP_DEBUG_LOG` estiver ativo).

## FAQ

**O plugin exige uma subscrição numa transportadora?**
Não. O modo **Manual** gera uma guia em PDF nativa sem qualquer dependência de API. Os modos com API (Colissimo, etc.) são opcionais.

**É compatível com HPOS (High-Performance Order Storage)?**
Sim, totalmente. O plugin declara a sua compatibilidade no arranque do WooCommerce.

**É compatível com os Cart/Checkout Blocks?**
Sim.

**As variações de produto são tratadas?**
Sim, cada variação é tratada como um artigo distinto.

**E os produtos virtuais ou descarregáveis?**
São automaticamente excluídos das devoluções.

**O cliente pode devolver parcialmente uma encomenda?**
Sim. A elegibilidade tem em conta as quantidades já devolvidas num RMA anterior.

**Multilingue?**
O plugin está pronto para tradução (Text Domain `dfreturnportal`, ficheiro `.pot` fornecido). Compatível com WPML, Polylang e TranslatePress.

**As fotografias dos clientes são guardadas de forma segura?**
Sim, na biblioteca de multimédia do WordPress, com regras de acesso `.htaccess` que impedem a listagem de diretórios.