Nowe Kolory — core/nowekolory 0.1.0

Pierwsza lokalna wersja przewoźnika dla Rumunii i transportu gotowych paczek do magazynu brokera. Jedno konto to jedna instalacja modułu. Uruchomienie modułu nie wykonuje nadań.

Praca magazynu

Nadaj paczki klienta przewoźnikiem Nowe Kolory w rejestrze przesyłek. Odbiorca, wartość i pobranie pochodzą z zamówienia. Wpisz rzeczywiste wymiary i wagę. Każda paczka z planu pakowania otrzymuje osobny list przewozowy.
Pobierz rumuńskie etykiety i naklej je na paczki. Zakończ pakowanie całego zamówienia.
W sekcji Nowe Kolory na karcie zamówienia wybierz Potwierdź gotowość paczek. System sprawdza komplet przesyłek i etykiet; fizyczne naklejenie potwierdza magazynier.
W zakładce Nowe Kolory wybierz gotowe zamówienia i podaj gabaryty oraz wagę brutto zewnętrznego kartonu. Utwórz zamówienie zbiorcze. Jeden transport oznacza jeden karton.
Nadaj karton do Bielska wybranym kontem DPD i pobierz jedną etykietę zewnętrzną. Listy rumuńskie i zamówienia klientów pozostają osobne.

Transport ma manifest sumujący ilości produktów oraz powiązania z zamówieniami i paczkami. Towary są w transport.contents, a products jest puste. Kwota sprzedaży wynosi zero; brak pobrania, płatności, faktury i zdarzeń tworzenia sprzedaży. Właściciel zamówień blokuje kopiowanie, łączenie ze sprzedażą, dodawanie produktów, płatności, zmianę faktury i adresu transportu.

Doręczenie kartonu do magazynu brokera zapisuje historię transportu. Nie uruchamia automatyzacji wysyłki i doręczenia zamówień klientów.

Konfiguracja

Login, hasło i accountID od brokera. Hasło ma format sekretu konfiguracji. Sprawdź połączenie wyłącznie weryfikuje logowanie.
Konkretne instancje zamówień i rejestru przesyłek. Po pierwszym nadaniu konto jest związane z tymi rejestrami. Listy pochodzą z hooków; błędy zachowują zapisane ID.
Konkretne konto przewoźnika obsługujące transport — dla tego przebiegu konto DPD — i istniejący status transportu.
Pełny, potwierdzony adres magazynu w Bielsku-Białej, telefon i e-mail. Ulica pozostaje pusta do uzupełnienia.
Opcjonalne courier i platformSource według informacji brokera.
Potwierdzona mapa kodów historii. Domyślnie pusta: nieznany kod pozostaje nieznany, a przyjęcie w magazynie nie oznacza doręczenia klientowi.

API i zakres

Źródło: oficjalna dokumentacja Nowe Kolory, OpenAPI 1.3.12, sprawdzona 12.10.2026. Host: https://api.nklogistic.pl/noweKoloryParcelApi/api. Środowisko zależy od konta. Logowanie używa query i tokenu Bearer. Brak schematu odpowiedzi logowania: adapter akceptuje JWT jako tekst lub accessToken/access_token; inny format wymaga potwierdzenia.

Obsługujemy tworzenie przesyłek, PDF/ZPL, historię i odczyt informacji o znanym AWB. Waga jest przeliczana na gramy, wymiary na całkowite cm. Zakres: RO/RON, COURIER/EASYBOX/SAMEDAY_LOCKER/FAN_COURIER_LOCKER z potwierdzonym kontekstem źródła. Nie zlecamy odbioru kuriera, zwrotów, usuwania przesyłek ani setParcelAsSent.

Warunki wymagania regionu i e-maila są niejednoznaczne. Dla RO wymagamy regionu i prawdziwego e-maila odbiorcy. eMAG udostępnia hash e-maila; zwolnienie z wymagania musi potwierdzić broker. Formularz pozwala uzupełnić dane ręcznie; przy szybkim nadaniu e-mail musi być zapisany w zamówieniu. Słownik kodów historii również wymaga informacji brokera.

API nie dokumentuje idempotencji ani wyszukania po naszym orderID. Nie zakładamy, że sam identyfikator zapobiega duplikatom.

Utrata odpowiedzi i ograniczenia

Zamiar nadania zapisujemy przed efektem. Znany numer listu można przekazać do rejestru ponownie bez nowego nadania. Niepewny wynik blokuje kolejne próby i wymaga sprawdzenia panelu oraz uzgodnienia z operatorem.

Lokalny dokument transportowy ma deterministyczne ID. Ten sam identyfikator i dane odzyskują ten sam dokument. Przy przerwanym tworzeniu użyj Dokończ tworzenie tego transportu. Rejestr i przewoźnik transportu prowadzą osobne trwałe dzienniki; nie ponawiamy niepewnego nadania DPD. Paczki mogą należeć do jednego transportu tego konta.

Wersja 0.1.0 nie ma automatycznego odblokowania niepewnego nadania ani anulowania/przebudowy utworzonego transportu. Manifest i adres są niezmienne. Przed utworzeniem sprawdź karton i limity usługi przewoźnika. Nie resetuj dziennika po niepewnym wyniku bez potwierdzenia operatora.

Kontrakty i instalacja

Cała komunikacja używa hooków i konkretnych ID instancji, bez fallbacku RPC. Nowe kontrakty:

sources.order.fulfillmentContext({orderId, sourceUniqueId}): zweryfikowana tożsamość marketplace i dostawy; źródło wskazuje zapisane ID zamówienia. Dostawca eMAG sprawdza świeże dane i anulowanie.
orders.transport.snapshot({orderId}): hash surowych danych zamówienia u właściciela.
orders.transport.create({transportId, sourceOrderIds, shipmentIds, sourceSnapshots, recipient, parcel, statusId}): idempotentny transport bez sprzedaży. Właściciel pochodzi z uwierzytelnionego kontekstu, a snapshoty są sprawdzane przed zapisem.
shipping.transports.ship({orderId, ordersInstanceId, carrierInstanceId}): nadanie i zapis jednej przesyłki z purpose: transport.
shipping.carrier.createTransportShipment({orderId, ordersInstanceId, requestId, parcel}): jedna przesyłka bez pobrania; implementacja DPD prowadzi własny dziennik.

Ponadto używamy standardowych kontraktów przewoźnika, przesyłek, odczytu zamówień, statusów, referencji i wkładów do widoku.

Potrzebne są przygotowane w workspace aktualizacje właściciela zamówień, rejestru przesyłek, źródła eMAG i przewoźnika DPD. Starsze wydania bez tych kontraktów nie obsłużą przebiegu. Wersja jest przygotowana lokalnie, bez publikacji i instalacji produkcyjnej.

Weryfikacja

npm ci
npm test
npm run check

Z workspace uruchom również testy module-contracts/*.test.js i testy zmienionych dostawców. module-contracts/transport-workflow.test.js sprawdza przez rzeczywiste hooki dwa zamówienia, osobne rumuńskie etykiety, jeden karton do Bielska i utratę odpowiedzi. API i baza są atrapami. Próba na koncie testowym brokera/DPD i sprawdzenie widoków po instalacji pozostają do wykonania.