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), 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.

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.

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":"…"}.

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.