Order Dispatch: bestellingen exporteren naar een logistiek dienstverlener / 3PL

Vereisten en compatibiliteit

De module Order Dispatch werkt op PrestaShop 8.0 tot 9.x, met minimaal PHP 7.2 (getest tot PHP 8.3), zowel in single-shop als in multistore.

• De PHP-extensie ftp is vereist voor FTP-transport en voor het ophalen van trackingbestanden via FTP.
• De PHP-extensie ssh2 is alleen nodig als u de SFTP-modus gebruikt. Zonder deze extensie kiest u gewoon FTP of de HTTP-API.
• De extensie curl is vereist voor het HTTP-API-transport en voor het ophalen van een tracking-URL.
• Toegang tot de crontab van uw server (of een externe crondienst) wordt aanbevolen om de exports te automatiseren.

Installatie

1. Open in de back-office Modules > Modulebeheer.
2. Klik op Een module installeren en sleep het archief dforderdispatch-1.0.0.zip erin.
3. Klik na de installatie op Configureren.

Bij de installatie maakt de module haar logtabel aan, registreert ze de hook actionOrderStatusPostUpdate en genereert ze een uniek beveiligingstoken voor de cron-URL’s.

Het exportformaat kiezen

De keuze van het formaat hangt af van wat uw logistiek dienstverlener of WMS kan inlezen. Drie formaten zijn beschikbaar in het veld Exportformaat.

CSV

Eén regel per bestelregel, waarbij de orderkop op elke regel wordt herhaald. Dit is het meest gangbare formaat bij fulfilmentbedrijven. Als scheidingsteken kiest u tussen puntkomma en komma.

Gegenereerde kolommen, in volgorde:

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

Plat EDI-bestand

Formaat met records gescheiden door verticale strepen en regeleinden in CRLF. Elke bestelling levert een kopregel H op, gevolgd door een record L per bestelregel.

H|referentie|datum|vervoerder|naam|voornaam|adres1|adres2|postcode|plaats|land|telefoon|email|gewicht
L|referentie|sku|ean13|aantal|omschrijving

Concreet voorbeeld:

H|XKBKNABJK|2026-07-05 10:00:00|PostNL|Jansen|Jan|Keizersgracht 1||1015 CJ|Amsterdam|NL|0600000000|jan@voorbeeld.nl|1.2
L|XKBKNABJK|SKU-114|1234567890123|2|Premium leren sneakers

JSON-API

Gestructureerde payload, geschikt voor dienstverleners met een moderne API. De volledige batch wordt in één object verzonden, met de generatiedatum en een array van bestellingen, elk met kop, klant, afleveradres en bestelregels.

Het transport kiezen

Het veld Transport bepaalt hoe het gegenereerde bestand bij uw dienstverlener terechtkomt.

Download

Geen automatische verzending. De knop Nu exporteren genereert het bestand en downloadt het rechtstreeks in uw browser. Handig om een formaat te testen of voor een dienstverlener die de bestanden handmatig ophaalt.

FTP

Vul de host, de poort (standaard 21), de gebruikersnaam, het wachtwoord en de externe ordermap in. De passieve modus staat standaard aan en volstaat voor de meeste hostings.

SFTP

Activeer de optie SFTP gebruiken en vul de SSH-poort in (doorgaans 22) in het poortveld. De FTP-gegevens dienen ook voor SFTP. Deze optie vereist de PHP-extensie ssh2 op de server.

HTTP-API

De volledige batch wordt via POST naar de URL van uw dienstverlener gestuurd, waarbij de body van het verzoek rechtstreeks het gegenereerde bestand bevat. Twee headers gaan mee met de verzending:

• X-DFOD-KEY: de API-sleutel die u in de configuratie hebt ingevuld.
• X-DFOD-FILENAME: de bestandsnaam berekend volgens uw patroon.

Het contenttype wordt aangepast aan het gekozen formaat (JSON, CSV of platte tekst). Elk HTTP-antwoord buiten het 2xx-bereik geldt als mislukking en wordt als zodanig gelogd.

Selectie van bestellingen en planning

Bronstatussen van bestellingen

Selecteer in Te exporteren orderstatussen een of meer statussen (doorgaans Betaling aanvaard en In voorbereiding). Alleen bestellingen die zich in een van deze statussen bevinden en nog nooit met succes zijn geëxporteerd, worden meegenomen.

Statuswijziging na export

Met het veld Status na export laat u geëxporteerde bestellingen automatisch overgaan naar een speciale opvolgstatus. Laat het op “Geen wijziging” staan als u de oorspronkelijke status wilt behouden.

Limiet per batch

Het veld Maximaal aantal bestellingen per batch begrenst de omvang van een export. Bij winkels met veel volume voorkomt een waarde tussen 100 en 300 te zware bestanden en te lange uitvoeringstijden.

Export-cron

De cron-URL, beveiligd met een uniek token, staat bovenaan de configuratiepagina. Voeg ze toe aan uw crontab:

*/15 * * * * curl -s "https://uw-winkel.nl/module/dforderdispatch/cron?token=UW_TOKEN" > /dev/null

De cron geeft een JSON-object terug met de gegenereerde batch, het aantal geëxporteerde bestellingen, de bestandsnaam en de transportmelding, zodat u hem kunt bewaken vanuit een monitoringtool.

Auto-push-modus

Activeer Automatisch verzenden bij statuswijziging om elke bestelling afzonderlijk door te sturen zodra ze in een exporteerbare status komt, zonder te wachten op de volgende cronrun. Deze modus steunt op de transporten FTP, SFTP of API. Met het transport Download heeft hij geen effect.

Naam van de gegenereerde bestanden

