PrestaShop Waybill ↔ Orbito

Integracja z API waybillupload 1.5.0 pobiera PDF, numer przesyłki i kuriera. Dane trafiają do rejestru przesyłek przez kontrakty hooków Orbito.

Od wersji 1.3.0 przekazuje również numer nowej faktury z Orbito do zakładki Dokumenty zamówienia w PrestaShop. Ta część wymaga sklepowego waybillupload 1.8.0 (źródła w ../prestashop-waybill-shop/waybillupload) oraz wskazania sourceInstanceId w konfiguracji integracji. Działa dla wszystkich zamówień wybranego konta sklepu, także bez własnej etykiety i niezależnie od przewoźnika.

Numery faktur w sklepie

Hook event:core.invoicing.invoice.issued zapisuje trwałe zadanie wysyłki. Worker pobiera fakturę kontraktem invoicing.invoices.getById dokładnie z instancji rejestru, która nadała zdarzenie, a zamówienie przez orders.getById z wybranego rejestru zamówień. Sprawdza powiązanie faktury z zamówieniem oraz źródło i instancję sklepu. Proformy, paragony, korekty i nieznane typy dokumentów są pomijane.

Do waybillupload trafiają numer faktury, jej identyfikatory, referencja zamówienia, dostępna kwota/waluta i data z rejestru Orbito. Sklep przechowuje je jako zewnętrzny dokument i wyświetla w istniejącej tabeli Dokumenty z licznikiem. Integracja nie wystawia kolejnej faktury i nie przesyła PDF-u; data oznacza datę zapisu w rejestrze Orbito.

Powtórzony event nie tworzy kolejnego wpisu. Lokalna kolejka obejmuje endpoint sklepu, instancję tej integracji, instancję rejestru faktur i ID dokumentu. Dokument w sklepie ma tożsamość opartą na ID sklepu, zweryfikowanej instancji źródła zamówień, instancji rejestru faktur i ID dokumentu, więc dwie integracje tego samego konta nie dodają go podwójnie. Przed POST integracja utrwala stan rozpoczętego zapisu. Jeśli odpowiedź zginie lub zapis ma niepewny wynik, ponowienie wykonuje wyłącznie GET get_invoice i sprawdza zapisany dokument; brak potwierdzenia wymaga weryfikacji, także po akcji Synchronizuj teraz. Nie powtarza POST-u automatycznie. Zadania przeżywają restart, a zmiana sklepu lub źródła nie przekierowuje starej kolejki.

W konfiguracji dostępny jest przełącznik Przekazuj numery faktur do sklepu (domyślnie włączony). Ta wersja obsługuje faktury pojawiające się po aktualizacji modułu oraz wcześniej zakolejkowane zadania; nie wykonuje masowego eksportu historycznych faktur.

Działanie

Co minutę i po zdarzeniu event:order:created odpytuje action=list po trwałym kursorze file.updated_at, z zapasem 5 minut i stronicowaniem po 200 rekordów. Pierwsza synchronizacja obejmuje całą historię, również pliki pobrane wcześniej przez API.
Filtruje po carrier.name, czyli przewoźniku wybranym w zamówieniu. To osobna wartość niż kurier odczytany z etykiety.
Wyszukuje jedno zamówienie po źródle, ID instancji źródła, sourceId i uniqueId.
Zapisuje shipment.tracking_number jako trackNo, shipment.courier jako nazwę przewoźnika oraz zachowuje courier_code i source (auto, manual, none). Nie podstawia referencji zamówienia za brakujący numer przesyłki.
Pobiera PDF z no_mark=1, sprawdza SHA-256 z rekordu i nagłówka oraz zapisuje etykietę. Limit pliku po stronie integracji wynosi 1 MB.
Brak numeru nie blokuje importu: przesyłka ma pusty trackNo, zachowany PDF i oznaczenie Do weryfikacji — brak numeru przesyłki. Późniejsza korekta ze sklepu aktualizuje ten sam wpis i usuwa oznaczenie.
Niezmieniony PDF nie jest pobierany ponownie. Korekta numeru, kuriera lub źródła numeru jest przetwarzana również wtedy, gdy SHA-256 pozostało takie samo.
Kursor przesuwa się dopiero po przetworzeniu wszystkich stron bez błędów i odłożonych rekordów. Brak zamówienia w Orbito pozostawia etykietę do późniejszego importu.

Przesyłka pozostaje ręczna ze statusem untracked: samo rozpoznanie nazwy kuriera nie przypisuje jej do konta modułu przewoźnika ani nie uruchamia śledzenia statusów.

Integracja pobiera publiczny link śledzenia przez hook shipping.carrier.getTrackingUrl, przekazując shipment.courier (lub courier_code, gdy brakuje nazwy) i numer przesyłki. Nie zawiera adresów ani list nazw przewoźników. Rozpoznawanie nazw i budowanie URL należy do dostawcy hooka. Odczyt jest kierowany do każdej odkrytej instancji: null oznacza brak dopasowania; zgodne linki z wielu kont są akceptowane bez przypisywania przesyłki do konta. Różne adresy lub błąd dostawcy pozostawiają numer bez linku, zapisują komunikat w logach i zatrzymują kursor do kolejnej synchronizacji. Import PDF nadal działa. Nieznany przewoźnik lub pusty numer nie otrzymuje zgadywanego adresu.

Wersja 1.2.1 ponownie przechodzi po historii, aby uzupełnić linki także w starszych wpisach, bez ponownego pobierania zapisanych PDF-ów. Korekta numeru lub kuriera aktualizuje link. Rejestr przesyłek musi obsługiwać trackingUrl w shipping.shipments.updateManual (wersja 2.12.1), a moduły przewoźników — nowy hook (DHL 1.3.1, DPD 2.6.1, InPost 2.4.1).

