Order Dispatch — Exportación de pedidos a un operador logístico / 3PL
Exportar automáticamente tus pedidos a tu operador logístico y reimportar los números de seguimiento.
Requisitos y compatibilidad
Order Dispatch funciona en PrestaShop 8.0 a 9.x, con PHP 7.2 como mínimo (probado hasta PHP 8.3), tanto en tienda única como en multitienda.
- La extensión PHP
ftpes necesaria para los transportes FTP y para recuperar los ficheros de seguimiento por FTP. - La extensión PHP
ssh2solo es necesaria si utilizas el modo SFTP. Sin ella, usa el FTP simple o la API HTTP. - La extensión
curles necesaria para el transporte API HTTP y para recuperar una URL de seguimiento. - Se recomienda tener acceso al crontab de tu servidor (o a un servicio de cron externo) para automatizar las exportaciones.
Instalación
- Desde el back office, abre Módulos > Gestor de módulos.
- Haz clic en Subir un módulo y suelta el archivo
dforderdispatch-1.0.0.zip. - Cuando termine la instalación, haz clic en Configurar.
En la instalación, el módulo crea su tabla de registro, registra el hook actionOrderStatusPostUpdate y genera un token de seguridad único para las URL de cron.
La desinstalación elimina la tabla de registro y todas las claves de configuración del módulo. Los pedidos y los números de seguimiento ya guardados no se ven afectados.
Elegir el formato de exportación
El formato adecuado depende de lo que tu operador logístico o tu WMS sepa leer. Hay tres formatos disponibles en el campo Formato de exportación.
CSV
Una línea por línea de pedido, con la cabecera del pedido repetida en cada línea. Es el formato más habitual entre los preparadores. El delimitador puede ser punto y coma o coma.
Columnas generadas, en orden:
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_weightFichero plano EDI
Formato de registros separados por barras verticales, con final de línea CRLF. Cada pedido genera un registro de cabecera H seguido de un registro L por línea de pedido.
H|referencia|fecha|transportista|apellido|nombre|direccion1|direccion2|cp|ciudad|pais|telefono|email|peso
L|referencia|sku|ean13|cantidad|descripcionEjemplo concreto:
H|XKBKNABJK|2026-07-05 10:00:00|Colissimo|Dupont|Jean|1 rue de la Paix||06000|Nice|FR|0600000000|[email protected]|1.2
L|XKBKNABJK|SKU-114|1234567890123|2|Zapatillas de cuero premiumCualquier barra vertical presente en los datos (nombre de producto, dirección) se sustituye automáticamente por un espacio para no romper la estructura del fichero. Los saltos de línea dentro de los campos también se neutralizan.
API JSON
Carga útil estructurada, adecuada para operadores que exponen una API moderna. El lote completo se envía en un único objeto que contiene la fecha de generación y un array de pedidos, cada uno con su cabecera, su cliente, su dirección de entrega y sus líneas.
Elegir el transporte
El campo Transporte determina cómo llega el fichero generado a tu proveedor.
Descarga
Sin envío automático. El botón Exportar ahora genera el fichero y lo descarga directamente en tu navegador. Útil para probar un formato o para un proveedor que recoge los ficheros manualmente.
FTP
Indica el host, el puerto (21 por defecto), el usuario, la contraseña y el directorio remoto de los pedidos. El modo pasivo está activado por defecto y funciona en la mayoría de alojamientos.
El campo de contraseña se muestra vacío por motivos de seguridad. Déjalo vacío al guardar para conservar la contraseña ya establecida.
SFTP
Activa la opción Usar SFTP e indica el puerto SSH (normalmente 22) en el campo de puerto. Las credenciales FTP se reutilizan para el SFTP. Esta opción requiere la extensión PHP ssh2 en el servidor.
API HTTP
El lote completo se envía por POST a la URL de tu proveedor, con el cuerpo de la petición conteniendo directamente el fichero generado. El envío va acompañado de dos cabeceras:
X-DFOD-KEY: la clave de API que has introducido en la configuración.X-DFOD-FILENAME: el nombre de fichero calculado según tu patrón.
El tipo de contenido se adapta al formato elegido (JSON, CSV o texto plano). Cualquier respuesta HTTP fuera del rango 2xx se considera un fallo y se registra como tal.
Selección de pedidos y planificación
Estados de pedido de origen
En Estados de pedido a exportar, selecciona uno o varios estados (habitualmente Pago aceptado y En preparación). Solo se toman los pedidos que están en uno de esos estados y que nunca se han exportado con éxito.
Cambio de estado tras la exportación
El campo Estado tras la exportación permite mover automáticamente los pedidos exportados a un estado de seguimiento dedicado. Déjalo en «Sin cambio» si prefieres conservar el estado original.
Límite por lote
El campo Número máximo de pedidos por lote limita el tamaño de una exportación. En tiendas de alto volumen, un valor entre 100 y 300 evita ficheros demasiado pesados y tiempos de ejecución excesivos.
Cron de exportación
La URL de cron, protegida por un token único, se muestra en la parte superior de la página de configuración. Añádela a tu crontab:
*/15 * * * * curl -s "https://tu-tienda.es/module/dforderdispatch/cron?token=TU_TOKEN" > /dev/nullEl cron devuelve un objeto JSON con el lote generado, el número de pedidos exportados, el nombre del fichero y el mensaje de transporte, lo que permite supervisarlo desde una herramienta de monitorización.
Modo auto-push
Activa Envío automático al cambiar de estado para transmitir cada pedido individualmente en cuanto entra en un estado exportable, sin esperar al siguiente paso del cron. Este modo se apoya en los transportes FTP, SFTP o API. No tiene efecto con el transporte Descarga.
Ambos modos pueden coexistir: el auto-push procesa los pedidos sobre la marcha y el cron recupera los que hayan fallado, mientras la deduplicación impide cualquier envío duplicado.
Nombre de los ficheros generados
El campo Patrón de nombre de fichero acepta dos variables:
{date}: marca de tiempo en formato AAAAMMDD-HHMMSS.{batch}: identificador único del lote, que también aparece en el registro.
La extensión se añade automáticamente según el formato: .csv, .txt para el EDI y .json. Los caracteres no alfanuméricos se eliminan del nombre final.
Reimportación de los números de seguimiento
Hay tres canales disponibles, utilizables simultáneamente. En todos los casos, el número recibido se escribe en el transportista del pedido y en el campo de seguimiento del pedido, y después se aplica el estado configurado en Estado tras la importación del seguimiento (normalmente Enviado).
Canal 1: subida manual de CSV
Desde el panel Importación de seguimientos de la página de configuración, selecciona un fichero CSV y lanza la importación. El mapeo se configura en los ajustes:
- Delimitador: punto y coma o coma.
- Índice de la columna de referencia: 0 corresponde a la primera columna.
- Índice de la columna de seguimiento: mismo principio.
- Fila de cabecera: actívala si la primera línea contiene los nombres de columna.
Fichero esperado con el mapeo por defecto:
reference;tracking
XKBKNABJK;8R001234567FR
1024;6A987654321FRLa columna de referencia acepta indistintamente la referencia de pedido de PrestaShop o el identificador numérico del pedido.
Canal 2: recuperación automática (cron pull)
Se pueden configurar dos fuentes, que se procesan una tras otra en cada ejecución:
- Directorio FTP de seguimientos: el módulo lista los ficheros .csv y .txt de la carpeta, los importa y puede eliminarlos después si la opción correspondiente está activada. Las credenciales FTP son las de la sección de transporte.
- URL de recuperación: una dirección HTTP o HTTPS que devuelva directamente un CSV de seguimientos.
Añade la URL de pull a tu crontab, por ejemplo cada hora:
0 * * * * curl -s "https://tu-tienda.es/module/dforderdispatch/tracking?token=TU_TOKEN&mode=pull" > /dev/nullCanal 3: webhook enviado por el operador logístico
Facilita a tu proveedor la URL de push que aparece en la configuración. Solo tiene que enviar una petición POST con un cuerpo JSON:
POST /module/dforderdispatch/tracking?token=TU_TOKEN&mode=push
Content-Type: application/json
[
{"reference": "XKBKNABJK", "tracking": "8R001234567FR"},
{"reference": "1024", "tracking": "6A987654321FR"}
]También se acepta un objeto envolvente de la forma {"items": [ ... ]}. La respuesta es un informe JSON que detalla cuántos pedidos se han actualizado, omitido y con error, con el detalle línea a línea.
Registro y supervisión
La parte inferior de la página de configuración muestra las últimas cincuenta operaciones, tanto exportaciones como importaciones, cada una con su fecha, el pedido afectado, el identificador del lote, el sentido, el formato, el transporte, el estado y el mensaje devuelto.
La deduplicación se basa en este registro: un pedido con una entrada de exportación en estado «sent» nunca se volverá a incluir en un lote posterior. Para forzar una reexportación, elimina la fila correspondiente en la tabla de registro del módulo.
Resolución de problemas
La exportación no devuelve ningún pedido
Comprueba que hay estados seleccionados en los ajustes y que realmente existen pedidos en ellos. Comprueba después que esos pedidos no se han exportado ya con éxito en un lote anterior.
El cron devuelve un error de token
El token que aparece en la configuración debe copiarse en la URL tal cual, sin espacios ni caracteres añadidos. Cópialo directamente desde la página de configuración.
La transferencia FTP falla
Verifica el host, el puerto y las credenciales, y comprueba después que el directorio remoto existe y admite escritura. Si tu alojamiento bloquea las conexiones salientes, puede ser necesario el modo pasivo o una apertura de puertos.
El SFTP no está disponible
El mensaje que indica que la extensión ssh2 no está disponible significa que no está instalada en el servidor. Pide a tu alojamiento que la active, o cambia al FTP simple o a la API HTTP.
Un número de seguimiento es rechazado
Los números de seguimiento se validan según las reglas de PrestaShop. Un número con caracteres no permitidos se rechaza y se registra como error, sin bloquear el resto de la importación.
Preguntas frecuentes
¿Puedo exportar a varios proveedores?
El módulo gestiona un flujo saliente configurado a la vez. Para alimentar dos proveedores distintos, lo más sencillo es separar los pedidos mediante estados diferentes y tratar cada flujo por separado.
¿Se admiten los pedidos en multitienda?
Sí, el módulo funciona en contexto multitienda. Los ajustes de configuración siguen el contexto de PrestaShop en el que se guardaron.
¿Qué ocurre si el proveedor no está accesible?
El fallo se registra con su mensaje de error y los pedidos afectados no se marcan como enviados. Por tanto, se retomarán automáticamente en el siguiente paso del cron, sin que tengas que intervenir.
¿El cambio de estado activa los correos al cliente?
Sí. El módulo utiliza el mecanismo estándar de cambio de estado de PrestaShop. Las notificaciones asociadas al estado de destino, en particular el correo de envío con el número de seguimiento, se envían con normalidad.