Order Dispatch — Bestellexport an einen Logistikdienstleister / 3PL

Voraussetzungen und Kompatibilität

Order Dispatch läuft unter PrestaShop 8.0 bis 9.x, mit PHP 7.2 als Minimum (getestet bis PHP 8.3), sowohl im Einzelshop als auch im Multishop.

• Die PHP-Erweiterung ftp wird für die FTP-Transporte und für das Abholen der Tracking-Dateien per FTP benötigt.
• Die PHP-Erweiterung ssh2 wird nur benötigt, wenn Sie den SFTP-Modus verwenden. Ohne sie nutzen Sie einfaches FTP oder die HTTP-API.
• Die Erweiterung curl wird für den HTTP-API-Transport und für den Abruf einer Tracking-URL benötigt.
• Zugriff auf die Crontab Ihres Servers (oder ein externer Cron-Dienst) wird empfohlen, um die Exporte zu automatisieren.

Installation

1. Öffnen Sie im Backoffice Module > Modul-Manager.
2. Klicken Sie auf Modul hochladen und legen Sie das Archiv dforderdispatch-1.0.0.zip ab.
3. Klicken Sie nach Abschluss der Installation auf Konfigurieren.

Bei der Installation legt das Modul seine Protokolltabelle an, registriert den Hook actionOrderStatusPostUpdate und erzeugt ein eindeutiges Sicherheitstoken für die Cron-URLs.

Das Exportformat wählen

Das passende Format hängt davon ab, was Ihr Logistikdienstleister oder Ihr WMS lesen kann. Im Feld Exportformat stehen drei Formate zur Verfügung.

CSV

Eine Zeile pro Bestellposition, wobei der Bestellkopf in jeder Zeile wiederholt wird. Das ist die gängigste Struktur bei Fulfillment-Dienstleistern. Als Trennzeichen stehen Semikolon oder Komma zur Wahl.

Erzeugte Spalten, in dieser Reihenfolge:

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

EDI-Flatfile

Format mit pipe-getrennten Datensätzen und CRLF-Zeilenenden. Jede Bestellung erzeugt einen Kopfdatensatz H, gefolgt von je einem Datensatz L pro Bestellposition.

H|Referenz|Datum|Versanddienstleister|Nachname|Vorname|Adresse1|Adresse2|PLZ|Ort|Land|Telefon|E-Mail|Gewicht
L|Referenz|SKU|EAN13|Menge|Bezeichnung

Konkretes Beispiel:

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|Premium-Ledersneaker

JSON-API

Strukturierte Nutzlast, passend für Dienstleister mit moderner API. Der gesamte Batch wird als ein einziges Objekt gesendet, das das Erzeugungsdatum und ein Array von Bestellungen enthält, jede mit Kopf, Kunde, Lieferadresse und Positionen.

Den Transport wählen

Das Feld Transport bestimmt, wie die erzeugte Datei zu Ihrem Dienstleister gelangt.

Download

Kein automatischer Versand. Die Schaltfläche Jetzt exportieren erzeugt die Datei und lädt sie direkt in Ihrem Browser herunter. Nützlich zum Testen eines Formats oder für einen Dienstleister, der die Dateien manuell abholt.

FTP

Tragen Sie Host, Port (standardmäßig 21), Benutzername, Passwort und das entfernte Bestellverzeichnis ein. Der Passivmodus ist standardmäßig aktiviert und passt zu den meisten Hosting-Umgebungen.

SFTP

Aktivieren Sie die Option SFTP verwenden und tragen Sie den SSH-Port (in der Regel 22) im Portfeld ein. Die FTP-Zugangsdaten werden auch für SFTP verwendet. Diese Option setzt die PHP-Erweiterung ssh2 auf dem Server voraus.

HTTP-API

Der gesamte Batch wird per POST an die URL Ihres Dienstleisters gesendet, wobei der Anfragekörper direkt die erzeugte Datei enthält. Zwei Header begleiten den Versand:

• X-DFOD-KEY: der API-Schlüssel, den Sie in der Konfiguration eingetragen haben.
• X-DFOD-FILENAME: der aus Ihrem Muster berechnete Dateiname.

Der Inhaltstyp richtet sich nach dem gewählten Format (JSON, CSV oder reiner Text). Jede HTTP-Antwort außerhalb des Bereichs 2xx gilt als Fehlschlag und wird entsprechend protokolliert.

