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

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.

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

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.

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, 10×15).

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)

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

// 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:

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:

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.