core/erli 0.4.1

Integracja ERLI: rynek PL, PLN, własne umowy z przewoźnikami oraz nadania ERLI (InPost, DHL, DPD, Orlen Paczka, Pocztex). Moduł ma wiele instalacji. Każdy sklep i środowisko mają osobną instalację oraz niezmienne przypisanie sklepu. Synchronizacja i eksport są domyślnie wyłączone.

Pierwsze uruchomienie

Wgraj paczkę core-erli-0.4.1.zip w panelu developera Orbito jako wersję

core/erli. Po poprawnym buildzie opublikuj ją i dodaj instalację do firmy.

W panelu sprzedawcy ERLI wybierz „Metoda integracji → Własna integracja po API”

i pobierz klucz. W konfiguracji instalacji Orbito wpisz klucz oraz nazwę sklepu, zostaw adres https://erli.pl/svc/shop-api i kliknij „Sprawdź połączenie i pobierz słowniki”.

Wybierz instancje zamówień i rejestru przesyłek oraz osobne statusy: nowe,

weryfikacja, historia i fizyczna wysyłka. Ustaw datę startu i VAT dostawy.

Przypisz każde konto kurierskie Orbito do kodu przewoźnika ERLI. Włączaj

wyłącznie konta z własnymi umowami. Przesyłki ERLI działają jako osobny przewoźnik, bez mapowania na zewnętrzny numer listu.

Włącz synchronizację i w panelu Ustawienia → Zamówienia → ERLI kliknij „Synchronizuj teraz”.
Dla własnych umów włącz „Odsyłaj przesyłki i status po fizycznej wysyłce”.

W Orbito wystaw list i fakturę, spakuj zamówienie, a przy faktycznej wysyłce ustaw wybrany status wysyłki. Moduł odeśle numery listów i status do ERLI.

Faktura zostaje w Orbito: ta wersja nie wysyła PDF faktury do ERLI.

