# Order Dispatch: exportação das encomendas para um operador logístico / 3PL
> Guia completo do módulo Order Dispatch: instalação, formatos de exportação CSV / EDI / JSON, transportes FTP, SFTP e API, planeamento por cron e reimportação dos números de seguimento.
- Página:
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dforderdispatch/index.md), [en](https://www.datafirefly.com/en/documentation/dforderdispatch/index.md), [es](https://www.datafirefly.com/es/documentation/dforderdispatch/index.md), [de](https://www.datafirefly.com/de/documentation/dforderdispatch/index.md), [it](https://www.datafirefly.com/it/documentation/dforderdispatch/index.md), [pl](https://www.datafirefly.com/pl/documentation/dforderdispatch/index.md), [nl](https://www.datafirefly.com/nl/documentation/dforderdispatch/index.md)
- Índice:
## 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 `ssh2` só é 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
1. No back-office, abra **Módulos > Gestor de módulos**.
2. Clique em **Carregar um módulo** e coloque o arquivo `dforderdispatch-1.0.0.zip`.
3. 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_weight
```
Em 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|designacao
```
Exemplo 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 premium
```
Qualquer 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/null
```
O 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;DW987654321PT
```
A 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/null
```
### Canal 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.