# Página de seguimento de encomenda multitransportadora (dftracking): guia completo

> O dftracking acrescenta à sua loja PrestaShop uma página de seguimento de encomenda com as suas cores. O módulo consulta diretamente as API das transportadoras (Colissimo, Mondial Relay, Chronopost, DHL),…

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

O dftracking acrescenta à sua loja PrestaShop uma página de seguimento de encomenda com as suas cores. O módulo consulta diretamente as API das transportadoras (Colissimo, Mondial Relay, Chronopost, DHL), normaliza os estados heterogéneos num vocabulário comum e apresenta-os numa linha de tempo de quatro etapas, acompanhada do detalhe dos eventos de cada volume.

**Transportadoras cobertas.** Os conectores nativos são a Colissimo/La Poste, a Mondial Relay e a Chronopost, que são operadores franceses, além da DHL, esta sim presente em Portugal. Os operadores portugueses (CTT, CTT Expresso, DPD Portugal, GLS, Nacex, SEUR) não têm conector nativo: as encomendas enviadas por eles continuam a aparecer na página com o número de seguimento e a ligação pública da transportadora, mas sem linha de tempo alimentada por API. A arquitetura é aberta e permite acrescentar um conector, como se explica na secção «Acrescentar uma transportadora».

Esta documentação cobre a versão **1.0.0** do módulo, compatível com PrestaShop **8.0.0 a 9.x** e PHP 7.4 a 8.3. Sem overrides de classe e sem dependências Composer.

## Instalação

1. No seu back-office PrestaShop, abra **Módulos > Gestor de módulos**.
2. Clique em **Carregar um módulo** e coloque o ficheiro `dftracking.zip`.
3. Clique em **Configurar** assim que a instalação terminar.

Na instalação, o módulo cria a tabela de cache `ps_dftracking_shipment`, gera um token de cron aleatório e regista-se em quatro hooks: `moduleRoutes` (URL amigável `/order-tracking`), `displayOrderDetail` (botão «Seguir a minha encomenda» no detalhe da encomenda), `displayCustomerAccount` (ligação na área de cliente) e `actionFrontControllerSetMedia` (folha de estilo da página).

## Credenciais de API das transportadoras

Cada transportadora tem o seu próprio modo de autenticação. Preencha apenas as que utiliza: uma transportadora não configurada simplesmente não é consultada, e o módulo passa a mostrar a ligação de seguimento pública.

### Colissimo / La Poste

O conector usa a API **Suivi v2** da plataforma Okapi. Crie uma conta gratuita em `developer.laposte.fr`, subscreva a API «Suivi» e copie a chave Okapi para o campo **Colissimo / La Poste: chave API Okapi**.

### Mondial Relay

O conector usa o serviço `WSI2_TracingColisDetaille`. Indique o seu **código Enseigne** (em regra 8 caracteres, por exemplo `BDTEST13` em ambiente de teste) e a sua **chave privada**, ambos fornecidos no seu contrato Mondial Relay ou a partir do Connect Hub. O módulo calcula automaticamente a assinatura MD5 esperada pelo serviço.

### Chronopost

Não é necessária qualquer credencial: o conector apoia-se no endpoint público `TrackingServiceWS`, que aceita os números de seguimento sem autenticação. Os campos de conta e palavra-passe existem para configurações específicas, mas são opcionais.

### DHL

O conector usa a API **Shipment Tracking – Unified**. Crie uma conta em `developer.dhl.com`, subscreva esta API e copie a chave para o campo **DHL: chave API**. Atenção às quotas do plano gratuito: a cache e o cron do módulo foram concebidos precisamente para as preservar.

## Mapeamento das transportadoras

A secção **Mapeamento de transportadoras** lista todas as transportadoras da sua loja e permite associar cada uma a um conector. Combinam-se dois mecanismos:

- **Mapeamento explícito**: escolhe o conector na lista pendente. É o método recomendado, sobretudo se as suas transportadoras tiverem nomes comerciais personalizados («Entrega expresso 24h», «Levantamento em ponto de recolha»...).
- **Deteção automática**: nas transportadoras deixadas em «Sem seguimento», o módulo procura palavras-chave no nome da transportadora (`colissimo`, `la poste`, `mondial relay`, `point relais`, `chronopost`, `dhl`...) e aplica o conector correspondente.

O mapeamento apoia-se na **referência da transportadora** (`id_reference`) e não no identificador técnico: sobrevive, portanto, às duplicações de transportadoras que o PrestaShop cria a cada alteração de tarifário.

A deteção automática procura palavras-chave francesas e não reconhece «CTT», «DPD» ou «Nacex». Numa loja portuguesa, deixe essas transportadoras em «Sem seguimento», a menos que passem efetivamente por um dos conectores disponíveis.

## Personalização da página de seguimento

A secção **Marca e apresentação** controla o aspeto da página do front-office:

- **Cor primária**: títulos, etapa em curso da linha de tempo, ligações da transportadora. Por predefinição `#2c3e50`.
- **Cor de destaque**: etapas concluídas e estado «Entregue». Por predefinição `#27ae60`.
- **Título personalizado**: substitui o título predefinido «Seguir a sua encomenda» no topo da página.
- **Mostrar os produtos da encomenda**: acrescenta por baixo da linha de tempo a lista dos artigos com miniaturas e quantidades.
- **Duração da cache (minutos)**: ver a secção seguinte.

As cores são injetadas como variáveis CSS no contentor da página: o resto da disposição herda naturalmente do seu tema.

## Cache e atualização

Cada volume seguido ocupa uma linha da tabela `ps_dftracking_shipment`, que guarda o estado normalizado, os eventos em formato JSON, o URL de seguimento da transportadora e a data e hora da última atualização.

