Seguimento DHL automático e multitransportadoras: guia completo
Instalar, configurar e explorar o seguimento DHL em tempo real, a sincronização automática dos estados e a página de seguimento com 19 transportadoras para PrestaShop 8 e 9.
O módulo DataFirefly Tracking consulta a API da DHL em tempo real para acompanhar as suas encomendas DHL eCommerce e DHL Express, faz evoluir automaticamente o estado das suas encomendas na entrega e oferece aos seus clientes uma página de seguimento com as suas cores, cobrindo 19 transportadoras. Este guia cobre a instalação, a obtenção da chave de API da DHL, a configuração, o cron, a página de seguimento, a sincronização dos estados, a adição de transportadoras e a resolução de problemas.
Pré-requisitos
- PrestaShop 8.0 a 9.x.
- PHP 8.1 a 8.3 com a extensão cURL ativa.
- Para o seguimento DHL: uma chave da API da DHL «Shipment Tracking — Unified» (developer.dhl.com).
- Um acesso a cron (tarefa agendada no servidor ou serviço de cron) para o seguimento automático.
O seguimento em tempo real diz respeito apenas à DHL eCommerce e à DHL Express. As outras 17 transportadoras são apresentadas com uma ligação de seguimento para a respetiva página oficial e não exigem qualquer chave de API.
A lista de transportadoras é maioritariamente francesa e da Europa do Norte: os CTT, os CTT Expresso, a Nacex e a SEUR não constam do registo. Numa loja portuguesa, as encomendas expedidas por esses operadores continuam a ser reconhecidas como encomendas normais do PrestaShop, mas sem ligação de seguimento automática. A secção «Acrescentar uma transportadora» explica como acrescentar cada uma com uma única entrada, o que é a via recomendada antes de colocar o módulo em produção.
Instalação
- No back-office, abra Módulos > Gestor de módulos, clique em Carregar um módulo e coloque o ficheiro
datafirefly_tracking.zip. - Depois de instalado, abra a página de configuração através do botão Configurar.
Na instalação, o módulo cria as suas tabelas, regista os seus hooks e gera automaticamente um token de cron.
Obter a chave de API da DHL
- Crie uma conta em
developer.dhl.com. - Subscreva a API Shipment Tracking — Unified e crie uma aplicação.
- Copie a chave de API (campo API Key).
Trata-se mesmo da chave da API de seguimento (Shipment Tracking — Unified) e não da chave da DHL eCommerce de expedição, usada para gerar as etiquetas. As duas chaves são distintas.
Configuração
A página de configuração reúne as seguintes definições:
- DHL Tracking API Key: cole aqui a sua chave de API da DHL.
- Ativar a consulta periódica: autoriza as atualizações automáticas das encomendas DHL.
- E-mails (Expedido, Em trânsito, Entregue, Incidente): preferências de notificação por transição de estado.
- Atualizar o estado do PrestaShop na entrega: ativa a sincronização automática do estado da encomenda.
- Retenção do registo (dias): período de conservação das linhas de registo antes da limpeza automática.
Grave as suas definições. Enquanto a chave não estiver preenchida e a consulta periódica não estiver ativa, nenhuma encomenda DHL é consultada.
Transportadoras suportadas
O módulo reconhece 19 transportadoras, repartidas por duas categorias.
Seguimento por API em tempo real (2)
DHL eCommerce e DHL Express: estados obtidos através da API da DHL, normalizados (criado, em trânsito, entregue, incidente) e apresentados numa linha de tempo.
Ligação de seguimento personalizada (17)
Colissimo, Chronopost, Shop2Shop, Mondial Relay, Relais Colis, Colis Privé, DPD, GLS, UPS, FedEx, TNT, La Poste, Poste Italiane, Correos, DHL Paket, bpost e PostNL: a página de seguimento mostra uma ligação para a página oficial da transportadora, sem chamada à API.
A deteção é feita primeiro pelo módulo da transportadora (external_module_name) e depois pelo nome da transportadora. Isto cobre também as transportadoras configuradas à mão, sem módulo externo.
A DPD, a GLS, a UPS, a FedEx e a TNT operam em Portugal e são reconhecidas de origem, o que já cobre uma boa parte dos envios internacionais. A ligação aponta para a página oficial da transportadora, que deteta o idioma do visitante ou o país do envio.
Criação automática do seguimento
Quando uma encomenda passa ao estado «Expedido», o módulo deteta a transportadora, resolve o número de seguimento e cria depois a ficha de seguimento. O número é procurado, por esta ordem, em:
- a linha de transportadora da encomenda (
order_carrier); - as etiquetas DHL Parcel (quando existirem);
- o número AWB da DHL Express (quando existir).
Nas encomendas DHL, o seguimento é depois consultado automaticamente; nas restantes transportadoras, é apenas associada uma ligação de seguimento à encomenda.
Configuração do cron
O cron aciona a consulta periódica das encomendas DHL e recupera as expedições que o hook tenha falhado (número preenchido depois da passagem a «Expedido», transportadora sem módulo). Agende o URL seguinte a cada 15 a 30 minutos:
curl "https://a-sua-loja.pt/module/datafirefly_tracking/cron?token=O_SEU_TOKEN"O token é gerado na instalação e apresentado na configuração. Para uma recuperação histórica pontual das encomendas antigas, acrescente o parâmetro days:
curl "https://a-sua-loja.pt/module/datafirefly_tracking/cron?token=O_SEU_TOKEN&days=60"A recuperação está limitada a 180 dias: para lá disso, a DHL elimina os seus dados de seguimento e a consulta devolveria apenas erros de «não encontrado».
A quota da API e o limitador de pedidos
A API da DHL está limitada a 250 pedidos por dia. O módulo integra um limitador de pedidos que:
- conta as chamadas do dia e para a consulta periódica de forma limpa quando atinge o limite, retomando no dia seguinte;
- espaça as consultas conforme o estado da encomenda (mais frequentes em caso de incidente, mais raras numa encomenda apenas criada);
- deixa definitivamente de consultar as encomendas entregues;
- abandona um número depois de vários erros de «não encontrado» (por exemplo, um número que não é da DHL introduzido numa transportadora DHL).
O contador do dia é visível na configuração e na ficha da encomenda.
Página de seguimento do lado do cliente
Aparece uma ligação «Seguir a minha encomenda» no detalhe da encomenda e na área de cliente. A página de seguimento personalizada apresenta uma linha de tempo de 4 etapas (Expedido, Em trânsito, Em distribuição, Entregue) e o detalhe dos eventos.
Está acessível:
- aos clientes com sessão iniciada, para as suas próprias encomendas;
- aos convidados, através do número de seguimento acompanhado da referência da encomenda.
Algumas transportadoras (PostNL) exigem o código postal do destinatário no URL de seguimento: o módulo preenche-o automaticamente a partir da morada de entrega da encomenda.
As cadeias da página de seguimento e as designações da linha de tempo são vistas pelo cliente. Traduza-as em Internacional > Traduções antes de divulgar a ligação, e crie a pasta mails/pt se ativar as notificações por transição de estado.
Seguimento no back-office
Em cada ficha de encomenda, um separador de seguimento mostra a linha de tempo, o último evento, o estado normalizado e um botão Atualizar para consultar a DHL manualmente (dentro do limite da quota). São também propostas a ligação para a página de seguimento oficial da transportadora e para a página de seguimento do front-office.
Sincronização dos estados de encomenda
Com a opção Atualizar o estado do PrestaShop na entrega ativa, o módulo faz evoluir o estado da encomenda nas encomendas DHL:
- encomenda entregue → estado «Entregue»;
- incidente de entrega → estado «Erro».
A mudança de estado aciona os e-mails nativos do PrestaShop. O módulo impede qualquer regressão: uma encomenda já entregue não pode voltar a «em trânsito».
Acrescentar uma transportadora
Todas as transportadoras estão descritas num registo central (classe CarrierRegistry). Acrescentar uma transportadora consiste em acrescentar uma única entrada com:
- o seu identificador interno e a sua designação;
- os nomes de módulo (
external_module_name) e os padrões de nome para a deteção; - o seu URL de seguimento (com os marcadores
{tracking}e, se necessário,{postcode}); - o indicador de seguimento por API ou por ligação, e a regra de validação do número.
Nenhuma outra parte do módulo precisa de ser alterada: a deteção, o URL, a designação e o painel decorrem daí automaticamente.
É por aqui que passa o suporte dos CTT: uma entrada com o padrão de nome «CTT», o URL público de seguimento dos CTT e o marcador {tracking} basta para que as encomendas expedidas por eles ganhem a sua ligação na página de seguimento. Faça o mesmo para os CTT Expresso, a Nacex ou a SEUR, conforme os operadores que utiliza.
Atualização a partir de uma versão anterior
A atualização faz-se substituindo os ficheiros do módulo; o PrestaShop aplica automaticamente os scripts de migração. A versão 1.1.0 alarga a coluna de tipo de transportadora para acolher as novas transportadoras: esse script é idempotente e preserva os dados existentes.
Não é necessária qualquer reconfiguração depois de uma atualização: a chave de API, o token de cron e as fichas de seguimento existentes são conservados.
Resolução de problemas
- Nenhuma encomenda DHL é seguida: confirme que a chave de API está preenchida, que a consulta periódica está ativa e que o cron é executado.
- Erro de «chave de API inválida»: certifique-se de que usa a chave da API Shipment Tracking — Unified e não a chave de expedição da DHL eCommerce.
- Quota atingida: com 250 pedidos por dia, a consulta periódica para e retoma no dia seguinte. Espace o cron ou reduza o volume de encomendas ativas, se for necessário.
- Uma encomenda continua por encontrar: depois de vários erros de «não encontrado», o módulo abandona o número (muitas vezes, um número que não é da DHL introduzido numa transportadora DHL).
- O estado da encomenda não muda: confirme que a opção de atualização do estado está ativa e que a encomenda é mesmo seguida pela API da DHL.
- Ligação de seguimento da PostNL incompleta: o código postal vem da morada de entrega; confirme que está preenchida na encomenda.
Desinstalação
A desinstalação elimina as tabelas de seguimento, de registo e de quota do módulo, bem como a sua configuração. Para uma simples atualização, basta substituir os ficheiros: o esquema e as fichas de seguimento são preservados.