Przykłady

Sześć powtarzających się wzorców integracji. Każdy wskazuje metodę, z której korzysta, kolejność wywołań i najczęstszy błąd.

1. Moduł przewoźnika

Kontekst. Firma kurierska z API. Integracja potrzebuje ich etykiet, ich limitów i ich zamknięcia dnia, przy czym Stockly nie zawiera żadnego kodu specyficznego dla dostawcy.

Metoda integracji. Punkty rozszerzeń, w procesie.

Kroki wdrożenia.

Zaimplementuj CarrierProfileInterface i otaguj usługę. Przewoźnik pojawia się wtedy w wyborze przewoźnika na każdej regule pakowania, z własnymi limitami i własnymi walidacjami.
Nasłuchuj p2lab.stockly.parcels.commit albo pozwól regule sklepu wyzwolić zamówienie przesyłki i wołaj swojego dostawcę raz na paczkę.
Zgłoś każdy numer przesyłki przez p2lab.stockly.parcel.tracking. Stockly zapisze go w dostawie zamówienia, a stamtąd czyta go mail potwierdzający wysyłkę.
Jeśli dostawca ma zamknięcie dnia, zaimplementuj CarrierManifestGatewayInterface i zadeklaruj maxParcelsPerCall(). Stockly sam podzieli przekazanie na porcje tej wielkości.

Typowy błąd. Podwójne zamówienie przesyłki. Paczka, która już niesie numer, nie może zostać zamówiona ponownie: przesyłka istnieje, a sklep za nią zapłacił. Stockly pilnuje tego metodą isRequestable(), którą trzeba odczytać przed wywołaniem; pętla ponawiająca, która ją ignoruje, produkuje dwie etykiety na jedną przesyłkę.

Drugi typowy błąd. Deklarowanie limitów, których nie ma w umowie. Limity bywają umowne równie często co techniczne: ten sam przewoźnik to 31,5 kg dla jednego sklepu i 20 kg dla drugiego, którego załoga nie może dźwigać więcej. Podaj domyślne wartości przewoźnika i pozwól regule sklepu je nadpisać.

2. Desktopowe narzędzie do etykiet

Kontekst. Sklep ma już mały program, który rozmawia z przewoźnikiem i steruje drukarką etykiet. Program zachowuje swoją rolę, a Stockly otrzymuje informację o wyniku.

Metoda integracji. HTTP, odpytywanie.

Kroki wdrożenia.

Odpytuj /api/search/p2lab-stockly-parcel o paczki bez numeru przesyłki:

{ "filter": [
    { "type": "equals", "field": "trackingCode", "value": null },
    { "type": "equalsAny", "field": "status", "value": ["planned", "packed"] }
  ],
  "associations": { "order": {}, "lines": {} } }

Zamów etykietę w programie zewnętrznym.
Zgłoś ją: POST shipping/parcels/{parcelId}/tracking.
Na koniec dnia czytaj GET shipping/batches/eligible i wołaj POST shipping/batches/close. To wywołanie zwraca jobId, a nie wynik: działa w tle, a PDF do podpisu przez kierowcę jest pod shipping/batches/{batchId}/list.

Typowy błąd. Traktowanie batches/close jak wywołania synchronicznego. Przekazanie całego dnia to tysiące zapisów i API przewoźnika przyjmujące po trzydzieści przesyłek; endpoint od razu oddaje id zadania, a narzędzie musi odpytać o wynik.

Uwaga eksploatacyjna. Filtruj też po stanowisku, jeśli sklep ma więcej niż jedno stanowisko pakowania; inaczej zamknięcie dnia podpisuje odbiór paczek stojących jeszcze na innym stanowisku. Pole nazywa się floorElementId na paczce, a shipping/batches/close przyjmuje je jako zakres.

3. ERP trzymający wagi

Kontekst. Dane podstawowe artykułów żyją w ERP i są lepsze niż to, co jest w Shopware.

Metoda integracji. DAL, cyklicznie.

Kroki wdrożenia.

Wypychaj wagi i wymiary do samego produktu Shopware: weight, length, width, height. Stockly czyta natywne pola; nie trzyma drugiej kopii.
Wypychaj narzut opakowania do p2lab_stockly_product_packaging, kluczując po productId.
Jeśli ERP pracuje klasami pakowania, a nie artykułami, utwórz po jednym p2lab_stockly_packaging_profile na klasę i pozwól pracować dopasowaniu po właściwości: trzysta artykułów objętych jednym wierszem, którego nigdy więcej nie trzeba synchronizować.
Po synchronizacji czytaj GET packaging/coverage i loguj summary.missingDimensions. To najtańszy możliwy test regresji na samym eksporcie.

Typowy błąd. Wysyłanie zer. ERP eksportujący „0.000” dla nieznanej wagi opakowania stwierdza, że artykuł jedzie bez opakowania, i żadna reguła niżej tego nie poprawi. Pomiń pole albo wyślij null.

