# Order Dispatch: eksport zamówień do operatora logistycznego / 3PL
> Kompletny przewodnik po module Order Dispatch: instalacja, formaty eksportu CSV / EDI / JSON, transport FTP, SFTP i API, harmonogram cron oraz ponowny import numerów przesyłek.
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-31
- Inne języki: [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), [pt](https://www.datafirefly.com/pt/documentation/dforderdispatch/index.md), [nl](https://www.datafirefly.com/nl/documentation/dforderdispatch/index.md)
- Indeks:
## 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.
Deinstalacja usuwa tabelę dziennika oraz wszystkie klucze konfiguracyjne modułu. Zapisane wcześniej zamówienia i numery przesyłek pozostają nienaruszone.
## 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
```
Każda pionowa kreska obecna w danych (nazwa produktu, adres) jest automatycznie zamieniana na spację, żeby nie rozbić struktury pliku. Znaki końca wiersza w polach są neutralizowane w ten sam sposób.
### 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.
Pole hasła pozostaje puste przy wyświetlaniu ze względów bezpieczeństwa. Zostaw je puste podczas zapisu, aby zachować dotychczasowe hasło.
### 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.
Oba tryby mogą działać równolegle: auto-push obsługuje zamówienia na bieżąco, a cron nadrabia te, które zakończyły się niepowodzeniem, przy czym deduplikacja wyklucza podwójną wysyłkę.
## 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.