Bestellauswahl und Planung

Quell-Bestellstatus

Wählen Sie unter Zu exportierende Bestellstatus einen oder mehrere Status aus (typischerweise Zahlung akzeptiert und In Bearbeitung). Berücksichtigt werden nur Bestellungen in einem dieser Status, die noch nie erfolgreich exportiert wurden.

Statuswechsel nach dem Export

Das Feld Status nach dem Export verschiebt exportierte Bestellungen automatisch in einen eigenen Verfolgungsstatus. Belassen Sie es auf „Keine Änderung“, wenn Sie den ursprünglichen Status behalten möchten.

Batch-Limit

Das Feld Maximale Bestellungen pro Batch begrenzt die Größe eines Exports. Bei Shops mit hohem Volumen vermeidet ein Wert zwischen 100 und 300 zu große Dateien und überlange Laufzeiten.

Export-Cron

Die per eindeutigem Token geschützte Cron-URL wird oben auf der Konfigurationsseite angezeigt. Fügen Sie sie Ihrer Crontab hinzu:

*/15 * * * * curl -s "https://ihr-shop.de/module/dforderdispatch/cron?token=IHR_TOKEN" > /dev/null

Der Cron gibt ein JSON-Objekt mit dem erzeugten Batch, der Anzahl exportierter Bestellungen, dem Dateinamen und der Transportmeldung zurück, was die Überwachung aus einem Monitoring-Werkzeug heraus erleichtert.

Auto-Push-Modus

Aktivieren Sie Automatischer Versand bei Statuswechsel, um jede Bestellung einzeln zu übermitteln, sobald sie in einen exportierbaren Status wechselt, ohne auf den nächsten Cron-Lauf zu warten. Dieser Modus nutzt die Transporte FTP, SFTP oder API. Beim Transport Download bleibt er wirkungslos.

Namen der erzeugten Dateien

Das Feld Dateinamensmuster akzeptiert zwei Variablen:

• {date}: Zeitstempel im Format JJJJMMTT-HHMMSS.
• {batch}: eindeutige Batch-Kennung, die auch im Protokoll erscheint.

Die Endung wird je nach Format automatisch ergänzt: .csv, .txt für EDI und .json. Nicht alphanumerische Zeichen werden aus dem endgültigen Namen entfernt.

Rückimport der Sendungsnummern

Drei Kanäle stehen zur Verfügung und können gleichzeitig genutzt werden. In allen Fällen wird die empfangene Nummer beim Versanddienstleister der Bestellung sowie im Sendungsnummernfeld der Bestellung eingetragen, anschließend wird der unter Status nach Tracking-Import konfigurierte Status angewendet (meist Versendet).

Kanal 1: manueller CSV-Upload

Wählen Sie im Bereich Tracking-Import der Konfigurationsseite eine CSV-Datei aus und starten Sie den Import. Die Zuordnung wird in den Einstellungen konfiguriert:

• Trennzeichen: Semikolon oder Komma.
• Spaltenindex der Referenz: 0 entspricht der ersten Spalte.
• Spaltenindex der Sendungsnummer: gleiches Prinzip.
• Kopfzeile: aktivieren, wenn die erste Zeile die Spaltennamen enthält.

Erwartete Datei bei Standardzuordnung:

reference;tracking
XKBKNABJK;8R001234567FR
1024;6A987654321FR

Die Referenzspalte akzeptiert wahlweise die PrestaShop-Bestellreferenz oder die numerische Bestell-ID.

Kanal 2: automatischer Abruf (Cron-Pull)

Es lassen sich zwei Quellen hinterlegen, die bei jedem Lauf nacheinander verarbeitet werden:

• Tracking-FTP-Verzeichnis: Das Modul listet die Dateien .csv und .txt im Ordner auf, importiert sie und kann sie anschließend löschen, wenn die entsprechende Option aktiviert ist. Verwendet werden die FTP-Zugangsdaten aus dem Transportbereich.
• Abruf-URL: eine HTTP- oder HTTPS-Adresse, die direkt eine Tracking-CSV zurückgibt.

Fügen Sie die Pull-URL Ihrer Crontab hinzu, zum Beispiel stündlich:

