Order Dispatch: eksport zamówień do operatora logistycznego / 3PL

Wymagania i zgodność

Moduł Order Dispatch działa na PrestaShop 8.0 do 9.x, przy PHP minimum 7.2 (testowany do PHP 8.3), w trybie jednosklepowym i wielosklepowym.

• Rozszerzenie PHP ftp jest wymagane dla transportu FTP oraz pobierania plików z numerami przesyłek przez FTP.
• Rozszerzenie PHP ssh2 jest wymagane wyłącznie przy trybie SFTP. Bez niego użyj zwykłego FTP albo API HTTP.
• Rozszerzenie curl jest wymagane dla transportu API HTTP oraz pobierania numerów przesyłek z adresu URL.
• Dostęp do crontab na serwerze (lub zewnętrzna usługa cron) jest zalecany do automatyzacji eksportów.

Instalacja

1. W panelu administracyjnym otwórz Moduły > Menedżer modułów.
2. Kliknij Zainstaluj moduł i wskaż archiwum dforderdispatch-1.0.0.zip.
3. Po zakończeniu instalacji kliknij Konfiguruj.

Podczas instalacji moduł tworzy własną tabelę dziennika, rejestruje hook actionOrderStatusPostUpdate i generuje unikalny token bezpieczeństwa dla adresów cron.

Wybór formatu eksportu

Wybór formatu zależy od tego, co potrafi odczytać Twój operator logistyczny lub system WMS. W polu Format eksportu dostępne są trzy formaty.

CSV

Jeden wiersz na pozycję zamówienia, z nagłówkiem zamówienia powtórzonym w każdym wierszu. To najczęściej spotykany format u firm kompletujących przesyłki. Separator wybierasz między średnikiem a przecinkiem.

Generowane kolumny, w kolejności:

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

Płaski plik EDI

Format z rekordami rozdzielonymi pionowymi kreskami i zakończeniami wierszy CRLF. Każde zamówienie tworzy rekord nagłówka H, po którym następuje jeden rekord L na pozycję zamówienia.

H|referencja|data|przewoznik|nazwisko|imie|adres1|adres2|kod|miasto|kraj|telefon|email|waga
L|referencja|sku|ean13|ilosc|nazwa

Konkretny przykład:

H|XKBKNABJK|2026-07-05 10:00:00|InPost|Kowalski|Jan|ul. Dluga 12||31-147|Krakow|PL|600100200|jan@przyklad.pl|1.2
L|XKBKNABJK|SKU-114|1234567890123|2|Skorzane sneakersy premium

API JSON

Ustrukturyzowany ładunek dopasowany do operatorów udostępniających nowoczesne API. Cała partia jest wysyłana w jednym obiekcie zawierającym datę wygenerowania i tablicę zamówień, każde z nagłówkiem, danymi klienta, adresem dostawy i pozycjami.

Wybór transportu

Pole Transport określa, w jaki sposób wygenerowany plik trafia do Twojego dostawcy usług.

Pobranie

Brak automatycznej wysyłki. Przycisk Eksportuj teraz generuje plik i pobiera go bezpośrednio w przeglądarce. Przydatne do przetestowania formatu albo dla dostawcy, który odbiera pliki ręcznie.

FTP

Podaj host, port (domyślnie 21), login, hasło i zdalny katalog zamówień. Tryb pasywny jest włączony domyślnie i odpowiada większości hostingów.

SFTP

Włącz opcję Używaj SFTP i wpisz w polu portu numer portu SSH (zwykle 22). Dane logowania FTP służą również do SFTP. Ta opcja wymaga rozszerzenia PHP ssh2 na serwerze.

API HTTP

Cała partia jest wysyłana metodą POST na adres URL Twojego dostawcy, a treść żądania zawiera bezpośrednio wygenerowany plik. Wysyłce towarzyszą dwa nagłówki:

• X-DFOD-KEY: klucz API wpisany w konfiguracji.
• X-DFOD-FILENAME: nazwa pliku wyliczona według Twojego wzorca.