Het veld Bestandsnaampatroon aanvaardt twee variabelen:

• {date}: tijdstempel in het formaat JJJJMMDD-UUMMSS.
• {batch}: unieke batch-ID, die ook in het logboek terugkomt.

De extensie wordt automatisch toegevoegd volgens het formaat: .csv, .txt voor EDI en .json. Niet-alfanumerieke tekens worden uit de definitieve naam verwijderd.

Herimport van trackingnummers

Drie kanalen zijn beschikbaar en kunnen gelijktijdig worden gebruikt. In alle gevallen wordt het ontvangen nummer weggeschreven op de vervoerder van de bestelling en in het trackingveld van de bestelling, waarna de status ingesteld in Status na trackingimport wordt toegepast (meestal Verzonden).

Kanaal 1: handmatige CSV-upload

Selecteer via het paneel Trackingimport op de configuratiepagina een CSV-bestand en start de import. De mapping stelt u in bij de instellingen:

• Scheidingsteken: puntkomma of komma.
• Kolomindex van de referentie: 0 komt overeen met de eerste kolom.
• Kolomindex van de tracking: idem.
• Kopregel: activeren als de eerste regel de kolomnamen bevat.

Voorbeeld van het verwachte bestand met de standaardmapping:

reference;tracking
XKBKNABJK;3SABCD1234567
1024;3SWXYZ7654321

De referentiekolom aanvaardt zowel de PrestaShop-bestelreferentie als de numerieke ID van de bestelling.

Kanaal 2: automatisch ophalen (cron pull)

Twee bronnen kunnen worden ingevuld en worden bij elke uitvoering na elkaar verwerkt:

• FTP-map met trackings: de module somt de .csv- en .txt-bestanden in de map op, importeert ze en kan ze daarna verwijderen als de betreffende optie is geactiveerd. De FTP-gegevens zijn die van de transportsectie.
• Ophaal-URL: een HTTP- of HTTPS-adres dat rechtstreeks een CSV met trackings teruggeeft.

Voeg de pull-URL toe aan uw crontab, bijvoorbeeld elk uur:

0 * * * * curl -s "https://uw-winkel.nl/module/dforderdispatch/tracking?token=UW_TOKEN&mode=pull" > /dev/null

Kanaal 3: webhook aangeleverd door de logistiek dienstverlener

Geef uw dienstverlener de push-URL door die in de configuratie wordt getoond. Hij hoeft alleen een POST-verzoek te sturen met een JSON-body:

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

[
  {"reference": "XKBKNABJK", "tracking": "3SABCD1234567"},
  {"reference": "1024", "tracking": "3SWXYZ7654321"}
]

Een omhullend object van de vorm {"items": [ ... ]} wordt eveneens aanvaard. Het antwoord is een JSON-rapport met het aantal bijgewerkte, genegeerde en foutieve bestellingen, met detail per regel.

Logboek en monitoring

Onderaan de configuratiepagina staan de laatste vijftig operaties, zowel exports als imports, telkens met datum, betrokken bestelling, batch-ID, richting, formaat, transport, status en de teruggegeven melding.

De deduplicatie steunt op dit logboek: een bestelling met een exportregel in de status “sent” wordt nooit meer opgenomen in een volgende batch. Om een herexport te forceren verwijdert u de betreffende regel in de logtabel van de module.

Probleemoplossing

De export vindt geen enkele bestelling

Controleer of er wel statussen zijn geselecteerd in de instellingen en of er zich daadwerkelijk bestellingen in bevinden. Ga vervolgens na of die bestellingen niet al met succes zijn geëxporteerd in een eerdere batch.

De cron geeft een tokenfout terug

Het token uit de configuratie moet letterlijk in de URL worden overgenomen, zonder spatie of extra teken. Kopieer het rechtstreeks vanaf de configuratiepagina.

De FTP-overdracht mislukt

Controleer host, poort en inloggegevens, en ga na of de externe map bestaat en schrijfbaar is. Als uw hoster uitgaande verbindingen blokkeert, kan de passieve modus of het openen van een poort nodig zijn.

SFTP is niet beschikbaar

De melding dat de extensie ssh2 niet beschikbaar is, betekent dat ze niet op de server is geïnstalleerd. Vraag uw hoster om activering, of schakel over op gewone FTP of de HTTP-API.

Een trackingnummer wordt geweigerd

Trackingnummers worden gevalideerd volgens de PrestaShop-regels. Een nummer met niet-toegestane tekens wordt geweigerd en als fout gelogd, zonder de rest van de import te blokkeren.

Veelgestelde vragen

Kan ik naar meerdere dienstverleners exporteren?

De module beheert één geconfigureerde uitgaande stroom tegelijk. Om twee verschillende dienstverleners te voeden, is de eenvoudigste aanpak de bestellingen te onderscheiden met verschillende statussen en elke stroom apart te verwerken.

Worden multistore-bestellingen ondersteund?

Ja, de module werkt in een multistore-context. De configuratie-instellingen volgen de PrestaShop-context waarin ze zijn opgeslagen.

Wat gebeurt er als de dienstverlener onbereikbaar is?

De mislukking wordt gelogd met de foutmelding en de betrokken bestellingen worden niet als verzonden gemarkeerd. Ze worden dus automatisch opnieuw meegenomen bij de volgende cronrun, zonder tussenkomst van uw kant.

Verstuurt de statuswijziging klant-e-mails?

Ja. De module gebruikt het standaardmechanisme voor statuswijzigingen van PrestaShop. De meldingen die aan de doelstatus zijn gekoppeld, met name de verzend-e-mail met het trackingnummer, worden dus gewoon verstuurd.