0 * * * * curl -s "https://ihr-shop.de/module/dforderdispatch/tracking?token=IHR_TOKEN&mode=pull" > /dev/null

Kanal 3: vom Dienstleister gesendeter Webhook

Geben Sie Ihrem Dienstleister die in der Konfiguration angezeigte Push-URL. Er muss lediglich eine POST-Anfrage mit einem JSON-Körper senden:

POST /module/dforderdispatch/tracking?token=IHR_TOKEN&mode=push
Content-Type: application/json

[
  {"reference": "XKBKNABJK", "tracking": "8R001234567FR"},
  {"reference": "1024", "tracking": "6A987654321FR"}
]

Ein umschließendes Objekt der Form {"items": [ ... ]} wird ebenfalls akzeptiert. Die Antwort ist ein JSON-Bericht mit der Anzahl aktualisierter, übersprungener und fehlerhafter Bestellungen, samt zeilenweiser Detailangabe.

Protokoll und Überwachung

Am unteren Ende der Konfigurationsseite werden die letzten fünfzig Vorgänge angezeigt, Exporte wie Importe, jeweils mit Datum, betroffener Bestellung, Batch-Kennung, Richtung, Format, Transport, Status und zurückgegebener Meldung.

Die Deduplizierung stützt sich auf dieses Protokoll: Eine Bestellung mit einem Exporteintrag im Status „sent“ wird nie wieder in einen späteren Batch aufgenommen. Um einen erneuten Export zu erzwingen, löschen Sie die entsprechende Zeile in der Protokolltabelle des Moduls.

Fehlerbehebung

Der Export liefert keine Bestellungen

Prüfen Sie, ob in den Einstellungen tatsächlich Status ausgewählt sind und ob sich Bestellungen darin befinden. Prüfen Sie anschließend, ob diese Bestellungen nicht bereits in einem früheren Batch erfolgreich exportiert wurden.

Der Cron meldet einen Token-Fehler

Das in der Konfiguration angezeigte Token muss unverändert in die URL übernommen werden, ohne zusätzliche Leer- oder Sonderzeichen. Kopieren Sie es direkt von der Konfigurationsseite.

Die FTP-Übertragung schlägt fehl

Prüfen Sie Host, Port und Zugangsdaten und stellen Sie anschließend sicher, dass das entfernte Verzeichnis existiert und beschreibbar ist. Falls Ihr Hoster ausgehende Verbindungen blockiert, kann der Passivmodus oder eine Firewall-Freigabe nötig sein.

SFTP ist nicht verfügbar

Die Meldung, dass die Erweiterung ssh2 nicht verfügbar ist, bedeutet, dass sie auf dem Server nicht installiert ist. Bitten Sie Ihren Hoster um die Aktivierung oder wechseln Sie zu einfachem FTP oder zur HTTP-API.

Eine Sendungsnummer wird abgelehnt

Sendungsnummern werden nach den PrestaShop-Regeln validiert. Eine Nummer mit unzulässigen Zeichen wird abgelehnt und als Fehler protokolliert, ohne den restlichen Import zu blockieren.

Häufige Fragen

Kann ich an mehrere Dienstleister exportieren?

Das Modul verwaltet jeweils einen konfigurierten ausgehenden Fluss. Um zwei verschiedene Dienstleister zu beliefern, ist es am einfachsten, die Bestellungen über unterschiedliche Status zu trennen und jeden Fluss separat zu behandeln.

Werden Multishop-Bestellungen unterstützt?

Ja, das Modul funktioniert im Multishop-Kontext. Die Konfigurationseinstellungen folgen dem PrestaShop-Kontext, in dem sie gespeichert wurden.

Was passiert, wenn der Dienstleister nicht erreichbar ist?

Der Fehlschlag wird mit seiner Fehlermeldung protokolliert und die betroffenen Bestellungen werden nicht als gesendet markiert. Sie werden daher beim nächsten Cron-Lauf automatisch erneut berücksichtigt, ohne dass Sie eingreifen müssen.

Löst der Statuswechsel Kunden-E-Mails aus?

Ja. Das Modul nutzt den Standardmechanismus für Statuswechsel von PrestaShop. Die dem Zielstatus zugeordneten Benachrichtigungen, insbesondere die Versand-E-Mail mit der Sendungsnummer, werden also normal versendet.