Typ treści jest dopasowany do wybranego formatu (JSON, CSV albo zwykły tekst). Każda odpowiedź HTTP spoza zakresu 2xx jest traktowana jako niepowodzenie i zapisywana w dzienniku.

Wybór zamówień i harmonogram

Statusy zamówień źródłowych

W polu Statusy zamówień do eksportu wybierz jeden lub kilka statusów (zwykle Płatność zaakceptowana i W trakcie przygotowania). Brane są pod uwagę wyłącznie zamówienia w jednym z tych statusów, które nie zostały jeszcze pomyślnie wyeksportowane.

Zmiana statusu po eksporcie

Pole Status po eksporcie pozwala automatycznie przełączyć wyeksportowane zamówienia na dedykowany status kontrolny. Zostaw wartość „Bez zmiany”, jeśli wolisz zachować status pierwotny.

Limit partii

Pole Maksymalna liczba zamówień w partii ogranicza rozmiar eksportu. W sklepach o dużym wolumenie wartość między 100 a 300 pozwala uniknąć zbyt ciężkich plików i nadmiernych czasów wykonania.

Cron eksportu

Adres URL crona, zabezpieczony unikalnym tokenem, jest wyświetlany u góry strony konfiguracji. Dodaj go do swojego crontab:

*/15 * * * * curl -s "https://twoj-sklep.pl/module/dforderdispatch/cron?token=TWOJ_TOKEN" > /dev/null

Cron zwraca obiekt JSON wskazujący wygenerowaną partię, liczbę wyeksportowanych zamówień, nazwę pliku i komunikat transportu, co pozwala monitorować go z poziomu narzędzia nadzoru.

Tryb auto-push

Włącz Automatyczna wysyłka przy zmianie statusu, aby przekazywać każde zamówienie pojedynczo, gdy tylko wejdzie w status kwalifikujący do eksportu, bez czekania na kolejny przebieg crona. Ten tryb korzysta z transportu FTP, SFTP lub API. Przy transporcie Pobranie pozostaje bez efektu.

Nazwy generowanych plików

Pole Wzorzec nazwy pliku przyjmuje dwie zmienne:

• {date}: znacznik czasu w formacie RRRRMMDD-GGMMSS.
• {batch}: unikalny identyfikator partii, powtórzony również w dzienniku.

Rozszerzenie jest dodawane automatycznie zależnie od formatu: .csv, .txt dla EDI oraz .json. Znaki inne niż alfanumeryczne są usuwane z ostatecznej nazwy.

Ponowny import numerów przesyłek

Dostępne są trzy kanały, których można używać jednocześnie. W każdym przypadku otrzymany numer jest zapisywany na przewoźniku zamówienia oraz w polu śledzenia zamówienia, a następnie stosowany jest status ustawiony w polu Status po imporcie numeru przesyłki (zwykle Wysłane).

Kanał 1: ręczne wgranie CSV

W panelu Import numerów przesyłek na stronie konfiguracji wybierz plik CSV i uruchom import. Mapowanie konfiguruje się w ustawieniach:

• Separator: średnik albo przecinek.
• Indeks kolumny referencji: 0 odpowiada pierwszej kolumnie.
• Indeks kolumny numeru przesyłki: tak samo.
• Wiersz nagłówka: włącz, jeśli pierwszy wiersz zawiera nazwy kolumn.

Przykład oczekiwanego pliku przy domyślnym mapowaniu:

reference;tracking
XKBKNABJK;620012345678901234
1024;620098765432109876

Kolumna referencji przyjmuje zarówno referencję zamówienia PrestaShop, jak i numeryczny identyfikator zamówienia.

Kanał 2: automatyczne pobieranie (cron pull)

Można wskazać dwa źródła, przetwarzane jedno po drugim przy każdym uruchomieniu:

• Katalog FTP z numerami przesyłek: moduł listuje pliki .csv i .txt w katalogu, importuje je i może je następnie usunąć, jeśli odpowiednia opcja jest włączona. Dane logowania FTP są te same co w sekcji transportu.
• Adres URL do pobrania: adres HTTP lub HTTPS zwracający bezpośrednio plik CSV z numerami przesyłek.

