# Seguimento DHL automático e multitransportadoras: guia completo

> 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…

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

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

1. No back-office, abra _Módulos > Gestor de módulos_, clique em _Carregar um módulo_ e coloque o ficheiro `datafirefly_tracking.zip`.
2. 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

1. Crie uma conta em `developer.dhl.com`.
2. Subscreva a API **Shipment Tracking — Unified** e crie uma aplicação.
3. 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:

1. a linha de transportadora da encomenda (`order_carrier`);
2. as etiquetas DHL Parcel (quando existirem);
3. 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.