Dois mecanismos mantêm estes dados atualizados:

1. **A tarefa cron**: mecanismo principal. Seleciona os volumes não finalizados cujos dados ultrapassaram a duração da cache, atualiza-os por lotes e regista de passagem as novas expedições das encomendas dos últimos 60 dias.
2. **A atualização na visita**: rede de segurança. Se um cliente consultar a sua página de seguimento com os dados fora de prazo, a API é consultada de imediato.

Em ambos os casos, um volume com o estado **Entregue** ou **Devolvido ao remetente** nunca mais é consultado: estes estados são considerados definitivos.

### Configurar o cron

O URL do cron, incluindo o token, é apresentado no topo da página de configuração do módulo. Programe-o a cada 30 a 60 minutos:

```
*/30 * * * * curl -s "https://asualoja.pt/index.php?fc=module&module=dftracking&controller=cron&token=O_SEU_TOKEN" > /dev/null
```

O parâmetro opcional `&limit=100` limita o número de chamadas à API por execução (50 por predefinição, 200 no máximo). O endpoint responde em JSON: `{"ok":true,"refreshed":12,"errors":0,"time":"…"}`.

O token é o único elemento a proteger este endpoint. Não o publique e regenere-o com o botão **Regenerar o token do cron** se suspeitar que foi divulgado. Nesse caso, lembre-se de atualizar a sua tarefa agendada com o novo URL.

## A página de seguimento do lado do cliente

A página está acessível em `/order-tracking` (URL alterável em **Parâmetros da loja > Tráfego e SEO** depois da instalação).

- **Cliente com sessão iniciada**: o botão «Seguir a minha encomenda» aparece no detalhe de cada encomenda, e é acrescentada uma ligação «Seguimento de encomenda» à área de cliente. O módulo verifica sistematicamente que a encomenda pertence mesmo ao cliente com sessão iniciada.
- **Convidado**: um formulário pede a referência da encomenda e o endereço de e-mail. Os dois têm de corresponder para que a encomenda seja apresentada; em caso de falha, a mensagem de erro é propositadamente genérica e nunca revela se a referência existe.

A linha de tempo global reflete o volume mais avançado da encomenda. Por baixo dela, cada expedição tem o seu próprio cartão: nome da transportadora, número de seguimento, marca de estado colorida, histórico detalhado dos eventos (data, designação, local) e ligação para o seguimento oficial da transportadora.

### Estados normalizados

As designações próprias de cada transportadora são convertidas em sete estados comuns, o que permite uma apresentação homogénea seja qual for o volume:

- **A aguardar recolha**: etiqueta criada, volume ainda não lido.
- **Em trânsito**: o volume circula na rede.
- **Em distribuição**: última etapa, rota do dia.
- **Disponível em ponto de recolha**: volume à espera em ponto de recolha ou em estação.
- **Entregue**: estado final.
- **Incidente de entrega**: anomalia assinalada pela transportadora.
- **Devolvido ao remetente**: estado final.

## Encomendas com vários volumes

O módulo lê a tabela `order_carrier`: cada número de seguimento associado à encomenda é tratado como uma expedição independente, com o seu próprio conector, estado e histórico. Nas lojas antigas em que o número de seguimento só está guardado na encomenda (`shipping_number`), um mecanismo de recurso assegura a compatibilidade.

## Acrescentar uma transportadora

A arquitetura é propositadamente aberta. Para integrar uma transportadora adicional, por exemplo os CTT ou a DPD Portugal:

1. Crie uma classe em `src/Adapter/` que estenda `DftrackingAbstractCarrierAdapter`.
2. Implemente `getCode()`, `getLabel()`, `isConfigured()`, `getPublicUrl()`, `getNameKeywords()` e `fetch()`. Esta última devolve um conjunto `status` / `events` / `tracking_url`, reutilizando as ajudas `httpRequest()`, `event()` e `result()` da classe abstrata.
3. Acrescente a classe ao conjunto de `DftrackingAdapterRegistry::all()` e o `require_once` correspondente em `dftracking.php`.

O novo conector passa a aparecer automaticamente nas listas de mapeamento do back-office.

## Resolução de problemas

- **A página mostra «A sua encomenda ainda não foi expedida»**: não há qualquer número de seguimento na encomenda. Acrescente-o na ficha da encomenda do back-office, separador Transporte.
- **O estado não é atualizado**: confirme primeiro que a tarefa cron é executada, chamando o seu URL manualmente no navegador: a resposta JSON indica o número de volumes atualizados e de erros. Consulte depois **Parâmetros avançados > Registos**: as falhas de chamada à API ficam aí registadas com a mensagem devolvida pela transportadora.
- **Erro «tracking number not found»**: é normal nas horas seguintes à criação da etiqueta, porque a transportadora ainda não registou o volume. O módulo volta a tentar no ciclo seguinte.
- **Uma transportadora não é reconhecida**: a deteção automática não encontrou palavras-chave no nome dela. Associe-a explicitamente na secção Mapeamento de transportadoras.
- **O formulário de convidado não encontra a encomenda**: a referência e o e-mail têm de corresponder exatamente aos da encomenda. Atenção às encomendas feitas com um endereço de e-mail diferente do da conta de cliente.
- **A página não assume as minhas cores**: limpe a cache do PrestaShop (**Parâmetros avançados > Desempenho**) depois da alteração, uma vez que a folha de estilo é colocada em cache pelo tema.

## Desinstalação

A desinstalação elimina a tabela `ps_dftracking_shipment` e todas as chaves de configuração, incluindo as suas credenciais de API. Guarde-as se pretender reinstalar o módulo.