Od 0.5.11 pobieranie etykiety używa Accept: */* oraz identyfikatora User-Agent takiego jak pozostałe żądania API. Nie wymaga, aby serwer deklarował typ application/pdf podczas negocjacji; pobrany plik nadal musi być binarnym PDF z nagłówkiem %PDF- i mieścić się w limicie 20 MB. Dokumentacja ERLI zaleca ustawianie User-Agent i podaje przykłady API z Accept: application/json; kontrakt waybills zwraca link etykiety bez gwarancji typu MIME. Odpowiedź HTTP 406 z działającej instalacji wskazała na potrzebę usunięcia ograniczenia do samego application/pdf. Wynik naprawy wymaga sprawdzenia pobrania etykiety w działającej instalacji. Pobranie nie ponawia nadania ani wydruku.

Nadawanie ERLI / ErliPRO

Zachowaj sprawdzone połączenie i wskazane instancje zamówień oraz rejestru przesyłek.
W konfiguracji ERLI → „Przesyłki ERLI” ustaw opcjonalny punkt nadania. Pusty punkt oznacza domyślny punkt danej usługi ustawiony w ERLI.
W Przesyłkach → Warunki doboru przewoźnika wybierz konto Przesyłki ERLI, wpisz nazwę kafelka, wymiary w cm i zakres widoczności od/do kg. Dla A/B/C utwórz trzy warunki. Waga nadania pochodzi ze wszystkich produktów i zestawów zamówienia. Brak wag lub wymiarów blokuje szybkie nadanie; nie używamy wymiarów ani wagi zapasowej.
W Shipping → Warunki doboru przewoźnika dodaj warunek dla instancji „Przesyłki ERLI” oraz wybranych źródeł, krajów i nazw dostawy. Jeśli istnieją warunki, kafelki wyświetlają się tylko dla pasujących warunków. Dostawa ERLI wybiera swoje konto przez tożsamość źródła i nie nadaje na własnej umowie innego konta.
W zamówieniu kliknij kafelek właściwej usługi z logo ERLI. Nie otwiera dodatkowego formularza wymiarów: nadaje paczkę z zapisanymi wartościami i pobiera PDF z ERLI. Wariant w ramach tej samej grupy wybierany jest na podstawie limitów z aktualnego słownika ERLI. Nie zmieniamy grupy punkt/kurier ani pobrania. Puste albo przekraczające limity wymiary pokazują kafelek z instrukcją konfiguracji, bez przycisku nadania.
Jeśli etykieta lub numer nie są jeszcze gotowe, pobierz istniejącą paczkę. Po utracie odpowiedzi nadanie nie jest automatycznie ponawiane; do jawnego powiązania istniejącego ID pozostaje formularz dostępny przez „Dodaj paczkę”.

Odbiorca, adres, telefon, e-mail i kod punktu odbioru przy nowym nadaniu pochodzą z aktualnego zamówienia w Orbito i są przekazywane w shipping.receiver do ERLI. Nie porównujemy ich z danymi ERLI; korekta w Orbito trafia na nową etykietę. Ulicę zapisaną razem z numerem budynku i mieszkania rozdzielamy na pola API ERLI. Obsługujemy litery oddzielone spacją od numeru budynku (Ulica 82 B/3) oraz złożone numery lokali (Andersa 4/II/6: budynek 4, lokal II/6). Żaden segment adresu nie jest usuwany; jawne pola numeru budynku i lokalu mają pierwszeństwo, a zapis w zamówieniu pozostaje zachowany. Jeśli danych brakuje, uzupełnij je w Orbito. Istniejąca paczka zachowuje dane z chwili nadania; pobieranie etykiety nie tworzy jej ponownie. Jedna paczka na nadanie; zamówienie może mieć kilka osobnych etykiet. Usługi muszą być obecne w słowniku ERLI oraz dopuszczone przez CreateParcels. Starsze usługi ze słownika bez odpowiednika nadania API i usługi zagraniczne nie są automatycznie zastępowane inną usługą.

Kolejna etykieta (0.5.14)

W zamówieniu wybierz „Dodaj paczkę” i konto ERLI, a następnie „Wygeneruj nową etykietę”, albo użyj odświeżonego kafelka szybkiego nadania. Istniejąca paczka w ERLI nie blokuje nowego nadania. Każde nadanie tworzy osobną paczkę i zachowuje wcześniejsze etykiety oraz tracking. Aby tylko pobrać istniejącą etykietę, użyj listy przesyłek lub podaj ID paczki w formularzu.

Formularz i kafelki zachowują token bieżącej operacji: ponowienie tego samego żądania nie tworzy kolejnej paczki. Następna operacja staje się dostępna po potwierdzeniu zapisu poprzedniej przesyłki w wybranym rejestrze. Niepewny wynik nadania nadal wymaga sprawdzenia i jawnego powiązania paczki ERLI; odświeżenie formularza, zmiana kafelka ani inny tryb pakowania nie ponawiają nadania.

Od 0.5.15 jawne wygenerowanie etykiety działa również dla zamówienia z historią wysyłki, doręczenia lub zwrotu przesyłki w ERLI, np. po przywróceniu lokalnego statusu „Do nadania”. Formularz i kafelki udostępniają nową operację; sam odczyt historii ani stare wywołanie bez tokenu nie nadają ponownie paczki. Zamówienie anulowane lub oczekujące na płatność, zwrot samego zamówienia, kontrola finansowa, zmiana danych źródłowych i niepewny wynik nadania nadal blokują wysyłkę. Ponowne nadanie nie zmienia klasyfikacji importu historycznego ani zasad automatycznego eksportu do ERLI.

Repozytorium i wydania

Kod źródłowy: orbito/erli. Pierwszą wersję użytkownik wgrywa ręcznie. Paczkę przygotowujemy oficjalnym CLI:

omm pack --dry-run
omm pack -o ../release-packages/core-erli-0.4.1.zip

Kolejne wydania: zwiększ zgodnie wersje module.json, package.json oraz package-lock.json, uruchom testy i sprawdź paczkę. Zapisz kod w repozytorium, a następnie opublikuj w rejestrze:

omm publish --release --changelog "Opis zmian"

Pomyślna publikacja obrazu w rejestrze nie oznacza aktualizacji zainstalowanego modułu. Po aktualizacji instancji sprawdź formularz i obieg zamówienia w Orbito.

Zakres

Test klucza przez GET /me, pobranie słowników metod dostawy i przewoźników.
Import zamówień przez POST /orders/_search, sortowanie po aktualizacji,

trwały kursor, zakładka 2 minut i maksymalnie 5 stron po 100 rekordów na przebieg. Po przerwaniu pełna strona jest kontynuowana od zapisanego kursora.

Trwały zapis danych źródłowych, ponowne odczyty zamówień oczekujących i problematycznych.
Idempotentny zapis przez orders.create, z tożsamością sklepu, środowiska i instancji.
Dane odbiorcy, firmy, NIP, punktu odbioru, komentarza klienta, pozycji, rabatów,

kwot brutto/netto, VAT, waluty i płatności.

pending oczekuje w kolejce. purchased online oznacza wpłatę; pobranie nie

tworzy wpłaty. Historia jest importowana bez automatyzacji sprzedaży.

Niepełny VAT, SKU, odbiorca, faktura lub niespójne sumy: import w trybie

review z financialPending; bez automatycznego eksportu.

Numery z rejestru przesyłek przez POST /shipping/external, następnie status

sent przez PATCH /orders/{id}/status. Obsługa wielu wpisów przesyłek, pod warunkiem jednego numeru na każdy wpis. Eksport wymaga ustawionego statusu fizycznej wysyłki w Orbito; samo utworzenie etykiety nie wystarcza.

Nadawanie ERLI przez POST /shipping/parcels/, odczyt punktów nadania,

etykiety PDF i tracking z GET /shipping/parcels/{id}. Numer paczki jest zapisywany przed pobieraniem etykiety. Niepewne nadanie nie jest automatycznie powtarzane. ERLI może dobrać niższy wariant wagowy tej samej usługi. Akceptujemy go tylko w tej samej grupie, u tego samego operatora, z tym samym pobraniem i po sprawdzeniu wymiarów oraz limitów z aktualnego słownika. Zapisujemy faktyczny wariant dla późniejszego odczytu etykiety i śledzenia. Odczytowy kontrakt shipping.carrier.reconcilePackingDispatch potwierdza istniejące paczki i odpowiadające im wpisy w wybranym rejestrze przesyłek. Nie tworzy ani nie drukuje nowych listów. Diagnostyka shipping.parcelDiagnostics pokazuje stan prób i paczek, bez danych odbiorcy i adresów etykiet.

Panel diagnostyki, ponowienie definitywnie odrzuconego eksportu i odczytowe

uzgodnienie niepewnego zapisu po wskazaniu istniejącego ID przesyłki ERLI.

Ogólne nazwy punktów (np. „Punkt DHL”, „Punkt InPost”) nie są importowane. Dla wcześniejszych zamówień synchronizacja usuwa niezmienioną nazwę źródłową przez kontrakt orders.source.updateLabels z flagą sourcePickupPointLabels. Obsługuje ją core/orders od 2.18.29; alternatywni dostawcy mogą implementować ten sam kontrakt. Kod punktu, adres i ręcznie wpisane nazwy pozostają zachowane.

Konfiguracja

Zainstaluj pakiet jako core/erli; zezwól na domenę API w sieci platformy.
Podaj nazwę źródła, klucz z ustawienia „Własna integracja po API” i adres API.

Produkcja: https://erli.pl/svc/shop-api. Testy: adres HTTPS uzyskany od ERLI, zakończony /svc/shop-api, z osobnym kluczem i osobną instalacją modułu.

Sprawdź połączenie i słowniki. Klucz jest polem SECRET; nie jest zwracany

przez diagnostykę ani zapisywany w logach i danych zamówień.

Wybierz ID instancji dostawcy zamówień i opcjonalnie rejestru przesyłek.

Listy są pobierane hookami w bieżącej instancji. Błąd listy jest widoczny, zapisane identyfikatory i mapowania nie są kasowane.

Wybierz różne statusy: nowe, weryfikacja, historia i fizyczna wysyłka.
Ustaw datę startu według Europe/Warsaw. Puste pole oznacza dzień i godzinę

pierwszego potwierdzonego połączenia. „Synchronizuj teraz” ponawia odczyt od tej daty; nie przywraca automatycznie zamówień usuniętych w Orbito.

Ceny API są w groszach. Klient automatycznie konwertuje wartości całkowite przez 100. Kwota końcowa musi zgadzać

się z sumą pozycji i dostawy, inaczej finansowe dane czekają na weryfikację.

Ustaw jawny VAT dostawy. VAT produktu pochodzi z zamówienia; opcjonalny

fallback stosowany jest wyłącznie wtedy, gdy stawki brakuje. TAX_NP/TAX_ZW i nieznane kody nie są zamieniane na TAX_0 ani 23%.

Każde konto przewoźnika mapuj po ID instancji na kod z CreateExternalParcel.

Brak mapowania blokuje tę operację; nie wybieramy pierwszego dostawcy.

Włącz import. Eksport włącz osobno po weryfikacji procesu statusów i nadań.

Architektura i utrata odpowiedzi

Komunikacja między modułami wyłącznie przez lokalną kopię src/hook-contract.js. Nie ma dependsOn ani RPC do innych instalowalnych modułów. Wszystkie żądania wybierają zapisany ID instancji dostawcy. Brak i niejednoznaczność dostawcy są rozpoznawane przez wspólny protokół przed efektem.

Worker działa pod odnawianą blokadą z ID instalacji. Zmiana konfiguracji, połączenia lub utrata blokady zatrzymuje kolejne efekty. Postęp i zamiar zapisu przesyłki są trwałe. Timeout, 5xx, zła odpowiedź lub restart po wysłaniu żądania nie powodują ponowienia tworzenia przesyłki.

Niepewna przesyłka wymaga wskazania ID istniejącej przesyłki w ERLI. Moduł odczytuje GET /shipping/external/{id} i porównuje sklep (uprawnienia tokena), zamówienie, typ, przewoźnika i numer. Zgadywana nieobecność ani przycisk „potwierdzam brak” nie uprawniają do ponowienia. Zmianę statusu o niepewnym wyniku uzgadniamy przez kolejny odczyt sellerStatus, bez ponownego PATCH.

Nie konsumujemy ani nie oznaczamy Inbox jako przeczytanego, dzięki czemu moduł nie zabiera wiadomości innym integracjom tego sklepu. Inbox i webhooki są możliwym rozszerzeniem, po ustaleniu współistnienia integracji.

Ograniczenia wydania 0.2

Zamówienia z dostawą ERLI/ErliPRO są importowane. Nadania przez ERLI obsługują

usługi InPost, DHL, DPD, Orlen Paczka i Pocztex obecne w API, jedną paczkę na zamówienie.

Brak odbioru osobistego, transportu własnego i rynku DE.
Brak uploadu faktury: publiczna specyfikacja nie potwierdza tej operacji.

Faktury wystawia dotychczasowy dostawca Orbito, a moduł nie podszywa się pod dostawcę księgowego i nie wysyła PDF do endpointów załączników produktów.

Zmiana pozycji, adresu lub kwot w ERLI po imporcie blokuje realizację i eksport.

Nie nadpisujemy korekt operatora. Bezpieczne zatwierdzenie zmiany i naprawa danych źródła są kolejnym etapem; samo ponowienie synchronizacji nie odblokowuje.

Zwroty i anulowania są wykrywane; nie wystawiamy korekt, nie zwracamy pieniędzy

ani nie anulujemy paczek automatycznie.

Scalanie zamówień i wpisy wielopaczkowe bez osobnych numerów wymagają jawnego

podziału źródeł; eksport jest zatrzymany.

Brak własnej synchronizacji ofert i stanów magazynowych. Import pozycji

wykorzystuje istniejący kontrakt katalogu obsługiwany przez dostawcę zamówień.

SDK i testy lokalne nie potwierdzają aktualizacji działającej instancji.

Formularz, dostęp sieciowy, kwoty oraz odpowiedzi API wymagają testu na sklepie.

Weryfikacja

npm ci --ignore-scripts
npm test
npm run check

Z katalogu workspace:

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

Źródła protokołu ERLI (CreateParcels sprawdzone 2026-10-07):

https://erli.pl/svc/shop-api/doc/
https://erli.pl/svc/shop-api/doc/swagger.json
https://erli.pl/svc/shop-api/doc/CHANGELOG.txt

Implementacja i testy używają syntetycznych danych. Import potwierdzono w działającym sklepie. Testy nadania i etykiet używają syntetycznych odpowiedzi; rzeczywiste nadanie wymaga danych konkretnej paczki.

Uzupełnianie źródeł i cen produktu

Od 0.2.3 synchronizacja dopisuje konto ERLI i jego cenę do istniejącego SKU, również dla wcześniej zaimportowanych zamówień (do 40 na przebieg). Wymaga dostawcy reklamującego idempotentSourceCatalogPrices, w core/orders od 2.18.30, oraz core/products 1.2.3. Wywołanie orders.source.syncCatalog z sourcePrices: true jest adresowane do zapisanej instancji zamówień i można bezpiecznie ponowić je po utracie odpowiedzi. Kartoteka, ręczne dane i BOM pozostają bez zmian. Starsze zamówienia nie nadpisują ceny nowszego zamówienia w tym samym kanale. Zamówienia oczekujące na kontrolę finansową nie uzupełniają cen. Błąd jest widoczny w panelu synchronizacji ERLI.

Po aktualizacji Products → Orders → ERLI uruchom „Synchronizuj teraz”; nie usuwaj i nie importuj ponownie zamówień.

Przewoźnik i logo przy dostawie ERLI/ErliPRO

Od 0.2.6 oraz core/shipping ≥2.14.4 dostawa ERLI/ErliPRO wskazuje konto źródłowe przez shipping.source.getCarrierSelection. Shipping respektuje pasujące warunki i zachowuje ich carrierOptions. Kafelki mają logo ERLI, nazwę rzeczywistej usługi i zapisane wymiary. Formularz nie otwiera się po kliknięciu szybkiego nadania. Lista usług i ich limity pochodzą z GET /dictionaries/shippingMethods; błąd odczytu nie zastępuje danych konfiguracji ani konta.

Nazwane szablony paczek

W Przesyłkach → Warunki doboru przewoźnika wybierz konto Przesyłki ERLI, wpisz nazwę kafelka, wymiary i zakres od/do kg. Ustaw frazę z dostawy zamówienia (np. InPost, Orlen, DHL lub Pocztex). Jeden warunek daje jeden nazwany kafelek; A/B/C to trzy warunki. Wymiary pochodzą z warunku, waga z wszystkich produktów i zestawów zamówienia, bez wagi opakowania i wartości zapasowej. ERLI wybiera zgodną usługę z aktualnego słownika dla grupy dostawy, COD, wymiarów i wagi. Logo pozostaje ERLI. Stare przypisania szablonów nadal są obsługiwane przez Przesyłki.

Od 0.3.1 usunięto zakładkę Domyślne nadanie. Stare wartości nie są używane. Bez skonfigurowanej paczki kafelek wskazuje konieczność uzupełnienia warunku. Otwarta wcześniej opcja korzystająca ze starego profilu nie nada paczki; trzeba odświeżyć zamówienie. Odzyskiwanie istniejących nadań nadal działa.

Od 0.3.4 limity osi ze słownika usług ERLI są normalizowane z cm do mm; waga słownika pozostaje w gramach, suma boków i najdłuższy bok pozostają w cm. Potwierdzono rzeczywisty słownik konta produkcyjnego: Paczkomat 64×38×41 cm, DHL Kurier 120×60×60 cm. API używa innej kolejności osi niż szablon: dobieramy obrót tej samej paczki pasujący do limitów, zachowując wszystkie trzy wymiary i rzeczywistą wagę. Do CreateParcels wysyłamy osie w mm i wagę w gramach.

Sposób realizacji i automatyczna konfiguracja (0.4.0)

W Przesyłki ERLI → Wysyłka realizowana przez wybierz Własne umowy lub ERLI. Nowa instalacja zaczyna od własnych umów; istniejące połączone instalacje zachowują możliwość nadawania ERLI. Własne umowy ukrywają nowe nadania i preinstalowane warunki ERLI, zachowując dostęp do etykiet i trackingu już nadanych przesyłek. Usunięto pola mapowania kont na przewoźników ERLI. Historyczne mapowania są zachowane; nowe przesyłki rozpoznają operatora z rzeczywistej nazwy przewoźnika i słownika ERLI. Niejednoznaczna nazwa zatrzymuje eksport z czytelnym błędem.

Po wyborze ERLI, połączeniu API i wskazaniu rejestru przesyłek moduł automatycznie wywołuje shipping.conditions.provision w tej konkretnej instancji (shipping 2.17.0 lub dostawca tego kontraktu). Nie wymaga włączonego importu. Startowy zestaw tworzy się raz: zastępuje wcześniejsze warunki tylko tego konta ERLI, a oryginały zostają zachowane. Kolejne uruchomienia nie nadpisują zmian użytkownika. InPost A/B/C mają standardowe skrytki, Orlen A/B/C pochodzi z S/M/L słownika. Pozostałe nazwy opisują operatora, usługę i gabaryt lub limit kg. Każdy szablon przypina dokładny identyfikator usługi i zachowuje wagę produktów zamówienia.

Wymiary startowe wynikają z limitów usług; dostosuj je do rzeczywistych kartonów, zwłaszcza przy wadze gabarytowej. Jeśli API podało tylko sumę boków i najdłuższy bok, zachowujemy istniejące zgodne wymiary albo tworzymy nazwany warunek wymagający ich uzupełnienia. Nie wymyślamy rozmiarów kartonu z sumy boków. Błąd instalacji jest widoczny w diagnostyce i nie blokuje importowania zamówień.

Plany opakowań

Hub przesyłek może przekazać potwierdzony packingPlan przez kontrakt shipping.carrier. Wymiary i waga brutto pochodzą z planu, a adapter ponownie sprawdza zgodność z aktualnym zamówieniem przed nadaniem. Zmiana zamówienia wymaga ponownego potwierdzenia. Obsługa jest deklarowana przez packingPlans: true oraz packingPlanVersions: [1, 2]. Wersja 2 obsługuje zestawy z osobnymi trybami połączenia kartonów; do API trafia wynikowa lista paczek. Nadal obowiązują limity usług i liczby paczek; starszy hub zachowuje dotychczasowy sposób nadania.

Aktualny adapter obsługuje jedną fizyczną paczkę. Plan osobnych podpaczek jest jawnie odrzucany; kartony połączone mogą być obsłużone po kontroli limitów usługi.

Gdy usługa nie obsługuje podpaczek w jednym nadaniu, aktualny Shipping może nadać każdą fizyczną paczkę na osobnym liście (separateShipments, packingParcelIndex). Pełny plan jest ponownie walidowany przed każdym nadaniem. Pobranie jest dzielone według sum maksymalnych obciążeń kartonów w paczce, w groszach, tak aby suma na wszystkich listach była dokładnie równa kwocie zamówienia. Każdy zapisany list ma własną etykietę i zdarzenie do istniejącej automatyzacji wydruku. Częściowy sukces lub niepewna odpowiedź zatrzymuje serię i blokuje automatyczne ponowienie.

API ERLI CreateParcels nie udostępnia pola częściowego pobrania; wariant z indeksem paczki jest odrzucany dla COD przed utworzeniem listu. Osobne listy są dostępne dla dostaw opłaconych.

0.5.13 — ochrona statusów po imporcie

Odcisk obejmuje wartości adresu, pozycji i rozliczeń, bez kolejności pól i metadanych ofert. Status problemów jest nadawany wyłącznie podczas pierwszego importu. Późniejsza zmiana źródła zatrzymuje niebezpieczne operacje, ale nie cofa statusu realizacji. Stare odciski są migrowane tylko ze zweryfikowanego punktu odniesienia.

Jawne metody import.previewStatusRecovery (from, to; maksymalnie doba) i import.restoreStatuses (planId, limit) odtwarzają statusy na podstawie historii platformy i hooków wybranej instancji. Plan obowiązuje godzinę; późniejsze zmiany operatora i niepewny wynik nie są ponawiane. Metody wymagają erli.manage. Naprawa statusów nie zatwierdza zmienionych danych źródłowych i nie ponawia nadań.