Drugi typowy błąd. Warianty. Wariant dziedziczący wagę po rodzicu zapisuje NULL, a importer, który poprawia to, kopiując wartość rodzica na każdy wariant, zamienia jeden wiersz danych podstawowych w tysiąc wierszy, których nikt nie będzie utrzymywał.

4. 3PL robiący własną kartonizację

Kontekst. Magazyn należy do operatora logistycznego, który decyduje o pudłach i zgłasza je po fakcie.

Metoda integracji. HTTP, wypychanie.

Kroki wdrożenia.

Nie wołaj parcels/plan; ta ścieżka raportuje wynik, a nie pyta o niego.

POST shipping/parcels/commit z paczkami takimi, jakie naprawdę były:

{ "orderId": "0191…",
  "source": "acme-3pl",
  "parcels": [
    { "sequence": 1,
      "weightKg": 6.42,
      "packagingMaterialId": "0191f2…",
      "volumetricWeightKg": 4.10,
      "note": "karton zewnętrzny wgnieciony, przeklejony",
      "lines": [{ "lineItemId": "0191…", "quantity": 2 }] }
  ] }

Numery przesyłek zgłaszaj jak w przypadku 2.

Typowy błąd. Ponowne wysłanie planu, gdy etykiety już istnieją. commit zastępuje podział, ale paczki niosące numer przesyłki są zamrożone i zostają dokładnie takie, jakie są, więc ponowne wysłanie nie zepsuje zamówionych przesyłek, ale też ich nie zaktualizuje. Jeśli 3PL przepakował zamówioną paczkę, anuluj ją i wyślij nową.

Zalecana praktyka. Wysyłaj packagingMaterialId, nawet jeśli katalog powstał tylko na tę potrzebę. To on pozwala później zapytać, czy 3PL używa sensownych rozmiarów pudeł, a jest to pytanie mające bezpośredni wpływ na koszt wysyłki.

5. Monitoring i BI

Kontekst. Ktoś chce wiedzieć, czy dane o pakowaniu się psują, bez otwierania admina.

Metoda integracji. HTTP, tylko odczyt.

Co odczytywać i co to znaczy.

Wywołanie	Alarmuj, gdy
`GET packaging/coverage`	`summary.hasGlobalProfile` jest false — cała funkcja jest bezwładna
`GET packaging/coverage`	`ready / total` spada tydzień do tygodnia — wchodzą niezmierzone nowości
`GET packaging/collisions`	lista jest niepusta — dwie reguły remisują i nikt nie wybrał
`GET packaging/variance`	`avgVarianceKg` powyżej progu — dane artykułu są błędne

Typowy błąd. Alarmowanie na rozmiarze gaps. Wylicza ona wszystko, co niezmierzone, i w sklepie z długim ogonem pozostaje długa na stałe. Liczy się jej góra: artykuły z wysokim shipments i hasDimensions: false.

6. Kiosk stanowiska

Kontekst. Ekran przy stanowisku, obsługiwany skanerem, we froncie własnym integratora.

Metoda integracji. HTTP.

Kroki wdrożenia.

Rozwiąż zeskanowany kod: GET /api/_action/p2lab-stockly/packing/scan/resolve?code=…. Próbuje przedrostka kodu zamówienia, potem numerów zamówień, potem numerów dokumentów, i nigdy nie zgaduje: kod niejednoznaczny wraca jako ambiguous z kandydatami.
Poproś o podział: POST shipping/parcels/plan.
Pokaż go, pozwól pakującemu zmienić, a potem POST shipping/parcels/commit z floorElementId ustawionym na stanowisko. Ten stempel to jedyny moment, w którym ktokolwiek wie, które z trzech stanowisk obsłużyło zamówienie.
POST shipping/parcels/packed, gdy przebieg się kończy, żeby wyzwoliła się reguła zamawiania przesyłek.

Typowy błąd. Zgubienie stanowiska. floorElementId jest stemplowane raz i nigdy nie nadpisywane nullem, właśnie po to, żeby późniejszy zapis z ekranu, który nie zna stanowiska, go nie skasował; jeśli jednak kiosk w ogóle go nie wysyła, raporty stanowisk zostają puste, a pominięcie ujawnia się dopiero przy ich odczycie.

Uwaga eksploatacyjna. Zamówienia zablokowane wracają ze skanera z powodem (anulowane, nieopłacone), a nie jako „nie znaleziono”. Pokaż ten powód, żeby nie odsyłać pakującego do skanera po odpowiedź, która się nie zmieni.

Lista kontrolna dla każdej integracji

Przeczytaj cztery metody integracji przed wyborem; większość kłopotliwych integracji wybrała najpierw niewłaściwą.
Nigdy nie zapisuj 0 w miejsce wartości „nieznane”.
Pokazuj *Source: "none" użytkownikom samej integracji. Tak znajduje się złe dane.
Traktuj batches/close jak zadanie, a nie wywołanie.
Jeśli sklep ma więcej niż jedno stanowisko pakowania, przekazuj floorElementId wszędzie, gdzie to możliwe.