Integracja korzysta z własnego stanu, a nie z only_new i download_count. Wszystkie pobrania używają no_mark=1; nie zwiększają licznika pobrań w sklepie. Dzięki temu odczyty i ponowienia nie wykonują dodatkowego efektu po stronie sklepu.

Konfiguracja

W Ustawienia → Moduły → Konfiguruj ustaw:

adres HTTPS sklepu lub pełny endpoint waybillupload;
klucz API jako sekret; wysyłany wyłącznie w nagłówku X-Api-Key;
nazwę przewoźnika z zamówienia, domyślnie Etykieta własna;
zastępczą nazwę kuriera, stosowaną tylko gdy API nie poda jego nazwy ani kodu;
kod źródła zamówień lub jego ID instancji; przy kilku kontach wskaż konkretną instancję;
do wysyłki faktur zawsze wskaż ID instancji źródła tego sklepu;
opcjonalny id_shop dla multistore;
strefę czasową sklepu uzgodnioną z administratorem PrestaShop (domyślnie Europe/Warsaw);
ID instancji rejestru zamówień i rejestru przesyłek, jeśli dany kontrakt udostępnia kilka instancji.

Daty kursora pozostają w lokalnym formacie sklepu YYYY-MM-DD HH:MM:SS. Nie są zamieniane na czas serwera Orbito ani UTC. Strefa czasowa opisuje konfigurację sklepu; jej zmiana uruchamia ponowne przejście po historii.

Domena sklepu musi być dozwolona dla platformowego Core.fetch. Dostępne są akcje Testuj połączenie i Synchronizuj teraz. Ręczna synchronizacja pozwala ponowić odczyty zablokowane po błędzie lub wyczerpaniu prób. Nie powtarza zapisu o niepewnym wyniku.

Trwałość, błędy i aktualizacja

Tożsamość etykiety obejmuje instancję importera, endpoint sklepu, id_shop i ID zamówienia. Stan przechowuje również ID instancji obu rejestrów, ID przesyłki, sumę pliku, metadane i nierozstrzygniętą operację. Zmiana wybranego rejestru nie przenosi istniejących wpisów automatycznie.

Błędy API zachowują error.code i status HTTP w logu. Nieprawidłowy JSON przy HTTP 2xx otrzymuje kod WAYBILL_INVALID_RESPONSE i jest traktowany jako przejściowy błąd odczytu. Pobieranie listy po takim błędzie, 5xx lub awarii sieci jest ponawiane po 1, 5 i 15 minutach, a następnie co godzinę, również po restarcie. Pojedynczy błąd odpowiedzi nie wyłącza całego importera. Historyczna blokada kursora HTTP_200 jest zdejmowana jednorazowo, bez zmiany pozycji kursora ani stanu zapisów przesyłek. Błędy 400/401/403/404/405/410 oraz jawne odmowy API nadal wymagają poprawy przyczyny i ręcznego ponowienia. Odczyty PDF po 5xx, awarii sieci lub chwilowej niezgodności sumy pliku mają najwyżej trzy ponowienia po 1, 5 i 15 minutach.

Jeśli pracownik dodał w międzyczasie ręczną przesyłkę bez tożsamości importu, zgodny niepusty numer przesyłki lub identyczna suma PDF w tym samym zamówieniu i rejestrze zatrzymuje utworzenie duplikatu (MANUAL_SHIPMENT_CONFLICT). Integracja nie przejmuje ani nie zmienia wpisu pracownika; powiązanie wymaga weryfikacji. Dotyczy to również ręcznego ponowienia synchronizacji.

Przed zapisem przesyłki utrwalana jest informacja o rozpoczętej operacji. Po utracie odpowiedzi integracja wyłącznie odczytuje rejestr i sprawdza tożsamość, metadane i PDF. Jeśli nie może potwierdzić zapisu, zatrzymuje ten rekord do weryfikacji — nie tworzy automatycznie drugiej przesyłki.

Starsza kolekcja prestashop_waybill_syncs pozostaje zachowana. Rekordy są przenoszone do stanu v2 dopiero po potwierdzeniu zamówienia, ID istniejącej przesyłki i sumy zapisanego PDF-u. Niejednoznacznych danych integracja nie przypisuje do konta.

Przed uruchomieniem tej wersji dostawca rejestru przesyłek musi udostępniać shipping.shipments.updateManual oraz rozszerzony shipping.shipments.createManual. Implementację dodano w lokalnym module rejestru przesyłek. Brak dostawcy lub kilka instancji bez jawnego wyboru daje błąd bez zapisu.

Kontrakty

orders.searchIds — wyszukanie zamówienia;
orders.getById — weryfikacja zamówienia przed wysyłką faktury;
invoicing.invoices.getById — odczyt faktury z rejestru wskazanego przez uwierzytelniony kontekst zdarzenia;
shipping.shipments.search — odczyt przesyłek;
shipping.shipments.getLabel — weryfikacja istniejącego pliku;
shipping.shipments.createManual — utworzenie wpisu wraz z PDF-em i danymi przesyłki;
shipping.shipments.updateManual — korekta numeru/kuriera i opcjonalna podmiana PDF-u bez nowego nadania.

Nie ma zależności dependsOn ani bezpośrednich wywołań innych modułów. Dostawca jest wybierany przez kontrakt i ID instancji; kod marki kuriera służy tylko jako dane.

Weryfikacja

npm test

Z katalogu workspace należy uruchomić również testy shipments-module oraz:

node --test --test-concurrency=1 --test-force-exit module-contracts/*.test.js

PrestaShop — etykiety ze sklepu