Dodaj adres pull do swojego crontab, na przykład co godzinę:

0 * * * * curl -s "https://twoj-sklep.pl/module/dforderdispatch/tracking?token=TWOJ_TOKEN&mode=pull" > /dev/null

Kanał 3: webhook wysyłany przez operatora

Przekaż swojemu dostawcy adres URL push wyświetlony w konfiguracji. Wystarczy, że wyśle żądanie POST z treścią JSON:

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

[
  {"reference": "XKBKNABJK", "tracking": "620012345678901234"},
  {"reference": "1024", "tracking": "620098765432109876"}
]

Akceptowany jest również obiekt opakowujący w postaci {"items": [ ... ]}. Odpowiedzią jest raport JSON opisujący liczbę zamówień zaktualizowanych, pominiętych i błędnych, ze szczegółami wiersz po wierszu.

Dziennik i nadzór

Dół strony konfiguracji pokazuje pięćdziesiąt ostatnich operacji, zarówno eksportów, jak i importów, a przy każdej datę, powiązane zamówienie, identyfikator partii, kierunek, format, transport, status i zwrócony komunikat.

Deduplikacja opiera się na tym dzienniku: zamówienie z wpisem eksportu o statusie „sent” nigdy nie trafi ponownie do kolejnej partii. Aby wymusić ponowny eksport, usuń odpowiadający wiersz z tabeli dziennika modułu.

Rozwiązywanie problemów

Eksport nie zwraca żadnego zamówienia

Sprawdź, czy w ustawieniach faktycznie wybrano statusy i czy znajdują się w nich jakieś zamówienia. Następnie sprawdź, czy te zamówienia nie zostały już pomyślnie wyeksportowane w poprzedniej partii.

Cron zwraca błąd tokenu

Token wyświetlony w konfiguracji musi zostać przeniesiony do adresu URL bez zmian, bez spacji ani dodatkowych znaków. Skopiuj go bezpośrednio ze strony konfiguracji.

Transfer FTP kończy się niepowodzeniem

Sprawdź host, port i dane logowania, a następnie upewnij się, że zdalny katalog istnieje i ma prawo zapisu. Jeśli hostingodawca blokuje połączenia wychodzące, konieczny może być tryb pasywny lub otwarcie ruchu.

SFTP jest niedostępny

Komunikat o braku rozszerzenia ssh2 oznacza, że nie jest ono zainstalowane na serwerze. Poproś hostingodawcę o jego włączenie albo przełącz się na zwykły FTP lub API HTTP.

Numer przesyłki zostaje odrzucony

Numery przesyłek są walidowane według reguł PrestaShop. Numer zawierający niedozwolone znaki jest odrzucany i zapisywany w dzienniku jako błąd, bez blokowania reszty importu.

Najczęstsze pytania

Czy mogę eksportować do kilku dostawców?

Moduł obsługuje jeden skonfigurowany strumień wychodzący naraz. Aby zasilać dwóch różnych dostawców, najprościej rozdzielić zamówienia różnymi statusami i obsługiwać każdy strumień osobno.

Czy zamówienia w trybie wielosklepowym są obsługiwane?

Tak, moduł działa w kontekście wielosklepowym. Ustawienia konfiguracji podążają za kontekstem PrestaShop, w którym zostały zapisane.

Co się dzieje, gdy dostawca jest nieosiągalny?

Niepowodzenie trafia do dziennika wraz z komunikatem błędu, a powiązane zamówienia nie są oznaczane jako wysłane. Zostaną więc automatycznie przetworzone przy kolejnym przebiegu crona, bez Twojej interwencji.

Czy zmiana statusu uruchamia e-maile do klientów?

Tak. Moduł korzysta ze standardowego mechanizmu zmiany statusu PrestaShop. Powiadomienia powiązane ze statusem docelowym, w szczególności e-mail o wysyłce z numerem przesyłki, są więc wysyłane normalnie.