Order Dispatch: exportação das encomendas para um operador logístico / 3PL
Exportar automaticamente as suas encomendas para o seu operador logístico e reimportar os números de seguimento.
Pré-requisitos e compatibilidade
O módulo Order Dispatch funciona em PrestaShop 8.0 a 9.x, com PHP 7.2 no mínimo (testado até PHP 8.3), em loja única ou em multiloja.
- A extensão PHP
ftpé necessária para os transportes FTP e para a recolha dos ficheiros de seguimento por FTP. - A extensão PHP
ssh2só é necessária se utilizar o modo SFTP. Sem ela, use o FTP simples ou a API HTTP. - A extensão
curlé necessária para o transporte por API HTTP e para a recolha a partir de um URL de seguimento. - Recomenda-se acesso ao crontab do seu servidor (ou um serviço de cron externo) para automatizar as exportações.
Instalação
- No back-office, abra Módulos > Gestor de módulos.
- Clique em Carregar um módulo e coloque o arquivo
dforderdispatch-1.0.0.zip. - Terminada a instalação, clique em Configurar.
Na instalação, o módulo cria a sua tabela de registo, regista o hook actionOrderStatusPostUpdate e gera um token de segurança único para os URL de cron.
A desinstalação elimina a tabela de registo e todas as chaves de configuração do módulo. As encomendas e os números de seguimento já gravados não são afetados.
Escolher o formato de exportação
A escolha do formato depende daquilo que o seu operador logístico ou o seu WMS sabe ler. Estão disponíveis três formatos no campo Formato de exportação.
CSV
Uma linha por linha de encomenda, com o cabeçalho da encomenda repetido em cada linha. É o formato mais comum entre os operadores de preparação. O delimitador escolhe-se entre ponto e vírgula e vírgula.
Colunas geradas, por ordem:
order_id ; reference ; date ; payment ; currency ; total_paid ;
shipping_cost ; carrier ; email ; firstname ; lastname ; company ;
phone ; address1 ; address2 ; postcode ; city ; country_iso ;
delivery_note ; sku ; ean13 ; product_name ; quantity ;
unit_price ; line_weightEm Portugal, o Excel e o LibreOffice configurados em português exportam e leem CSV com ponto e vírgula. Se o seu operador logístico pedir um ficheiro que abra diretamente numa folha de cálculo, mantenha o ponto e vírgula como delimitador.
Ficheiro plano EDI
Formato com registos separados por barras verticais e fins de linha CRLF. Cada encomenda produz um registo de cabeçalho H seguido de um registo L por linha de encomenda.
H|referencia|data|transportadora|apelido|nome|morada1|morada2|codigo_postal|localidade|pais|telefone|email|peso
L|referencia|sku|ean13|quantidade|designacaoExemplo concreto:
H|XKBKNABJK|2026-07-05 10:00:00|CTT Expresso|Silva|João|Rua Augusta 100||1100-053|Lisboa|PT|+351912000000|joao@exemplo.pt|1.2
L|XKBKNABJK|SKU-114|1234567890123|2|Sapatilhas de pele premiumQualquer barra vertical presente num dado (designação de produto, morada) é automaticamente substituída por um espaço, para não partir a estrutura do ficheiro. As quebras de linha nos campos são igualmente neutralizadas.
API JSON
Carga estruturada, adequada aos operadores logísticos que expõem uma API moderna. O lote completo é enviado num único objeto com a data de geração e um conjunto de encomendas, cada uma com o seu cabeçalho, o seu cliente, a sua morada de entrega e as suas linhas.
Escolher o transporte
O campo Transporte determina como o ficheiro gerado chega ao seu prestador.
Descarregamento
Sem envio automático. O botão Exportar agora gera o ficheiro e descarrega-o diretamente no seu navegador. Útil para testar um formato ou para um prestador que recolhe os ficheiros manualmente.
FTP
Preencha o servidor, a porta (21 por predefinição), o utilizador, a palavra-passe e o diretório remoto das encomendas. O modo passivo está ativo por predefinição e serve à maioria dos alojamentos.
O campo da palavra-passe fica vazio na apresentação, por razões de segurança. Deixe-o vazio ao gravar para conservar a palavra-passe já existente.
SFTP
Ative a opção Utilizar SFTP e indique a porta SSH (22, em regra) no campo da porta. As credenciais de FTP servem também para o SFTP. Esta opção exige a extensão PHP ssh2 no servidor.
API HTTP
O lote completo é enviado por POST para o URL do seu prestador, com o corpo do pedido a conter diretamente o ficheiro gerado. O envio é acompanhado de dois cabeçalhos:
X-DFOD-KEY: a chave de API que introduziu na configuração.X-DFOD-FILENAME: o nome de ficheiro calculado segundo o seu padrão.
O tipo de conteúdo é adaptado ao formato escolhido (JSON, CSV ou texto simples). Qualquer resposta HTTP fora do intervalo 2xx é considerada uma falha e registada como tal.
Seleção das encomendas e planeamento
Estados de encomenda de origem
Em Estados de encomenda a exportar, selecione um ou mais estados (tipicamente Pagamento aceite e Em preparação). Só são retidas as encomendas que se encontrem num destes estados e que nunca tenham sido exportadas com sucesso.
Mudança de estado após a exportação
O campo Estado após a exportação permite passar automaticamente as encomendas exportadas para um estado de acompanhamento dedicado. Deixe em «Sem alteração» se preferir conservar o estado de origem.
Limite por lote
O campo Número máximo de encomendas por lote limita a dimensão de uma exportação. Em lojas de grande volume, um valor entre 100 e 300 evita ficheiros demasiado pesados e tempos de execução excessivos.
Cron de exportação
O URL de cron, protegido por um token único, é apresentado no topo da página de configuração. Acrescente-o ao seu crontab:
*/15 * * * * curl -s "https://a-sua-loja.pt/module/dforderdispatch/cron?token=O_SEU_TOKEN" > /dev/nullO cron devolve um objeto JSON com o lote gerado, o número de encomendas exportadas, o nome do ficheiro e a mensagem de transporte, o que permite vigiá-lo a partir de uma ferramenta de supervisão.
Modo auto-push
Ative Envio automático na mudança de estado para transmitir cada encomenda individualmente assim que entra num estado exportável, sem esperar pela próxima passagem do cron. Este modo apoia-se nos transportes FTP, SFTP ou API. Não tem efeito com o transporte por Descarregamento.
Os dois modos podem coexistir: o auto-push trata as encomendas à medida que surgem e o cron recupera as que tenham falhado, com a desduplicação a impedir qualquer envio em duplicado.
Nome dos ficheiros gerados
O campo Padrão do nome de ficheiro aceita duas variáveis:
{date}: data e hora no formato AAAAMMDD-HHMMSS.{batch}: identificador único do lote, também presente no registo.
A extensão é acrescentada automaticamente conforme o formato: .csv, .txt para o EDI e .json. Os caracteres não alfanuméricos são retirados do nome final.
Reimportação dos números de seguimento
Estão disponíveis três canais, utilizáveis em simultâneo. Em todos os casos, o número recebido é escrito na transportadora da encomenda e no campo de seguimento da encomenda, sendo depois aplicado o estado configurado em Estado após a importação do seguimento (em regra, Enviado).
Canal 1: carregamento manual de CSV
No painel Importação dos seguimentos da página de configuração, selecione um ficheiro CSV e inicie a importação. O mapeamento configura-se nas definições:
- Delimitador: ponto e vírgula ou vírgula.
- Índice da coluna da referência: 0 corresponde à primeira coluna.
- Índice da coluna do seguimento: idem.
- Linha de cabeçalho: a ativar se a primeira linha contiver os nomes das colunas.
Exemplo de ficheiro esperado com o mapeamento predefinido:
reference;tracking
XKBKNABJK;DW123456789PT
1024;DW987654321PTA coluna da referência aceita indistintamente a referência de encomenda do PrestaShop ou o identificador numérico da encomenda.
Canal 2: recolha automática (cron pull)
Podem ser indicadas duas origens, tratadas uma a seguir à outra em cada execução:
- Diretório FTP dos seguimentos: o módulo lista os ficheiros .csv e .txt da pasta, importa-os e pode eliminá-los em seguida, se a opção correspondente estiver ativa. As credenciais de FTP são as da secção de transporte.
- URL de recolha: um endereço HTTP ou HTTPS que devolva diretamente um CSV de seguimentos.
Acrescente o URL de pull ao seu crontab, por exemplo de hora a hora:
0 * * * * curl -s "https://a-sua-loja.pt/module/dforderdispatch/tracking?token=O_SEU_TOKEN&mode=pull" > /dev/nullCanal 3: webhook enviado pelo operador logístico
Comunique ao seu prestador o URL de push apresentado na configuração. Basta-lhe enviar um pedido POST com um corpo JSON:
POST /module/dforderdispatch/tracking?token=O_SEU_TOKEN&mode=push
Content-Type: application/json
[
{"reference": "XKBKNABJK", "tracking": "DW123456789PT"},
{"reference": "1024", "tracking": "DW987654321PT"}
]Também é aceite um objeto envolvente da forma {"items": [ ... ]}. A resposta é um relatório JSON com o número de encomendas atualizadas, ignoradas e com erro, e o detalhe linha a linha.
Registo e supervisão
O fundo da página de configuração mostra as cinquenta últimas operações, tanto exportações como importações, cada uma com a data, a encomenda em causa, o identificador do lote, o sentido, o formato, o transporte, o estado e a mensagem devolvida.
A desduplicação apoia-se neste registo: uma encomenda com uma entrada de exportação no estado «sent» nunca mais será incluída num lote seguinte. Para forçar uma reexportação, elimine a linha correspondente na tabela de registo do módulo.
Resolução de problemas
A exportação não devolve qualquer encomenda
Confirme que estão mesmo selecionados estados nas definições e que existem encomendas nesses estados. Verifique depois que essas encomendas não foram já exportadas com sucesso num lote anterior.
O cron devolve um erro de token
O token apresentado na configuração tem de ser usado tal e qual no URL, sem espaços nem caracteres acrescentados. Copie-o diretamente da página de configuração.
A transferência FTP falha
Verifique o servidor, a porta e as credenciais, e confirme que o diretório remoto existe e permite escrita. Se o seu alojamento bloquear as ligações de saída, poderá ser necessário o modo passivo ou a abertura do fluxo.
O SFTP está indisponível
A mensagem que indica que a extensão ssh2 não está disponível significa que não está instalada no servidor. Peça a sua ativação ao seu alojamento, ou passe para o FTP simples ou para a API HTTP.
Um número de seguimento é recusado
Os números de seguimento são validados segundo as regras do PrestaShop. Um número com caracteres não autorizados é rejeitado e registado como erro, sem bloquear o resto da importação.
Perguntas frequentes
Posso exportar para vários prestadores?
O módulo gere um fluxo de saída configurado de cada vez. Para alimentar dois prestadores distintos, a prática mais simples é distinguir as encomendas por estados diferentes e tratar cada fluxo em separado.
As encomendas em multiloja são suportadas?
Sim, o módulo funciona em contexto multiloja. As definições de configuração seguem o contexto PrestaShop em que foram gravadas.
O que acontece se o prestador estiver inacessível?
A falha é registada com a respetiva mensagem de erro e as encomendas em causa não são marcadas como enviadas. Serão, por isso, automaticamente retomadas na próxima passagem do cron, sem qualquer intervenção da sua parte.
A mudança de estado despoleta os e-mails para o cliente?
Sim. O módulo usa o mecanismo padrão de mudança de estado do PrestaShop. As notificações associadas ao estado de destino, nomeadamente o e-mail de expedição com o número de seguimento, são portanto enviadas normalmente.