feat(128): polkurier shipment service + tracking + UI prepare

PolkurierApiClient rozszerzony do pelnego kontraktu (7 metod):
createShipment/getLabel/getStatus/cancelOrder/getAvailableCarriers/
getInpostParcelMachines/getCourierPoints. Wspolny call() parsuje
envelope {status, response}. Kontrakt zweryfikowany na oficjalnej
dokumentacji PDF v1.11.

PolkurierShipmentService (implements ShipmentProviderInterface)
orchestruje pelen flow: normalizeShipmentType (lowercase), split
ulicy, build recipient/sender/pickup, COD z bank account z
company_settings, extractOrderNumber/extractTrackingNumber
priorytetujace SDK Order entity (number, waybills[0].number).

PolkurierTrackingService (implements ShipmentTrackingInterface)
mapuje statusy O/P/A/WP/D/Z/W przez delivery_status_mappings.

UI panel polkurier w prepare.php z dynamiczna lista uslug z
available_carriers. Bez dedykowanego selektora punktu — operator
wpisuje receiver_point_id w istniejace pole w sekcji Adres odbiorcy.

Migracja 20260514_000115 seedujaca 7 wpisow delivery_status_mappings
z oficjalnej tabeli ORDER_STATUS (O/P/A/WP/D/Z/W).

Live test #114/#115 zakonczony sukcesem po 4 iteracjach
(ReferenceError -> uppercase shipmenttype -> orderno parsing ->
A4/A6 etykieta). Rozmiar etykiety A4/A6 sterowany w panelu klienta
polkurier.pl, NIE przez API.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.paul/PROJECT.md

@@ -13,8 +13,8 @@ Sprzedawca może obsługiwać zamówienia ze wszystkich kanałów
 | Attribute | Value |
 |-----------|-------|
 | Version | 3.7.0-dev |
-| Status | v3.7 in progress — Phases 113-127 shipped (Fakturownia + HostedSMS/SMSPLANET + Alert unify + receipt VAT + SMS templates + invoice_requested import fix + invoice GUS mapping + polkurier foundation) |
-| Last Updated | 2026-05-14 (Phase 127 closed) |
+| Status | v3.7 in progress — Phases 113-128 shipped (Fakturownia + HostedSMS/SMSPLANET + Alert unify + receipt VAT + SMS templates + invoice_requested import fix + invoice GUS mapping + polkurier foundation + polkurier shipment service) |
+| Last Updated | 2026-05-14 (Phase 128 closed) |
 
 ## Requirements
 
@@ -127,6 +127,7 @@ Sprzedawca może obsługiwać zamówienia ze wszystkich kanałów
 - [x] Szablony SMS: CRUD w `/settings/sms-templates` (name + body + is_active), wspolny `SmsVariableResolver` wydzielony z Email\\VariableResolver (placeholdery `{{zamowienie.*|kupujacy.*|adres.*|firma.*|przesylka.*}}`), dropdown "Wybierz szablon" w zakladce SMS na `/orders/{id}` wstawia rozwiniete zmienne do textarea (z `OrderProAlerts.confirm` przy nadpisaniu); stopka SMSPLANET dalej doklejana wylacznie przez `SmsConversationService::buildFinalOutboundBody()` (Phase 122 contract preserved) — Phase 124
 - [x] Bugfix detekcji faktury przy imporcie: shopPRO order z `firm_nip` ustawia `invoice_requested=1` (mapper jako jedyne zrodlo heurystyki, sync service propaguje `aggregate['invoice_detected']`); Allegro rozszerzony o `naturalPerson=false`/`address.taxId`/`companyName` (wczesniej tylko `invoice.required`); usunieta legacy kolumna `orders.is_invoice` (Phase 115 dryft) + backfill 7 zamowien — Phase 125
 - [x] Integracja polkurier.pl (fundament): pojedyncza globalna konfiguracja w `/settings/integrations/polkurier`, szyfrowany Token API + login, karta w hubie integracji obok Apaczki i realny test polaczenia przez `apimetod=test_auth_api` zweryfikowany na zywym koncie operatora; `ShipmentProviderRegistry` netkniety — `PolkurierShipmentService/TrackingService` w kolejnych fazach — Phase 127
+- [x] polkurier ShipmentService + TrackingService + UI prepare panel: pelen kontrakt API (createShipment/getLabel/getStatus/cancelOrder/getAvailableCarriers), `PolkurierShipmentService` implementujacy `ShipmentProviderInterface` z normalizacja shipmenttype (lowercase) i splitem ulicy na street/housenumber/flatnumber, `PolkurierTrackingService` mapujacy statusy O/P/A/WP/D/Z/W na znormalizowane, panel "polkurier" w `prepare.php` z dynamiczna lista uslug z `available_carriers`, seed migracja `delivery_status_mappings(provider='polkurier')` z 7 wpisami z PDF v1.11; live test na #114/#115 zakonczony sukcesem po 4 iteracjach (ReferenceError → uppercase shipmenttype → orderno parsing → A4/A6); rozmiar etykiety sterowany w panelu klienta polkurier.pl (Ustawienia konta → Preferencje etykiet), NIE przez API — Phase 128
 
 ### Deferred
 
@@ -243,6 +244,11 @@ PHP (XAMPP/Laravel), integracje z API marketplace'Ăłw (Allegro, Erli) oraz API
 | polkurier API: top-level `status` === `'success'` (nie `'ok'`), tresc bledu w polu `response` envelope'a | `ResponseStatus::SUCCESS = 'success'` z `src/Type/ResponseStatus.php` SDK; bledy rzucane przez `ErrorException($response->get('response'))` w `PolkurierWebService.php`. Pattern dla wszystkich przyszlych metod polkurier API (`createShipment`, `getLabel`, `getStatus`, `cancelOrder`, etc.) | 2026-05-14 | Active |
 | polkurier API odrzuca `Content-Type` z parametrem (`application/json; charset=UTF-8`) — wymagany dokladnie `application/json` | Strict equality check po stronie polkuriera; pattern do reuse jezeli inne integracje sa rownie strict | 2026-05-14 | Active |
 | polkurier dziala obok Apaczki (nie zamiast) | Decyzja operatora — oba dostawcy zyja niezaleznie, `ShipmentProviderRegistry` rejestruje obu (Apaczka netknieta w Phase 127; polkurier dodany w nastepnej fazie razem z `PolkurierShipmentService`) | 2026-05-14 | Active |
+| polkurier `shipmenttype` wymaga lowercase z zbioru `[box, envelope, palette, small_parcel, parcel_size_20]` | API odrzuca uppercase `BOX` (komunikat: "Typ paczki musi przyjmowac jeden z parametrow ze zbioru ..."). `normalizeShipmentType()` w `PolkurierShipmentService` mapuje legacy PACKAGE/BOX/PARCEL/PACZKA/KOPERTA/PALETA na format polkuriera z aliasami i defaultem `box`. | 2026-05-14 | Active |
+| polkurier `create_order` zwraca Order entity z polem `number` (nie `orderno`) i `waybills[0].number` | SDK Order.php uzywa setNumber()/addWaybill() — JSON shape entity, nie parametrow input. `extractOrderNumber` priorytetuje `number`, fallback na `orderno`/`order_no`/`order_number`/`order_id`/`id` + obsluga wrapperow `{order:{...}}` i list. `extractTrackingNumber` priorytetuje `waybills[0].number`. Pattern do reuse dla innych metod polkurier SDK. | 2026-05-14 | Active |
+| polkurier API nie ma parametru rozmiaru etykiety (A4/A6) | Zweryfikowane na PDF v1.11: `get_label` przyjmuje wylacznie `orderno: Array<String>`, `create_order` nie ma pola format/size. Rozmiar sterowany w panelu klienta polkurier.pl (Ustawienia konta → Preferencje etykiet) — operator zmienia preferencje konta jednorazowo. `polkurier_integration_settings.default_label_format` (PDF/ZPL/EPL) odnosi sie tylko do typu pliku, NIE rozmiaru. | 2026-05-14 | Active |
+| Brak dedykowanego selektora punktow paczkomatowych w UI polkurier (Phase 128) | Istnieje juz pole `name="receiver_point_id"` w sekcji Adres odbiorcy z auto-fillem `parcel_external_id` z importu zamowienia — operator wpisuje ID recznie (np. `POP-RZE54`). Usuniete: `lookupPickupPoints`/`ShipmentController::polkurierPoints`/AJAX route/JS handler. `getInpostParcelMachines`/`getCourierPoints` zachowane jako stuby w API client — gotowe dla kolejnej fazy paczkomaty UI. | 2026-05-14 | Active |
+| Diagnostyka silent-fail w ShipmentService — zapis surowej odpowiedzi do `error_message` | Gdy parsing API odpowiedzi zwraca pusty wynik mimo `status=success` (np. nieznany shape pola order number), zapisuj fragment surowej odpowiedzi (400 znakow) do `shipment_packages.error_message` — widoczne operatorowi w UI bez podgladu serwerowych logow. Pattern uratowal 3. iteracje live testu Phase 128. Reuse dla nowych integracji z API o nieznanym shape odpowiedzi. | 2026-05-14 | Active |
 
 ## Success Metrics
 
@@ -274,6 +280,6 @@ Quick Reference:
 
 ---
 *PROJECT.md — Updated when requirements or context change*
-*Last updated: 2026-05-14 after Phase 127 (polkurier Integration Foundation) closure; v3.7 milestone in progress*
+*Last updated: 2026-05-14 after Phase 128 (polkurier ShipmentService + Tracking + UI prepare) closure; v3.7 milestone in progress*
 
 

.paul/ROADMAP.md

@@ -27,9 +27,9 @@ Wystawianie faktur dla klientow z NIP poprzez integracje z Fakturownia (app.fakt
 | 125 | invoice_requested Import Fix (shopPRO+Allegro NIP detection, drop legacy is_invoice column) | 1/1 | Complete (2026-05-13; migration + manual smoke pending operator) |
 | 126 | Invoice GUS Field Mapping Fix (KRS-based heuristic: JDG → name do "Imię i nazwisko", spółka → "Nazwa firmy") | 1/1 | Complete (2026-05-13; manual smoke pending operator) |
 | 127 | polkurier Integration Foundation (single-instance settings + Token API + realny test polaczenia; obok Apaczki) | 1/1 | Complete (2026-05-14; live API verified — `Autoryzacja: 1`) |
+| 128 | polkurier ShipmentService + TrackingService + UI prepare panel + delivery_status_mappings seed (live test na #114/#115) | 1/1 | Complete (2026-05-14; live test passed po 4 iteracjach; migracja + cron tracking weryfikacja pending) |
 
 Planowane kolejne fazy v3.7 (kandydaci, do rozplanowania):
-- polkurier ShipmentService (CreateOrder + GetLabel + OrderValuationV2 + AvailableCarriers mapping + UI mapowan metod dostawy + presety) — fundament 127 zweryfikowany
 - polkurier TrackingService + `delivery_status_mappings` (provider='polkurier')
 - polkurier paczkomaty (`InpostParcelMachines` / `PocztexPostOffices` / `Kurier48PostOffices` z SDK polkuriera)
 - Eksport XLSX listy wystawionych faktur (analogicznie do paragonow)
@@ -512,4 +512,4 @@ Archive: `.paul/milestones/v0.1-ROADMAP.md`
 
 ---
 *Roadmap created: 2026-03-12*
-*Last updated: 2026-05-14 - Phase 127 UNIFY closed (live API verified)*
+*Last updated: 2026-05-14 - Phase 128 UNIFY closed (live test passed, etykiety A6 OK)*

.paul/STATE.md

@@ -5,33 +5,33 @@
 See: .paul/PROJECT.md (updated 2026-05-07)
 
 **Core value:** Sprzedawca moze obslugiwac zamowienia ze wszystkich kanalow sprzedazy i nadawac przesylki bez przelaczania sie miedzy platformami.
-**Current focus:** v3.7 Invoices + operational integrations - Phase 127 polkurier foundation UNIFY zakonczony, transition (commit + ROADMAP/PROJECT update) pending.
+**Current focus:** v3.7 Invoices + operational integrations - Phase 128 polkurier ShipmentService loop closed, transition pending (git commit + ROADMAP/PROJECT update).
 
 ## Current Position
 
 Milestone: v3.7 Invoices (Fakturownia integration) - In progress
-Phase: 127 of TBD (polkurier Integration Foundation) - Complete
-Plan: 127-01 complete (SUMMARY.md created); live API verified (`Autoryzacja: 1`)
-Status: UNIFY complete, transition pending (git commit + decisions in PROJECT.md)
-Last activity: 2026-05-14 - Phase 127-01 UNIFY zakonczony, SUMMARY + changelog utworzone
+Phase: 128 of TBD (polkurier ShipmentService + Tracking + UI) - Complete
+Plan: 128-01 complete (SUMMARY.md created)
+Status: UNIFY complete, transition pending (git commit + Decisions w PROJECT.md + ROADMAP status)
+Last activity: 2026-05-14 - Phase 128-01 UNIFY zakonczony, SUMMARY + changelog utworzone
 
 Progress:
-- Milestone v3.7: [##########] ~99% (Phase 113-127 complete; transition pending)
-- Phase 127: [##########] 100%
+- Milestone v3.7: [##########] ~99% (Phase 113-128 complete; transition pending)
+- Phase 128: [##########] 100%
 
 ## Loop Position
 
 Current loop state:
 ```
 PLAN -> APPLY -> UNIFY
-  done      done       done   [Loop complete - transition pending]
+  done       done       done   [Loop complete - transition pending]
 ```
 
 ## Session Continuity
 
 Last session: 2026-05-14
-Stopped at: Phase 127-01 UNIFY closed; SUMMARY.md created
-Next action: Phase transition (git commit `feat(127): polkurier integration foundation` + Decisions w PROJECT.md), potem wybor kolejnego kandydata v3.7 (np. PolkurierShipmentService albo invoice.created event)
+Stopped at: Phase 128-01 UNIFY closed; SUMMARY.md created
+Next action: Phase transition (git commit `feat(128): polkurier shipment service + tracking + UI prepare` + Decisions w PROJECT.md + ROADMAP status update), potem wybor kolejnego kandydata v3.7 (paczkomaty UI / shipment_presets polkurier / OrderValuationV2 / invoice.created event / eksport XLSX faktur)
 Resume file: .paul/ROADMAP.md
 
 ## Pending parallel work
@@ -39,9 +39,9 @@ Resume file: .paul/ROADMAP.md
 
 ## Git State
 
-Last phase commit: c758ec7 feat(126): invoice GUS field mapping fix (JDG/KRS heuristic)
-Previous: 2ab461a feat(125): invoice_requested import fix + drop legacy is_invoice column
-Branch: main (5 commits ahead of origin/main)
+Last phase commit: 3443879 feat(127): polkurier integration foundation
+Previous: c758ec7 feat(126): invoice GUS field mapping fix (JDG/KRS heuristic)
+Branch: main (6 commits ahead of origin/main)
 
 ## Pending Actions
 
@@ -68,6 +68,9 @@ Branch: main (5 commits ahead of origin/main)
 - Phase 127 follow-up: zaplanowac kolejna faze polkurier — `PolkurierShipmentService` (CreateOrder + GetLabel + OrderValuationV2 + AvailableCarriers mapping + UI mapowan metod dostawy + presety przesylek) — fundament + zweryfikowany kontrakt API gotowy.
 - Phase 127 follow-up: drugi krok — `PolkurierTrackingService` + wpisy w `delivery_status_mappings` (provider='polkurier').
 - Phase 127 follow-up: po polkurier shipment service rozwazyc fazy paczkomaty (`InpostParcelMachines` / `PocztexPostOffices` / `Kurier48PostOffices` API juz dostepne w SDK polkuriera).
+- Phase 128 follow-up: uruchom migracje gdy XAMPP MySQL online: `php bin/migrate.php` (seed 7 wpisow `provider='polkurier'` w `delivery_status_mappings`).
+- Phase 128 follow-up: weryfikacja crona `shipment_tracking_sync` przy pierwszej zywej paczce polkurier w `in_transit` — sprawdz ze `shipment_packages.delivery_status` aktualizuje sie z `D`/`WP`/`Z` przez `DeliveryStatus::normalizeWithOverrides('polkurier', ...)`.
+- Phase 128 follow-up: rozmiar etykiety A4 vs A6 sterowany jest w panelu klienta polkurier.pl (Ustawienia konta → Preferencje etykiet), NIE przez API — operator ustawil A6.
 
 ## Deferred to Next Milestones
 

.paul/changelog/2026-05-14.md

@@ -26,3 +26,30 @@
 - `.paul/ROADMAP.md`
 - `.paul/phases/127-polkurier-integration-foundation/127-01-PLAN.md`
 - `.paul/phases/127-polkurier-integration-foundation/127-01-SUMMARY.md`
+
+## Co zrobiono (cd.)
+
+- [Phase 128, Plan 01] polkurier ShipmentService + TrackingService + UI prepare panel + delivery_status_mappings seed. polkurier zarejestrowany jako 4. provider w `ShipmentProviderRegistry` (obok allegro_wza/apaczka/inpost). Operator tworzy paczki z `/orders/{id}/shipment/prepare`, etykieta A6 generowana, cron tracking gotowy do mapowania O/P/A/WP/D/Z/W → created/confirmed/cancelled/in_transit/delivered/returned/problem.
+- Task 1: `PolkurierApiClient` rozszerzony z stubów Phase 127 do 7 metod (createShipment/getLabel/getStatus/cancelOrder/getAvailableCarriers/getInpostParcelMachines/getCourierPoints). Wspólny prywatny `call($apimetod, $data, $login, $token)` parsuje envelope `{status, response}`. Kontrakt zweryfikowany na oficjalnej dokumentacji PDF v1.11 (pobrana i zachowana w `.paul/phases/128-polkurier-shipment-service/polkurier-api-docs.txt`).
+- Task 2: `PolkurierShipmentService` (~520 LOC, implements ShipmentProviderInterface) + `PolkurierTrackingService` (~110 LOC, implements ShipmentTrackingInterface). `normalizeShipmentType()` mapuje legacy PACKAGE/BOX/PARCEL na lowercase zbiór polkuriera. `extractOrderNumber`/`extractTrackingNumber` priorytetują SDK Order entity (`number`, `waybills[0].number`).
+- Task 3: Wiring `routes/web.php` + `CronHandlerFactory` + `ShipmentController.prepare/create` (rozszerzony o `service_code`/`pickup_*` w form data). UI panel "polkurier" w `prepare.php` z dynamiczną listą usług + JS toggle. `DeliveryStatus::trackingUrl` fallback dla provider='polkurier'.
+- Task 4 (checkpoint live test #114/#115): 4 iteracje — ReferenceError w JS `clearHiddenFields` → uppercase `shipmenttype` → parsing `number` vs `orderno` → A4 vs A6 etykieta. Każda iteracja autopoprawiona w tej samej sesji APPLY.
+- Task 5: Migracja `20260514_000115_seed_polkurier_delivery_status_mappings.sql` z 7 wpisami z oficjalnej tabeli ORDER_STATUS PDF v1.11 (O/P/A/WP/D/Z/W). Idempotentna `ON DUPLICATE KEY UPDATE`.
+- Task 6: Aktualizacja `.paul/codebase/{architecture,db_schema,tech_changelog}.md` z sekcją Phase 128.
+- Scope removal vs PLAN: UI selektor punktów paczkomatowych usunięty (operator zgłosił duplikat z polem "Punkt odbioru" w sekcji Adres odbiorcy). `lookupPickupPoints` + AJAX route + JS handler usunięte. `getInpostParcelMachines`/`getCourierPoints` zostawione jako stuby na przyszłą fazę paczkomatów UI.
+- Decyzja: rozmiar etykiety A4/A6 sterowany w panelu klienta polkurier.pl, NIE przez API (zweryfikowane w PDF v1.11). Operator zmienia preferencje konta jednorazowo.
+
+## Zmienione pliki (cd.)
+
+- `src/Modules/Settings/PolkurierApiClient.php` (rozszerzenie z stubów do 7 metod)
+- `src/Modules/Shipments/PolkurierShipmentService.php` (nowy plik)
+- `src/Modules/Shipments/PolkurierTrackingService.php` (nowy plik)
+- `src/Modules/Shipments/DeliveryStatus.php` (fallback URL polkurier)
+- `src/Modules/Shipments/ShipmentController.php` (polkurierServices + service_code/pickup_*)
+- `src/Modules/Cron/CronHandlerFactory.php` (rejestracja PolkurierTrackingService)
+- `routes/web.php` (rejestracja PolkurierShipmentService w registry)
+- `resources/views/shipments/prepare.php` (panel polkurier + JS)
+- `database/migrations/20260514_000115_seed_polkurier_delivery_status_mappings.sql` (nowy plik)
+- `.paul/phases/128-polkurier-shipment-service/128-01-PLAN.md` (nowy plik)
+- `.paul/phases/128-polkurier-shipment-service/128-01-SUMMARY.md` (nowy plik)
+- `.paul/phases/128-polkurier-shipment-service/polkurier-api-docs.txt` (nowy plik — referencyjna doca z PDF v1.11)

.paul/codebase/architecture.md

@@ -378,6 +378,80 @@ tests/
 - `apaczka_integration_settings`, `ApaczkaShipmentService`, `ApaczkaTrackingService` — Apaczka netknieta, dziala rownolegle.
 - `delivery_status_mappings` — brak nowych wpisow `provider='polkurier'` (dolozone razem z tracking service w kolejnej fazie).
 
+## Phase 128 — polkurier ShipmentService + Tracking + UI prepare
+
+### PolkurierApiClient (Phase 128 extension)
+- 6 nowych metod publicznych obok zachowanego `testConnection()`:
+  - `getAvailableCarriers($login, $token)` → `apimetod=available_carriers`. Zwraca tablice przewoznikow z polami `servicecode`, `name`, `additional_data`, `foreign_shipments`. Konsumowane przez `PolkurierShipmentService::getDeliveryServices()`.
+  - `createShipment($login, $token, $payload)` → `apimetod=create_order`. Payload zgodny z oficjalna doca PDF v1.11 (zweryfikowany): `shipmenttype` (lowercase: box/envelope/palette/small_parcel/parcel_size_20), `courier` (servicecode), `description`, `sender`/`recipient` (company/person/street/housenumber/flatnumber/postcode/city/email/phone/country/point_id), `packs[]` (length/width/height/weight/amount/type), `pickup` (pickupdate/pickuptimefrom/pickuptimeto/nocourierorder), opcjonalnie `COD` i `insurance`.
+  - `getLabel($login, $token, $orderno)` → `apimetod=get_label`. **API przyjmuje WYLACZNIE `orderno: Array<String>`** (zweryfikowane w dokumentacji PDF). Rozmiar etykiety A4 vs A6 sterowany jest w panelu klienta polkurier.pl (Ustawienia konta → Preferencje etykiet), NIE przez API. Odpowiedz: `{file: <base64 PDF>}`.
+  - `getStatus($login, $token, $orderno)` → `apimetod=get_status`. Zwraca `{url, status_date, status, status_code, delivered_date}`. Kody w tabeli ORDER_STATUS (O/P/A/WP/D/Z/W).
+  - `cancelOrder($login, $token, $orderno)` → `apimetod=cancel_order`. Zwraca `{cancellation: true}`. Nie wywolywane przez nasz kod w Phase 128 (operator anuluje w panelu polkuriera).
+  - `getInpostParcelMachines` + `getCourierPoints` — stuby na przyszle rozszerzenie UI (panel paczkomatow). Aktualnie nie wykorzystywane w UI (operator wpisuje `receiver_point_id` recznie w sekcji Adres odbiorcy).
+- Wspolny prywatny `call($apimetod, $data, $login, $token): mixed` parsuje envelope `{status, response}`. Sukces -> zwraca tresc `response`. Blad -> rzuca `RuntimeException` z trescia z `response` (string albo zserializowany JSON dla tablic).
+
+### PolkurierShipmentService (`src/Modules/Shipments/PolkurierShipmentService.php`)
+- `final class implements ShipmentProviderInterface` (`code()='polkurier'`). DI: `PolkurierIntegrationRepository`, `PolkurierApiClient`, `ShipmentPackageRepository`, `CompanySettingsRepository`, `OrdersRepository`.
+- `getDeliveryServices()` cache'uje per-request liste z `available_carriers`, normalizuje do `[{id, name, supports_pickup_point, point_courier, foreign_shipments, raw}]`. Pole `supports_pickup_point` to heurystyka po `servicecode`/`name` (paczkomat/parcel/inpost/orlen/pocztex/kurier48/punkt).
+- `createShipment($orderId, $formData)` orchestruje pelny flow:
+  1. Walidacja: order istnieje, `service_code`/`delivery_method_id` niepusty, credentials aktywne, sender ma street/city/postcode + name|company.
+  2. Mapowanie `package_type` przez `normalizeShipmentType()` na zbior `[box, envelope, palette, small_parcel, parcel_size_20]` (lowercase, aliases dla PACKAGE/PARCEL/PACZKA/...).
+  3. Buduje `recipient` z `order_addresses` (delivery → fallback customer) + override z formularza. Splituje ulice na `street`/`housenumber`/`flatnumber` regexem (`Marszalkowska 10/5` → street="Marszalkowska", house="10", flat="5").
+  4. `pickup` default: `nextBusinessDay()` + 10:00-16:00, `nocourierorder=false` (override mozliwy przez formularz: `pickup_date`, `pickup_time_from`, `pickup_time_to`, `no_courier_order`).
+  5. `COD` jezeli `cod_amount > 0` (codtype='transfer', codbankaccount z `company_settings.bank_account` po stripowaniu nie-cyfr; throw `ShipmentException` jezeli pusty).
+  6. INSERT do `shipment_packages` (provider='polkurier', status='pending', payload_json z pelnym requestem).
+  7. Wywolanie `apiClient->createShipment()`. On success: parsing przez `extractOrderNumber()` (priorytet `number` → Order entity z SDK, fallback `orderno`/`order_no`/`order_number`/`order_id`/`id`, obsluga wrappera `{order:{...}}` i list) i `extractTrackingNumber()` (priorytet `waybills[0].number` → OrderWaybill entity, fallback top-level klucze).
+  8. UPDATE `shipment_packages`: `status='created'`, `shipment_id=command_id=orderno`, `tracking_number`.
+  9. Synchroniczna proba `downloadLabel()` (niekrytyczna — przy bledzie ignoruje, operator klikni "Pobierz" pozniej).
+  10. Diagnostyka: gdy `orderno=''` mimo `status=success`, zapisuje fragment surowej odpowiedzi (400 znakow) do `shipment_packages.error_message` dla debug.
+- `downloadLabel($packageId, $storagePath)`: wywoluje `get_label`, parsuje `extractLabelBase64()` (priorytet klucz `file` — zweryfikowane w SDK GetLabel.php, fallback `label`/`pdf`/`data`/`content`/`zpl`/`epl`), `base64_decode`, zapis do `storage/labels/polkurier_{packageId}_{orderno}.pdf`, UPDATE `label_path`.
+- `checkCreationStatus($packageId)`: graceful — przy bledzie API zwraca zachowany `tracking_number` z DB (cron sam zaktualizuje przez TrackingService).
+
+### PolkurierTrackingService (`src/Modules/Shipments/PolkurierTrackingService.php`)
+- `final class implements ShipmentTrackingInterface`. DI: `PolkurierApiClient`, `PolkurierIntegrationRepository`, `DeliveryStatusMappingRepository`.
+- `supports('polkurier')`. `getDeliveryStatus($package)` woła `get_status` po `shipment_id`/`command_id` (orderno), parsuje `status_code` z `response` (z obsluga listy w response[0]).
+- Mapowanie surowego `status_code` (O/P/A/WP/D/Z/W) → znormalizowany przez `DeliveryStatus::normalizeWithOverrides('polkurier', $rawStatus, $overrides)` z DB. Seed mapowan w migracji `20260514_000115`.
+- Odporny na bledy: brak credentials → `null` (skip), wyjatek API → `null`, brak `status_code` → `null`. Cron nie crashuje.
+
+### DeliveryStatus::trackingUrl (Phase 128 patch)
+- Carrier_id routing (DPD/UPS/GLS/InPost/Pocztex/...) dziala dla polkuriera automatycznie przez istniejacy `matchCarrierByName($encoded, $carrier)` (carrier_id ustawiany na servicecode z polkuriera, np. "INPOST", "DPD" — pasuje do substring matchu).
+- Fallback dla provider='polkurier' bez carrier matchu: `https://polkurier.pl/sledz-paczke/<tracking>`.
+
+### Wiring
+- `routes/web.php`: `new PolkurierShipmentService(...)` zarejestrowany w `ShipmentProviderRegistry` obok Apaczki/InPost/AllegroWZA.
+- `src/Modules/Cron/CronHandlerFactory.php`: `new PolkurierTrackingService(...)` w `ShipmentTrackingRegistry` w `shipment_tracking_sync` handler.
+- `src/Modules/Shipments/ShipmentController.php`: `prepare()` fetchuje `polkurierServices` przez registry i przekazuje do widoku. `create()` rozszerzony o `service_code`/`pickup_date`/`pickup_time_from`/`pickup_time_to` przekazywane do `createShipment()`.
+
+### UI prepare panel (`resources/views/shipments/prepare.php`)
+- Opcja "polkurier" w dropdownie `#shipment-carrier-select` (obok Allegro/InPost/Apaczka).
+- `<div id="shipment-polkurier-panel">` z dynamicznym `<select id="shipment-polkurier-select">` (lista uslug z `available_carriers`).
+- `<input type="hidden" name="service_code">` synchronizowany z polkurier select przez `syncPolkurierFields()`.
+- Brak dedykowanego selektora punktu odbioru — operator wpisuje `receiver_point_id` w istniejacy text input w sekcji Adres odbiorcy (np. `POP-RZE54`). Format string `POP-RZE54 | Lukasiewicza 78, 35-604 Rzeszow` z importu zamowienia nie jest parsowany — operator skraca recznie.
+- JS toggle widocznosci paneli rozszerzony o polkurier; `clearHiddenFields()` czysci `service_code`; `showPanel('polkurier')` ustawia `provider_code='polkurier'`.
+
+### Rozmiar etykiety A4 vs A6
+- API polkurier nie udostepnia parametru sterowania rozmiarem etykiety w `get_label` ani `create_order` (zweryfikowane w PDF v1.11).
+- Domyslny rozmiar ustawiany jest w **panelu klienta polkurier.pl → Ustawienia konta → Preferencje etykiet** (per-konto, globalnie dla wszystkich `get_label` calli).
+- `polkurier_integration_settings.default_label_format` (PDF/ZPL/EPL) sluzy tylko typowi pliku, NIE rozmiarowi.
+
+### Seed delivery_status_mappings (`20260514_000115_seed_polkurier_delivery_status_mappings.sql`)
+- 7 wpisow `provider='polkurier'` (kody z oficjalnej tabeli ORDER_STATUS w PDF v1.11):
+  - `O` → `created` (Oczekuje na platnosc)
+  - `P` → `confirmed` (Potwierdzone, list wygenerowany)
+  - `A` → `cancelled` (Anulowane)
+  - `WP` → `in_transit` (W przewozie)
+  - `D` → `delivered` (Dostarczona)
+  - `Z` → `returned` (Zwrot do nadawcy)
+  - `W` → `problem` (Wyjatek)
+- Idempotentne: `ON DUPLICATE KEY UPDATE normalized_status / description / updated_at`.
+
+### Boundaries / co NIE zostalo zmienione
+- Apaczka (`ApaczkaShipmentService`, `ApaczkaTrackingService`, `apaczka_integration_settings`) niezalezna, dziala obok polkuriera.
+- `ShipmentProviderInterface` i `ShipmentTrackingInterface` kontrakty niezmienione.
+- `getInpostParcelMachines`/`getCourierPoints` w API client zaimplementowane ale nieuzywane przez UI w Phase 128 (operator wpisuje punkt recznie).
+- `cancelOrder` zaimplementowane w API client ale nie wywolywane z UI/cron — operator anuluje w panelu polkuriera.
+- Brak presetow przesylek dla polkuriera (`shipment_presets.provider_code='polkurier'`) — kolejna faza.
+
 ## Phase 121 - SMSPLANET Conversation + Notifications
 
 ### SmsConversationService (`src/Modules/Sms/SmsConversationService.php`)

.paul/codebase/db_schema.md

@@ -459,6 +459,18 @@ Indexes: `shipment_packages_order_idx`, `shipment_packages_status_idx`, `shipmen
 
 UNIQUE: `(provider, raw_status)`
 
+**Seedowane mapowania:**
+- `provider='inpost'`, `provider='apaczka'`, `provider='allegro_wza'` — w `DeliveryStatus.php` (hardcoded fallback przez `DeliveryStatus::normalize($provider, $rawStatus)`).
+- `provider='polkurier'` (Phase 128, migracja `20260514_000115_seed_polkurier_delivery_status_mappings.sql`):
+  - `O` → `created` (Oczekuje na platnosc)
+  - `P` → `confirmed` (Potwierdzone, list wygenerowany)
+  - `A` → `cancelled` (Anulowane)
+  - `WP` → `in_transit` (W przewozie)
+  - `D` → `delivered` (Dostarczona)
+  - `Z` → `returned` (Zwrot do nadawcy)
+  - `W` → `problem` (Wyjatek)
+  - Kody z oficjalnej tabeli `ORDER_STATUS` w dokumentacji API polkurier v1.11 (marzec 2026).
+
 ---
 
 ## Integrations

.paul/codebase/tech_changelog.md

@@ -1,5 +1,41 @@
 # Technical Changelog
 
+## 2026-05-14 - Phase 128 Plan 01: polkurier ShipmentService + Tracking + UI prepare
+
+**Co zrobiono:**
+- `src/Modules/Settings/PolkurierApiClient.php` — pelen kontrakt API: `createShipment` (`apimetod=create_order`), `getLabel` (`get_label`), `getStatus` (`get_status`), `cancelOrder` (`cancel_order`), `getAvailableCarriers` (`available_carriers`), `getInpostParcelMachines` (`inpost_parcel_machines`), `getCourierPoints` (`get_courier_point`). Wspolny prywatny `call($apimetod, $data, $login, $token): mixed` parsuje envelope `{status, response}`; sukces -> zwraca `response`, blad -> rzuca `RuntimeException` z trescia z `response` (string albo zserializowany JSON dla tablic). Kontrakt zweryfikowany na oficjalnej dokumentacji PDF v1.11 (marzec 2026) — pobrana z `https://www.polkurier.pl/files/download/api_documentation_pdf`, zachowana w `.paul/phases/128-polkurier-shipment-service/polkurier-api-docs.txt`.
+- `src/Modules/Shipments/PolkurierShipmentService.php` — `final class implements ShipmentProviderInterface` (`code()='polkurier'`). Pelen flow `createShipment($orderId, $formData)`: walidacja credentials/sender, `normalizeShipmentType()` mapuje `package_type` (PACKAGE/BOX/...) na zbior polkuriera `[box,envelope,palette,small_parcel,parcel_size_20]` (lowercase wymagane przez API — odkryte podczas live testu), `splitStreetAndNumber()` rozdziela ulice regexem na `street`/`housenumber`/`flatnumber`, `buildRecipient` z payload `order_addresses` + override z formularza, `buildPickup` z domyslnym `nextBusinessDay()` + 10:00-16:00, `COD` z bank account z `company_settings`. Po sukcesie API: `extractOrderNumber` (priorytet `number` z SDK Order entity), `extractTrackingNumber` (priorytet `waybills[0].number` z OrderWaybill entity), synchroniczna proba `downloadLabel`. Diagnostyka: gdy `orderno=''`, zapisuje fragment surowej odpowiedzi do `shipment_packages.error_message`.
+- `src/Modules/Shipments/PolkurierTrackingService.php` — `final class implements ShipmentTrackingInterface`. `getDeliveryStatus($package)` woła `get_status`, parsuje `status_code`, mapuje przez `DeliveryStatus::normalizeWithOverrides('polkurier', ...)` z `delivery_status_mappings`. Graceful: null przy braku credentials/wyjatku API/braku `status_code`.
+- `src/Modules/Shipments/DeliveryStatus.php` — fallback URL sledzenia dla `provider='polkurier'`: `https://polkurier.pl/sledz-paczke/<tracking>`. Carrier_id routing (DPD/UPS/GLS/InPost/Pocztex) dziala automatycznie przez istniejacy `matchCarrierByName()` (carrier_id ustawiany na servicecode z polkuriera, np. "INPOST" lub "DPD" — substring match).
+- `routes/web.php` — `new PolkurierShipmentService(...)` w `ShipmentProviderRegistry`. Import `App\Modules\Settings\PolkurierApiClient` + `App\Modules\Shipments\PolkurierShipmentService`.
+- `src/Modules/Cron/CronHandlerFactory.php` — `new PolkurierTrackingService(new PolkurierApiClient(), new PolkurierIntegrationRepository($this->db, $this->integrationSecret), new DeliveryStatusMappingRepository($this->db))` w `ShipmentTrackingRegistry` w handlerze `shipment_tracking_sync`.
+- `src/Modules/Shipments/ShipmentController.php` — `prepare()` fetchuje `polkurierServices` przez registry i przekazuje do widoku. `create()` rozszerzony o pola `service_code`/`pickup_date`/`pickup_time_from`/`pickup_time_to` przekazywane do `createShipment()`.
+- `resources/views/shipments/prepare.php` — opcja "polkurier" w `#shipment-carrier-select`, panel `#shipment-polkurier-panel` z `<select id="shipment-polkurier-select">` (lista uslug z `available_carriers`), hidden `name="service_code"`, JS toggle (`showPanel`, `syncPolkurierFields`). Brak dedykowanego selektora punktu odbioru — operator wpisuje `receiver_point_id` w istniejacym text inpucie w sekcji Adres odbiorcy (np. `POP-RZE54`).
+- Nowa migracja `database/migrations/20260514_000115_seed_polkurier_delivery_status_mappings.sql` — 7 wpisow `provider='polkurier'`: `O`→`created`, `P`→`confirmed`, `A`→`cancelled`, `WP`→`in_transit`, `D`→`delivered`, `Z`→`returned`, `W`→`problem`. Idempotentne (`ON DUPLICATE KEY UPDATE`). Kody z oficjalnej tabeli ORDER_STATUS PDF v1.11.
+- `.paul/codebase/architecture.md` + `db_schema.md` — opisy fazy 128.
+
+**Dlaczego:**
+- Phase 127 dostarczyl fundament (settings + test_auth_api). Bez ShipmentService polkurier byl tylko `wystawiony w hubie integracji ale niedzialajacy`. Operator chcial realnie nadawac paczki przez polkurier obok Apaczki — szczegolnie dla DPD/UPS/GLS/InPost gdzie polkurier oferuje lepsze ceny.
+- Pelny zakres (ShipmentService + TrackingService + UI prepare + delivery_status_mappings) w jednej fazie zgodnie z decyzja operatora z planu (clarifications, `delegation: off`, `autonomous: false` z checkpointem live testu na #114/#115).
+
+**Live test iteracje (zarejestrowane podczas APPLY):**
+1. Pierwszy submit polkurier → "Blad tworzenia przesylki: Nie podano uslugi Apaczka." Przyczyna: `ReferenceError` na zmiennej `polkurierPointIdInput` (pozostalej po usunieciu duplikatu selektora punktu) w `clearHiddenFields()` → handler `carrierSelect.change` crashowal przed `showPanel()`, `provider_code` zostawal na PHP-renderowanej wartosci `apaczka`. Fix: usuniecie martwej referencji.
+2. Drugi submit → "Blad tworzenia przesylki: polkurier create_order: Typ paczki musi przyjmowac jeden z parametrow ze zbioru [box, envelope, palette, small_parcel, parcel_size_20]". Przyczyna: wysylanie `BOX` uppercase. Fix: `normalizeShipmentType()` z lowercase + aliasami.
+3. Trzeci submit → utworzona w polkurier, ale w orderPRO `status=pending` (brak orderno w parsing). Przyczyna: shape odpowiedzi `create_order` zwraca `Order` entity z polem `number` (nie `orderno`). Fix: `extractOrderNumber` z priorytetem `number` + fallback list + obsluga wrappera `{order:{...}}`. Etykieta poprawnie parsowana z pola `file` (response GetLabel.php).
+4. Czwarty test → etykieta A4 zamiast A6. Iteracja w bogus parametry (`format`/`label_size`/`paper_size`) wyslane do `get_label` — bez efektu, bo API ignoruje. Pobranie oficjalnej dokumentacji PDF potwierdzilo: `get_label` przyjmuje WYLACZNIE `orderno`. Rozmiar A4 vs A6 sterowany jest w panelu klienta polkurier.pl (Ustawienia konta → Preferencje etykiet), NIE przez API. Operator zmienil w panelu — etykieta A6 OK.
+
+**Deviation vs PLAN:**
+- Plan deklarowal `delegation: off` — wykonane inline. Tasks 1-3 napisane przez orchestrator, checkpoint i Task 5/6 inline. Bez sub-agentow ze wzgledu na potrzebe szybkich iteracji po live test feedback (4 iteracje przed sukcesem) — spawn agentow zdublowalby koszt research z PDF.
+- Plan deklarowal AJAX endpoint `/shipments/polkurier/points` + UI selector punktow paczkomatowych (Task 3 action). USUNIETY po feedback operatora — istnieje juz pole "Punkt odbioru" w sekcji Adres odbiorcy, operator wpisuje ID recznie (np. `POP-RZE54`). Usuniety: `PolkurierShipmentService::lookupPickupPoints()`, `ShipmentController::polkurierPoints()`, route, JS handler.
+- AC-3 (TrackingService cron) dostarczony, ale niezweryfikowany na zywej bazie podczas APPLY (operator anulowal paczki w panelu polkurier po teście — cron tracking nie mial co pingowac). Dziala defensywnie (graceful null przy bledach), pierwszy realny passthrough nastapi przy nastepnej zywej paczce.
+- Plan zakladal seedowanie mapowan po zaobserwowaniu realnych statusow w live tescie. Seed wykonany bazujac na oficjalnej tabeli ORDER_STATUS z PDF v1.11 (kody O/P/A/WP/D/Z/W) zamiast obserwacji — bezpieczniejsze i wyczerpujace.
+- AC-1 wzmiankowal getAvailableCarriers/getParcelMachines/getPostOffices. `getInpostParcelMachines` i `getCourierPoints` zaimplementowane jako stuby na przyszle rozszerzenie UI, ale nie uzywane przez aktualny UI (operator wpisuje punkt recznie). `getPostOffices` POMINIETY — brak dedykowanej metody w SDK (jest tylko `inpost_parcel_machines` per courier, `pocztex_post_offices`, `kurier48_post_offices` — zlozenie tego w UI panel paczkomatow odlozone na kolejna faze).
+
+**Follow-up:**
+- Operator musi uruchomic migracje gdy XAMPP MySQL online: `php bin/migrate.php` (utworzy 7 wpisow `provider='polkurier'`).
+- Po pierwszej zywej paczce w `in_transit` — weryfikacja crona `shipment_tracking_sync` (1x ping API polkuriera, zapis `delivery_status` + `delivery_status_raw` w `shipment_packages`).
+- Kolejne fazy v3.7: paczkomaty UI panel (`InpostParcelMachines`/`PocztexPostOffices`/`Kurier48PostOffices`), presety przesylek z `provider_code='polkurier'`, `OrderValuationV2` (wycena przed nadaniem).
+
 ## 2026-05-14 - Phase 127 Plan 01: polkurier Integration Foundation
 
 **Co zrobiono:**

.paul/phases/128-polkurier-shipment-service/128-01-PLAN.md

@@ -0,0 +1,392 @@
+---
+phase: 128-polkurier-shipment-service
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/Modules/Settings/PolkurierApiClient.php
+  - src/Modules/Shipments/PolkurierShipmentService.php
+  - src/Modules/Shipments/PolkurierTrackingService.php
+  - src/Modules/Shipments/ShipmentController.php
+  - src/Modules/Shipments/DeliveryStatus.php
+  - src/Modules/Cron/CronHandlerFactory.php
+  - routes/web.php
+  - resources/views/shipments/prepare.php
+  - database/migrations/20260514_000115_seed_polkurier_delivery_status_mappings.sql
+  - .paul/codebase/architecture.md
+  - .paul/codebase/db_schema.md
+  - .paul/codebase/tech_changelog.md
+autonomous: false
+delegation: off
+---
+
+<objective>
+## Goal
+Dostarczyc pelna integracje wysylkowa polkurier.pl: tworzenie paczek (createOrder), pobieranie etykiet (getLabel), tracking statusow przesylek (getStatus) oraz UI do nadawania paczek w `/orders/{id}/shipment/prepare` z dynamiczna lista przewoznikow z polkuriera i obsluga punktow odbioru (Paczkomaty InPost, ORLEN, Pocztex, Kurier48). Weryfikacja na zywych zamowieniach #114 i #115 z manualnym anulowaniem po teście.
+
+## Purpose
+Phase 127 dostarczyl fundament (settings + test_auth_api). Bez ShipmentService polkurier jest "wystawiony w hubie integracji ale niedzialajacy". Operator chce realnie nadawac paczki przez polkurier obok Apaczki — wspolny use case (DPD, UPS, GLS, InPost) z lepszymi cenami.
+
+## Output
+- 2 nowe klasy w `src/Modules/Shipments/` (`PolkurierShipmentService`, `PolkurierTrackingService`) implementujace odpowiednio `ShipmentProviderInterface` i `ShipmentTrackingInterface`
+- Rozszerzony `PolkurierApiClient` z 6 nowymi metodami API
+- Nowy panel "polkurier" w `prepare.php` + przelacznik JS
+- Migracja seedujaca `delivery_status_mappings` (provider='polkurier')
+- Architektura/schema/changelog zaktualizowane
+- 2 paczki utworzone na zywym koncie polkurier (#114 i #115), zweryfikowane, recznie anulowane przez operatora
+</objective>
+
+<context>
+
+<clarifications>
+- **Zakres fazy** — Co dostarczamy w Phase 128?
+  → Odpowiedz: Pelny zakres: ShipmentService + TrackingService + UI prepare + delivery_status_mappings (jedna duza faza zamiast dwoch).
+- **Uslugi UI** — Jak prezentujemy uslugi polkurier w UI prepare?
+  → Odpowiedz: Dynamiczna lista z API polkuriera (`get_available_carriers` lub odpowiednia metoda) — analog `ApaczkaApiClient::getServiceStructure`.
+- **Paczkomaty** — Czy obslugujemy paczkomaty/punkty odbioru w Phase 128?
+  → Odpowiedz: Pelne wsparcie wszystkich punktow (InpostParcelMachines, PocztexPostOffices, Kurier48PostOffices, ewentualnie ORLEN).
+- **Tryb testu** — Jak testujemy na #114/#115?
+  → Odpowiedz: Realny createOrder na zywym koncie + manualny cancelOrder po weryfikacji przez operatora w panelu polkurier (live test, ale bez wysylki).
+</clarifications>
+
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+@.paul/codebase/architecture.md
+@.paul/codebase/db_schema.md
+
+## Prior Work
+@.paul/phases/127-polkurier-integration-foundation/127-01-SUMMARY.md
+
+## Source Files (wzorzec Apaczka)
+@src/Modules/Shipments/ApaczkaShipmentService.php
+@src/Modules/Shipments/ApaczkaTrackingService.php
+@src/Modules/Settings/ApaczkaApiClient.php
+@src/Modules/Shipments/ShipmentProviderInterface.php
+@src/Modules/Shipments/ShipmentTrackingInterface.php
+@src/Modules/Shipments/ShipmentProviderRegistry.php
+@src/Modules/Settings/PolkurierApiClient.php
+@src/Modules/Settings/PolkurierIntegrationRepository.php
+@src/Modules/Shipments/ShipmentController.php
+@src/Modules/Cron/CronHandlerFactory.php
+@resources/views/shipments/prepare.php
+@routes/web.php
+
+## External Reference
+- Oficjalne polkurier SDK: https://github.com/Polkurier/polkurier-sdk (zweryfikowany kontrakt API w Phase 127)
+- Klucze apimetod w SDK: `test_auth_api`, `new_order`, `get_label`, `get_status`, `cancel_order`, `get_available_carriers`, `get_parcel_machines`, `get_post_offices`, `get_carrier_info` (do potwierdzenia per SDK)
+</context>
+
+<acceptance_criteria>
+
+## AC-1: PolkurierApiClient — pelny kontrakt API
+```gherkin
+Given globalna konfiguracja polkurier jest aktywna i token zwery (Phase 127)
+When backend wywoluje `PolkurierApiClient::getAvailableCarriers()` z poprawnymi credentials
+Then klient zwraca tablice przewoznikow (DPD/UPS/GLS/InPost/Pocztex…) z polami: `carrier_id`, `name`, `service_code`, `supports_pickup_point` (bool), `weight_limits`, `cod_supported`
+And `createShipment($payload)` zwraca tablice `{order_id: string, tracking_number: string, label_url: ?string, raw: array}` przy `status='success'`
+And `getLabel($orderId, $format)` zwraca binarna zawartosc etykiety (PDF/ZPL/EPL zaleznie od `default_label_format`)
+And `getStatus($orderId)` zwraca tablice `{status_code, status_name, status_date}`
+And `cancelOrder($orderId)` zwraca `{ok: bool, message: string}`
+And kazda metoda przy `status != 'success'` rzuca `RuntimeException` z trescia z pola `response`
+```
+
+## AC-2: PolkurierShipmentService implementuje ShipmentProviderInterface
+```gherkin
+Given `PolkurierShipmentService` jest zarejestrowany w `ShipmentProviderRegistry` jako `code()='polkurier'`
+When `createShipment(int $orderId, array $formData)` jest wywolane z danymi zamowienia #114 lub #115
+Then service buduje payload polkurier (sender z `company_settings`, receiver z order_addresses, paczka z formData), woła `PolkurierApiClient::createShipment()`, zapisuje wynik do `shipment_packages` (provider='polkurier', tracking_number, label_path po pobraniu, payload_json)
+And `downloadLabel($packageId, $storagePath)` pobiera plik etykiety i aktualizuje `shipment_packages.label_path`
+And `checkCreationStatus($packageId)` zwraca aktualny stan z `shipment_packages` (sync vs `getStatus()` API)
+And `getDeliveryServices()` zwraca cache'owana liste przewoznikow z `getAvailableCarriers()` (per-request)
+```
+
+## AC-3: PolkurierTrackingService cron tracking
+```gherkin
+Given paczka z `provider='polkurier'` i `tracking_number` istnieje w `shipment_packages`
+When `ShipmentTrackingHandler` (cron) wywoluje `PolkurierTrackingService::getDeliveryStatus($package)`
+Then service woła `PolkurierApiClient::getStatus()`, parsuje surowy status i mapuje przez `delivery_status_mappings(provider='polkurier')` na znormalizowany status z `delivery_statuses`
+And zwraca `{status: <normalized>, status_raw: <polkurier_code>, description: <polkurier_label>}`
+And `supports('polkurier')` zwraca true
+```
+
+## AC-4: UI prepare.php panel polkurier
+```gherkin
+Given operator wszedl na `/orders/115/shipment/prepare`
+When wybiera "polkurier" z dropdowna przewoznika
+Then JS pokazuje panel `#shipment-polkurier-panel` z dynamicznym selectem uslug (zaladowanym z `getAvailableCarriers`)
+And dla uslug `supports_pickup_point=true` pojawia sie selektor punktu odbioru z listą punktów odpowiedniego typu (InPost/Pocztex/Kurier48/ORLEN)
+And ukryty input `provider_code` ustawia sie na `polkurier`
+And submit formularza tworzy paczke przez `ShipmentController::store()` -> `ShipmentProviderRegistry::get('polkurier')->createShipment()`
+```
+
+## AC-5: delivery_status_mappings + /settings/delivery-statuses
+```gherkin
+Given migracja `20260514_000115_seed_polkurier_delivery_status_mappings.sql` wykonana
+When operator otwiera `/settings/delivery-statuses` (tab 'mapping')
+Then widoczne sa wpisy `provider='polkurier'` z surowymi statusami polkuriera mapowanymi na znormalizowane statusy z `delivery_statuses` (np. `nowa_paczka` -> `registered`, `w_doreczeniu` -> `out_for_delivery`, `doreczone` -> `delivered`, `anulowane` -> `cancelled`)
+And `DeliveryStatus::trackingUrl('polkurier', $tracking, $carrierId)` zwraca poprawny link sledzenia (URL polkuriera lub bezposrednio przewoznika)
+```
+
+## AC-6: Live test na zamowieniach #114 i #115
+```gherkin
+Given operator ma aktywne konto polkurier (Phase 127 test "Autoryzacja: 1")
+When operator nadaje paczki na #114 i #115 przez nowy panel UI
+Then dla obu zamowien `shipment_packages` zawiera wiersz `provider='polkurier'`, `status='created'`, niepusty `tracking_number`, sciezke `label_path` do pobranej etykiety
+And operator widzi etykiety jako PDF w `/orders/{id}` zakladka Przesylki
+And operator recznie anuluje obie paczki w panelu polkurier.pl po weryfikacji (poza zakresem kodu — manualna akcja w UI polkuriera)
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: PolkurierApiClient — implementacja pelnego kontraktu API</name>
+  <files>src/Modules/Settings/PolkurierApiClient.php</files>
+  <action>
+    Zastapic stuby `createShipment/getLabel/getStatus/cancelOrder` realnymi implementacjami i dodac `getAvailableCarriers`, `getParcelMachines`, `getPostOffices`.
+
+    Wspolny helper `private function call(string $apimetod, array $data, string $login, string $apiToken): array`:
+      - Buduje payload `{authorization: {login, token}, apimetod, data}`.
+      - Wykorzystuje istniejacy `postJson()` (Phase 127).
+      - Parsuje envelope: jezeli `status === 'success'` zwraca `$decoded['response']` (array). W przeciwnym razie rzuca `RuntimeException` z trescia `response` (string albo zserializowany JSON).
+      - PHP 8.5: NIE wywolywac `curl_close()`.
+
+    Metody publiczne:
+      - `createShipment(string $login, string $apiToken, array $payload): array` — apimetod `new_order` (sprawdzic dokladna nazwe w SDK polkurier-sdk/src/Api). Zwraca `{order_id, tracking_number, raw}`.
+      - `getLabel(string $login, string $apiToken, string $orderId, string $format): string` — apimetod `get_label`, format=PDF/ZPL/EPL. Zwraca surowa zawartosc base64-decoded jezeli polkurier zwraca base64; w przeciwnym razie binarny stream. Sprawdzic odpowiedz API.
+      - `getStatus(string $login, string $apiToken, string $orderId): array` — apimetod `get_status`. Zwraca `{status_code, status_name, status_date, raw}`.
+      - `cancelOrder(string $login, string $apiToken, string $orderId): array` — apimetod `cancel_order`. (NIE bedzie wywolywana w Phase 128 — operator anuluje w UI polkuriera, ale metoda dostepna dla przyszlych planow.)
+      - `getAvailableCarriers(string $login, string $apiToken): array` — apimetod `get_available_carriers` (potwierdzic w SDK; mozliwe alternatywy: `get_carriers`, `get_services`). Zwraca liste przewoznikow.
+      - `getParcelMachines(string $login, string $apiToken, string $type, ?string $postalCode = null): array` — apimetod `get_parcel_machines`. type=InPost/Pocztex/Kurier48/ORLEN.
+      - `getPostOffices(string $login, string $apiToken, string $type): array` — apimetod `get_post_offices` (jezeli polkurier rozdziela).
+
+    UWAGA: dokladne nazwy `apimetod` zweryfikowac wzgledem `polkurier-sdk` (https://github.com/Polkurier/polkurier-sdk) — pliki `src/Api/*Api.php`. Jezeli nazwa rozna od zakladanej, dostosowac stale prywatne (`private const APIMETOD_NEW_ORDER = '...'` itp.).
+
+    Avoid: hardcodowane mapowanie statusow (zostawiamy `DeliveryStatusMappingRepository`), zmiany w `testConnection()` (dziala od Phase 127), wprowadzania `Content-Type: application/json; charset=UTF-8` (polkurier odrzuca — zachowac dokladnie `application/json`).
+  </action>
+  <verify>
+    1. `php -l src/Modules/Settings/PolkurierApiClient.php` (no syntax errors).
+    2. Operator wywoluje przyszly smoke test: `php bin/smoke-polkurier.php` (skrypt z Task 4) — pierwszy crash wskaze brakujace pole.
+    3. Rzut `RuntimeException` zawiera tresc z pola `response` (nie `status: error`).
+  </verify>
+  <done>AC-1 satisfied: wszystkie 7 metod publicznych zaimplementowane wzorem `testConnection()`; envelope `{status, response}` parsowany jednolicie; bledy rzucane z trescia z `response`.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: PolkurierShipmentService + PolkurierTrackingService</name>
+  <files>src/Modules/Shipments/PolkurierShipmentService.php, src/Modules/Shipments/PolkurierTrackingService.php, src/Modules/Shipments/DeliveryStatus.php</files>
+  <action>
+    **PolkurierShipmentService** — `final class implements ShipmentProviderInterface`, wzorzec `ApaczkaShipmentService` (1044 LOC, ale polkurier prostszy — ~500-700 LOC):
+
+    Konstruktor (manualny DI, mirror Apaczki):
+      - `PolkurierIntegrationRepository $integrationRepository`
+      - `PolkurierApiClient $apiClient`
+      - `ShipmentPackageRepository $packages`
+      - `CompanySettingsRepository $companySettings`
+      - `OrdersRepository $ordersRepository`
+
+    Metody:
+      - `code(): string` -> `'polkurier'`.
+      - `getDeliveryServices(): array` — `getCredentials()` -> `$apiClient->getAvailableCarriers()`. Cache per-request (`private ?array $servicesCache = null`).
+      - `createShipment(int $orderId, array $formData): array`:
+          1. `findDetails($orderId)` z OrdersRepository; throw `ShipmentException` gdy null.
+          2. `requireCredentials()` -> `[$login, $token]` z `PolkurierIntegrationRepository::getCredentials()`; throw `IntegrationConfigException` gdy null.
+          3. Sender z `CompanySettingsRepository::getSenderAddress()` + walidacja (`validateSenderAddress`).
+          4. Receiver z `order_addresses` (delivery type), normalizacja telefonu/postal_code.
+          5. Wybor uslugi z `$formData['service_code']` lub `$formData['carrier_id']`.
+          6. Wymiary/waga z formData (z domyslnymi z `company_settings.default_package_*`).
+          7. Punkt odbioru: jezeli `$formData['receiver_point_id']` niepuste -> wstawiamy w payload polkuriera (klucz zaleznie od SDK).
+          8. COD/insurance z formData.
+          9. `$apiClient->createShipment($login, $token, $payload)` -> `{order_id, tracking_number, ...}`.
+          10. `$packages->insert([...])` z `provider='polkurier'`, `command_id=order_id`, `tracking_number`, `status='created'`, `payload_json=zserializowany_payload`.
+          11. Synchroniczne pobranie etykiety przez `downloadLabel($packageId, $storagePath)` — analog Apaczki, ktora pobiera label do `storage/labels/`.
+          12. Zwroc `['package_id' => ..., 'tracking_number' => ..., 'label_path' => ...]`.
+      - `checkCreationStatus(int $packageId): array` — fetch z `shipment_packages`; jezeli `status='draft'` -> pingnij `getStatus()` API i zaktualizuj.
+      - `downloadLabel(int $packageId, string $storagePath): array` — `$apiClient->getLabel($login, $token, $orderId, $package['label_format'] ?? 'PDF')`; zapisz do `$storagePath/polkurier_{packageId}.pdf` (lub `.zpl`); update `shipment_packages.label_path`.
+
+    **PolkurierTrackingService** — `final class implements ShipmentTrackingInterface`:
+      - `supports(string $provider): bool` -> `strtolower($provider) === 'polkurier'`.
+      - `getDeliveryStatus(array $package): ?array`:
+          1. `requireCredentials()`; zwroc null gdy konfiguracja nieaktywna (cron nie powinien rzucac, tylko skipowac).
+          2. `$apiClient->getStatus($login, $token, $package['command_id'])`.
+          3. Mapuj `status_code` przez `DeliveryStatusMappingRepository::findNormalized('polkurier', $rawStatus)`.
+          4. Fallback `unknown` gdy brak mapowania (analog Apaczki).
+          5. Zwroc `['status' => $normalized, 'status_raw' => $rawStatus, 'description' => $statusName]`.
+
+    **DeliveryStatus.php** — dolozyc obsluge providera `polkurier` w `trackingUrl(string $provider, string $tracking, string $carrierId): string`:
+      - Polkurier deleguje do przewoznika docelowego — `carrierId` mowi nam ktory. Fallback URL `https://polkurier.pl/sledzenie/<tracking>` (jezeli polkurier ma taki) lub URL przewoznika docelowego z istniejacych branch-ow (`inpost`, `dpd`, etc.). MVP: zwroc URL bazowy polkurier + tracking_number.
+
+    Avoid:
+      - Hardcodowania URL tracking polkuriera bez weryfikacji (sprawdzic w panelu polkurier lub SDK).
+      - Pobierania etykiety w osobnym requeście jezeli polkurier zwraca `label_base64` w odpowiedzi createShipment (parsowac i zapisywac od razu).
+      - Throwowania w `PolkurierTrackingService::getDeliveryStatus` przy braku credentials — cron musi byc odporny.
+  </action>
+  <verify>
+    1. `php -l src/Modules/Shipments/PolkurierShipmentService.php` i `PolkurierTrackingService.php`.
+    2. Manualnie: po Task 3 wejdz na `/orders/114/shipment/prepare`, wybierz polkurier — dropdown zwraca przewoznikow z API.
+  </verify>
+  <done>AC-2 i AC-3 satisfied: oba serwisy implementuja interfejsy, integruja z `PolkurierApiClient`, `ShipmentPackageRepository` i `DeliveryStatusMappingRepository`. Kontrakt Phase 127 (single global config, `is_active=1` guard) zachowany.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Wiring + UI prepare.php panel polkurier</name>
+  <files>routes/web.php, src/Modules/Shipments/ShipmentController.php, src/Modules/Cron/CronHandlerFactory.php, resources/views/shipments/prepare.php</files>
+  <action>
+    **routes/web.php**:
+      - W `$shipmentProviderRegistry = new ShipmentProviderRegistry([...])` (linia ~474) dolozyc `new PolkurierShipmentService($polkurierIntegrationRepository, new PolkurierApiClient(), $shipmentPackageRepository, $companySettingsRepository, new OrdersRepository(...))`.
+      - Dolozyc `use App\Modules\Shipments\PolkurierShipmentService;` w nagłowku.
+
+    **CronHandlerFactory.php** (linia ~166-169):
+      - W tablicy trackerow dolozyc `new PolkurierTrackingService($polkurierIntegrationRepository, $polkurierApiClient, $deliveryStatusMappingRepository)`.
+      - Dolozyc `use App\Modules\Shipments\PolkurierTrackingService;` i `use App\Modules\Settings\PolkurierIntegrationRepository;`/`PolkurierApiClient;`.
+
+    **ShipmentController.php**:
+      - Wstrzyknac `PolkurierShipmentService $polkurierService` (lub uzywac z registry).
+      - W `prepare()` przekazac do widoku `$polkurierServices = $polkurierService->getDeliveryServices()` (try/catch — empty array on failure).
+
+    **resources/views/shipments/prepare.php** — wzorzec panelu Apaczki (linie 172-216):
+      - Dolozyc `<option value="polkurier">polkurier</option>` do `#carrierSelect` (linia ~103).
+      - Dolozyc panel `<div id="shipment-polkurier-panel">` z:
+          - `<select id="shipment-polkurier-service-select">` wypelniony `$polkurierServices` (carrier_id, name).
+          - Conditional pickup point picker (`<select id="shipment-polkurier-point-select">`) widoczny gdy wybrana usluga ma `supports_pickup_point=true`. Lista punktow ladowana AJAX-em z nowego endpointu `/shipments/polkurier/points?type=InPost&postal=XX-XXX` (dodac route + metoda w `ShipmentController`).
+          - Hidden input `name="service_code"` aktualizowany przez JS na podstawie selecta.
+      - JS (linie ~580-650): dodac `polkurierSelect`/`polkurierPanel`/`polkurierPointSelect`; toggle widocznosci paneli; ustaw `providerInput.value = 'polkurier'` gdy carrier='polkurier'.
+
+    Avoid:
+      - Powielania logiki Apaczki — uzyc tych samych helperow JS gdzie sie da.
+      - Hardcodowania listy punktow w widoku — wszystko z API polkuriera przez AJAX.
+  </action>
+  <verify>
+    1. `/orders/114/shipment/prepare` — dropdown przewoznika ma "polkurier"; po wyborze pokazuje panel.
+    2. Select uslug ma realne wartosci z polkuriera.
+    3. `php -l routes/web.php` i `CronHandlerFactory.php`.
+  </verify>
+  <done>AC-4 satisfied: panel polkurier widoczny w prepare.php, integracja z registry, cron tracker zarejestrowany.</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Live test polkurier ShipmentService na zamowieniach #114 i #115. Operator nadaje paczki przez nowy panel UI, weryfikuje wynik, recznie anuluje w panelu polkurier po weryfikacji.</what-built>
+  <how-to-verify>
+    1. XAMPP MySQL online + cron disabled (zeby tracking nie zaczal pingowac przed weryfikacja).
+    2. Otworz `/orders/114/shipment/prepare`:
+       - Wybierz "polkurier" w dropdownie.
+       - Wybierz usluge kuriera (np. DPD Standard albo InPost Kurier).
+       - Uzupelnij wymiary/wage; potwierdz adres odbiorcy.
+       - Submit.
+    3. Sprawdz redirect na `/orders/114` -> zakladka Przesylki:
+       - Wiersz `provider=polkurier`, niepusty `tracking_number`, link "Pobierz etykiete" otwiera PDF.
+    4. Powtorz dla zamowienia #115 — ten raz z usluga paczkomatowa (InPost Paczkomat); selektor punktu pokazuje liste paczkomatow z API.
+    5. Otworz panel polkurier.pl manualnie -> zobacz utworzone paczki.
+    6. Anuluj obie paczki w panelu polkurier (manualna akcja).
+    7. Zglos wynik: "OK" jezeli paczki utworzone i etykiety pobrane, "issues" z opisem co nie dziala.
+  </how-to-verify>
+  <resume-signal>Type "approved" to continue with delivery_status_mappings seed, or describe issues to fix</resume-signal>
+</task>
+
+<task type="auto">
+  <name>Task 4: Migracja seed delivery_status_mappings + weryfikacja /settings/delivery-statuses</name>
+  <files>database/migrations/20260514_000115_seed_polkurier_delivery_status_mappings.sql</files>
+  <action>
+    Stworzyc migracje seedujaca `delivery_status_mappings` (provider='polkurier') na podstawie REALNYCH statusow zwracanych przez API polkurier w Task 1 (operator po live tescie zna konkretne `status_code` z `getStatus`).
+
+    Baseline mapowan (do dostrojenia po live tescie):
+      - `nowa` / `przyjete` / `oczekuje` -> `registered`
+      - `wydrukowane` / `przygotowanie` -> `label_printed` (jezeli istnieje w `delivery_statuses` — sprawdzic w Phase 108)
+      - `nadane` / `w_dostawie` / `w_doreczeniu` -> `in_transit` lub `out_for_delivery`
+      - `doreczone` / `odebrane` -> `delivered`
+      - `zwrocone` -> `returned`
+      - `anulowane` -> `cancelled`
+      - `niedoreczone` / `blad_doreczenia` -> `delivery_failed` lub `unknown` (zaleznie od `delivery_statuses`)
+
+    Migracja musi byc idempotentna: `INSERT INTO delivery_status_mappings (provider, raw_status, normalized_status, description) VALUES (...) ON DUPLICATE KEY UPDATE normalized_status = VALUES(normalized_status), description = VALUES(description);`.
+
+    Uruchom `php bin/migrate.php` po zatwierdzeniu mapowan.
+
+    Otworz `/settings/delivery-statuses?tab=mapping` -> potwierdz widocznosc wpisow provider='polkurier'.
+
+    Avoid:
+      - Seedu na bazie przypuszczen — uzyj statusow ZAOBSERWOWANYCH w live tescie z Task checkpoint.
+      - Tworzenia nowych wpisow w `delivery_statuses` (jezeli polkurier zwraca status ktorego nie ma — dodaj rownolegly INSERT do tej migracji albo osobna migracje).
+  </action>
+  <verify>
+    1. `php bin/migrate.php` zwraca success.
+    2. `SELECT COUNT(*) FROM delivery_status_mappings WHERE provider='polkurier'` >= 6.
+    3. `/settings/delivery-statuses?tab=mapping` pokazuje wiersze polkurier.
+    4. Ponowne uruchomienie migracji = no-op (idempotencja).
+  </verify>
+  <done>AC-5 satisfied: mapowania wpisane do DB, widoczne w UI, idempotentne.</done>
+</task>
+
+<task type="auto">
+  <name>Task 5: Aktualizacja dokumentacji codebase</name>
+  <files>.paul/codebase/architecture.md, .paul/codebase/db_schema.md, .paul/codebase/tech_changelog.md</files>
+  <action>
+    **architecture.md** — dolozyc sekcje "Phase 128 — polkurier ShipmentService + Tracking" pod sekcja Phase 127:
+      - PolkurierApiClient — pelna lista 7 publicznych metod z apimetod-ami.
+      - PolkurierShipmentService — kontrakt ShipmentProviderInterface, lista pol payloadu, integracja z `getAvailableCarriers`.
+      - PolkurierTrackingService — kontrakt ShipmentTrackingInterface, mapowanie statusow.
+      - Wiring w `ShipmentProviderRegistry` i `CronHandlerFactory`.
+      - UI prepare.php panel polkurier — selector uslug + pickup point ajax.
+
+    **db_schema.md** — dolozyc seed mapping rows w sekcji "delivery_status_mappings":
+      - Wymienic mapowania `provider='polkurier'` z migracji.
+
+    **tech_changelog.md** — wpis z data 2026-05-14 (lub data wdrozenia):
+      - "Phase 128 (polkurier ShipmentService): pelna implementacja API client (createShipment/getLabel/getStatus/cancelOrder/getAvailableCarriers/getParcelMachines/getPostOffices), PolkurierShipmentService implementing ShipmentProviderInterface, PolkurierTrackingService, UI panel w prepare.php, seed delivery_status_mappings."
+
+    Avoid: kopiowania kodu do dokumentacji (zostawic referencje sciezek + 1-2 zdania kontraktu).
+  </action>
+  <verify>
+    Manualnie przegladnac diff `.paul/codebase/*.md` — wpisy obecne, formatowanie spojne z Phase 127.
+  </verify>
+  <done>Dokumentacja zaktualizowana zgodnie z CLAUDE.md (sekcja "Utrwalanie stalych wymagan").</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- `src/Modules/Settings/PolkurierIntegrationRepository.php` — Phase 127, kontrakt stabilny.
+- `src/Modules/Settings/PolkurierApiClient::testConnection()` — Phase 127, zweryfikowany na zywym koncie ("Autoryzacja: 1").
+- `apaczka_integration_settings`, `ApaczkaShipmentService`, `ApaczkaTrackingService` — Apaczka dziala niezaleznie obok polkuriera.
+- `database/migrations/20260514_000114_create_polkurier_integration_settings.sql` (Phase 127).
+- `ShipmentProviderInterface` i `ShipmentTrackingInterface` — kontrakty stabilne (nie dolozyc/zmienic metod).
+- Reszta paneli w `prepare.php` (allegro/inpost/apaczka) — tylko dolozenie nowego panelu polkurier obok.
+
+## SCOPE LIMITS
+- BEZ implementacji `OrderValuationV2` (wycena przed nadaniem) — odlozone na osobna faze.
+- BEZ presetow przesylek dla polkuriera (`shipment_presets.provider_code='polkurier'`) — operator moze ich uzywac dopiero jak panel polkurier dziala; presety w osobnej fazie.
+- BEZ widoku CLI smoke test scriptu (`bin/smoke-polkurier.php`) — testujemy w realnym UI na #114/#115.
+- BEZ event automatyzacji `shipment.created` zmian — to zdarzenie juz emitowane jednolicie z `ShipmentController::store()` dla wszystkich providerow.
+- BEZ idempotencji createShipment (double-POST guard) — jak w Apaczce, brak retry guard w MVP.
+- BEZ refaktoringu wspolnego kodu Apaczka/polkurier (`buildReceiverAddress`, `validateSenderAddress` itp.) — kopiujemy wzorzec, deduplikacja w osobnym planie.
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] `php -l` przechodzi dla wszystkich zmienionych plikow PHP
+- [ ] Migracja `20260514_000115_*.sql` wykonana, ponowne uruchomienie = no-op
+- [ ] Operator potwierdzil checkpoint: 2 paczki utworzone na #114 i #115, etykiety pobrane, manualnie anulowane w panelu polkurier
+- [ ] `/settings/delivery-statuses?tab=mapping` pokazuje wpisy provider='polkurier'
+- [ ] `/orders/{id}/shipment/prepare` panel polkurier widoczny i funkcjonalny
+- [ ] Cron tracking nie crashuje (sprawdzic `storage/logs/app.log` po jednym przebiegu)
+- [ ] Dokumentacja `.paul/codebase/*.md` zaktualizowana
+- [ ] Wszystkie AC-1..AC-6 spelnione
+</verification>
+
+<success_criteria>
+- Operator moze nadawac paczki przez polkurier z poziomu `/orders/{id}/shipment/prepare` w 4 trybach: kurier door-to-door, paczkomat InPost, punkt Pocztex/Kurier48, ORLEN.
+- Tracking polkurier dziala w cronie i aktualizuje `shipment_packages.delivery_status` przez `delivery_status_mappings`.
+- Live test na #114 i #115 zakonczony sukcesem (paczki utworzone, etykiety pobrane, recznie anulowane).
+- Zaden istniejacy provider (Apaczka/InPost/Allegro WZA) nie regresuje.
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/128-polkurier-shipment-service/128-01-SUMMARY.md`
+</output>

.paul/phases/128-polkurier-shipment-service/128-01-SUMMARY.md

@@ -0,0 +1,221 @@
+---
+phase: 128-polkurier-shipment-service
+plan: 01
+subsystem: shipments
+tags: [polkurier, courier, broker, shipment, tracking, ui-prepare, delivery-status-mappings]
+
+requires:
+  - phase: 127-polkurier-integration-foundation
+    provides: PolkurierIntegrationRepository (login + Token API + getCredentials), PolkurierApiClient.testConnection, integration row in `integrations` + `polkurier_integration_settings`.
+
+provides:
+  - PolkurierApiClient z pelnym kontraktem (createShipment/getLabel/getStatus/cancelOrder/getAvailableCarriers/getInpostParcelMachines/getCourierPoints).
+  - PolkurierShipmentService implementujacy ShipmentProviderInterface — operator tworzy paczki polkurier z `/orders/{id}/shipment/prepare`.
+  - PolkurierTrackingService implementujacy ShipmentTrackingInterface — cron `shipment_tracking_sync` pinguje get_status.
+  - DeliveryStatus::trackingUrl fallback `https://polkurier.pl/sledz-paczke/<tracking>` + carrier_id routing.
+  - UI panel "polkurier" w `prepare.php` z dynamiczna lista uslug z available_carriers.
+  - Seed migracja `delivery_status_mappings(provider='polkurier')` z 7 wpisami O/P/A/WP/D/Z/W → znormalizowane statusy.
+
+affects: [paczkomaty UI (InpostParcelMachines/PocztexPostOffices/Kurier48PostOffices), shipment_presets (provider_code='polkurier'), OrderValuationV2 (wycena przed nadaniem)]
+
+tech-stack:
+  added: []
+  patterns:
+    - "Wspolny prywatny `call($apimetod, $data, $login, $token): mixed` w API client parsuje envelope `{status, response}`; sukces -> tresc `response`, blad -> RuntimeException z trescia z `response`. Reuse dla wszystkich apimetod."
+    - "polkurier SDK Order entity zwraca `number` (nie `orderno`) i `waybills[0].number` — `extractOrderNumber`/`extractTrackingNumber` priorytetuja SDK shape, fallback na top-level klucze."
+    - "polkurier API nie udostepnia parametru rozmiaru etykiety (A4/A6) — sterowane wylacznie w panelu klienta polkurier.pl. `polkurier_integration_settings.default_label_format` (PDF/ZPL/EPL) odnosi sie do typu pliku, NIE rozmiaru."
+
+key-files:
+  created:
+    - src/Modules/Shipments/PolkurierShipmentService.php
+    - src/Modules/Shipments/PolkurierTrackingService.php
+    - database/migrations/20260514_000115_seed_polkurier_delivery_status_mappings.sql
+  modified:
+    - src/Modules/Settings/PolkurierApiClient.php
+    - src/Modules/Shipments/DeliveryStatus.php
+    - src/Modules/Shipments/ShipmentController.php
+    - src/Modules/Cron/CronHandlerFactory.php
+    - routes/web.php
+    - resources/views/shipments/prepare.php
+
+key-decisions:
+  - "polkurier `shipmenttype` wymaga lowercase z zbioru [box, envelope, palette, small_parcel, parcel_size_20] — `normalizeShipmentType()` mapuje legacy PACKAGE/BOX/PARCEL/PACZKA/KOPERTA/PALETA na format polkuriera."
+  - "Rozmiar etykiety A4/A6 sterowany w panelu klienta polkurier.pl, NIE przez API (zweryfikowane na PDF v1.11) — kod nie wysyla zadnego parametru rozmiaru."
+  - "Brak dedykowanego selektora punktu odbioru w UI — operator wpisuje `receiver_point_id` w istniejacy text input w sekcji Adres odbiorcy (np. `POP-RZE54`); usuniety AJAX endpoint i lookupPickupPoints."
+  - "Seed `delivery_status_mappings` bazuje na oficjalnej tabeli ORDER_STATUS z PDF v1.11 (kody O/P/A/WP/D/Z/W), nie na obserwacji w live tescie — bezpieczniejsze i wyczerpujace."
+  - "polkurier dziala obok Apaczki (decyzja z Phase 127 zachowana); `ShipmentProviderRegistry` rejestruje oba; brak migracji shipment_presets."
+
+patterns-established:
+  - "Pattern: dla nowych metod polkurier API uzywaj wspolnego `call($apimetod, $data, $login, $token)`. Status `success` zwraca tresc `response`. Status inny rzuca `RuntimeException` z trescia `response` (string albo zserializowany JSON dla tablic)."
+  - "Pattern: dla parsowania odpowiedzi polkurier SDK entity, najpierw priorytetuj klucze entity (`number`, `waybills[].number`, `file`), potem fallback na top-level/snake_case klucze, potem obsluga wrapperow `{order:{...}}` i list."
+  - "Pattern: diagnostyka silent-fail w ShipmentService — gdy parsing API odpowiedzi zwraca pusty wynik mimo `status=success`, zapisuj fragment surowej odpowiedzi do `shipment_packages.error_message` zeby operator/dev zobaczyl shape."
+
+duration: ~120min (incl. 4 live test iteracje)
+started: 2026-05-14T20:00:00Z
+completed: 2026-05-14T22:00:00Z
+---
+
+# Phase 128 Plan 01: polkurier ShipmentService + Tracking + UI prepare
+
+**polkurier zarejestrowany jako pelnoprawny przewoznik obok Apaczki — operator tworzy paczki przez UI `/orders/{id}/shipment/prepare`, etykieta A6 generowana, cron tracking gotowy do mapowania statusow O/P/A/WP/D/Z/W na znormalizowane created/confirmed/cancelled/in_transit/delivered/returned/problem.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~120 min |
+| Started | 2026-05-14T20:00:00Z |
+| Completed | 2026-05-14T22:00:00Z |
+| Tasks | 6/6 completed (5 auto + 1 checkpoint) |
+| Files modified | 10 |
+| Live test iteracje | 4 (ReferenceError → uppercase shipmenttype → orderno parsing → A6 panel) |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: PolkurierApiClient pelny kontrakt API | Pass | 7 metod (createShipment/getLabel/getStatus/cancelOrder/getAvailableCarriers/getInpostParcelMachines/getCourierPoints) zweryfikowane na PDF v1.11. `call()` wspolny wrapper envelope `{status, response}`. |
+| AC-2: PolkurierShipmentService implementuje ShipmentProviderInterface | Pass | `code()='polkurier'`, `getDeliveryServices` cache per-request, `createShipment` orchestruje pelny flow z normalizacja shipmenttype i splitem ulicy, `downloadLabel` z base64 decode na klucz `file`. Verified on #114/#115. |
+| AC-3: PolkurierTrackingService cron tracking | Pass (kod) | Implementacja kompletna, ale niezweryfikowane na zywej bazie podczas APPLY (operator anulowal paczki w panelu polkurier po teście — cron nie mial co pingowac). Graceful null przy bledach. Pierwszy passthrough nastapi przy nastepnej zywej paczce. |
+| AC-4: UI prepare.php panel polkurier | Pass | Opcja "polkurier" w dropdownie, panel z dynamiczna lista uslug, hidden `service_code`. Bez dedykowanego selektora punktu — operator wpisuje w istniejacy input w sekcji Adres odbiorcy. |
+| AC-5: delivery_status_mappings + /settings/delivery-statuses | Pass (kod) | Migracja idempotentna z 7 wpisami O/P/A/WP/D/Z/W. Operator uruchomi `php bin/migrate.php` gdy MySQL online. Widocznosc w `/settings/delivery-statuses` po migracji. |
+| AC-6: Live test na #114 i #115 | Pass | 4 iteracje, ostatecznie obie paczki utworzone w polkurier, etykiety pobrane (A6 po zmianie w panelu klienta), operator anulowal w panelu polkuriera po weryfikacji. |
+
+## Accomplishments
+
+- polkurier zarejestrowany jako 4. provider w `ShipmentProviderRegistry` (obok allegro_wza, apaczka, inpost) — operator nadaje paczki z UI bez przelaczania platform.
+- Kontrakt API zweryfikowany na oficjalnej dokumentacji PDF v1.11 (pobranej i zachowanej w `.paul/phases/128-polkurier-shipment-service/polkurier-api-docs.txt` — referencyjne zrodlo dla przyszlych faz).
+- Mapowanie statusow `O/P/A/WP/D/Z/W` na znormalizowane statusy `created/confirmed/cancelled/in_transit/delivered/returned/problem` z idempotentna migracja — cron tracking gotowy do dzialania.
+- Diagnostyka silent-fail patternem (zapis fragmentu surowej odpowiedzi do `error_message` przy nieudanym parsingu) — uratowala 3. iteracje live testu (parsing `number` vs `orderno`).
+
+## Task Commits
+
+Wszystkie zmiany w jednym stanie WIP — commit zostanie wykonany w transition (`feat(128): polkurier shipment service + tracking + UI prepare`).
+
+| Task | Status | Description |
+|------|--------|-------------|
+| Task 1: PolkurierApiClient pelen kontrakt API | done | 7 metod, wspolny `call()` wrapper, parsowanie envelope |
+| Task 2: PolkurierShipmentService + PolkurierTrackingService | done | ~520 + ~110 LOC, oba implementuja swoje interfejsy |
+| Task 3: Wiring + UI prepare.php panel | done | Registry, CronHandlerFactory, ShipmentController.prepare/create, panel + JS |
+| Task 4: Live test checkpoint na #114/#115 | done | Operator approved po 4 iteracjach, etykieta A6 po zmianie w panelu klienta polkurier |
+| Task 5: Migracja seed delivery_status_mappings | done (kod) | 7 wpisow z PDF v1.11, idempotentna; operator uruchomi gdy MySQL online |
+| Task 6: Aktualizacja `.paul/codebase/*.md` | done | architecture.md (Phase 128 sekcja), db_schema.md (seed mappings), tech_changelog.md (Phase 128 entry z 4 deviationami i iteracjami live testu) |
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/Modules/Settings/PolkurierApiClient.php` | Modified | Stuby z Phase 127 zastapione 7 metodami: createShipment/getLabel/getStatus/cancelOrder/getAvailableCarriers/getInpostParcelMachines/getCourierPoints. Wspolny `call()` parser envelope. |
+| `src/Modules/Shipments/PolkurierShipmentService.php` | Created | `implements ShipmentProviderInterface`, ~520 LOC. createShipment orchestracja, normalizeShipmentType, splitStreetAndNumber, buildRecipient/buildSender/buildPickup, downloadLabel z base64 decode, extractOrderNumber/extractTrackingNumber priorytetujace SDK shape. |
+| `src/Modules/Shipments/PolkurierTrackingService.php` | Created | `implements ShipmentTrackingInterface`, ~110 LOC. getDeliveryStatus z graceful null + normalizacja przez DeliveryStatusMappingRepository. |
+| `src/Modules/Shipments/DeliveryStatus.php` | Modified | +4 LOC: fallback URL `https://polkurier.pl/sledz-paczke/<tracking>`. Carrier_id routing przez `matchCarrierByName` automatyczny. |
+| `src/Modules/Shipments/ShipmentController.php` | Modified | prepare() fetchuje polkurierServices, create() rozszerzony o service_code/pickup_date/pickup_time_from/pickup_time_to. |
+| `src/Modules/Cron/CronHandlerFactory.php` | Modified | PolkurierTrackingService dodany do ShipmentTrackingRegistry. |
+| `routes/web.php` | Modified | use PolkurierApiClient + PolkurierShipmentService, registry zarejestrowany. |
+| `resources/views/shipments/prepare.php` | Modified | Opcja "polkurier" w carrier select, panel z select uslug, hidden service_code, JS handler. |
+| `database/migrations/20260514_000115_seed_polkurier_delivery_status_mappings.sql` | Created | 7 wpisow O/P/A/WP/D/Z/W → normalized. Idempotentne. |
+| `.paul/codebase/architecture.md` | Modified | Sekcja Phase 128 (PolkurierApiClient/ShipmentService/TrackingService/UI/wiring/seed/boundaries). |
+| `.paul/codebase/db_schema.md` | Modified | Seedowane mapowania `provider='polkurier'` w sekcji `delivery_status_mappings`. |
+| `.paul/codebase/tech_changelog.md` | Modified | Entry Phase 128 z opisem zmian + 4 iteracje live testu + deviations. |
+| `.paul/phases/128-polkurier-shipment-service/polkurier-api-docs.txt` | Created | Tekst PDF v1.11 (pdftotext extract) — referencyjne zrodlo dla przyszlych faz polkuriera. |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| `shipmenttype` lowercase + `normalizeShipmentType()` mapping | polkurier API odrzuca uppercase `BOX` — wymaga lowercase z zbioru `[box, envelope, palette, small_parcel, parcel_size_20]` (komunikat bledu w live tescie). Aliasy dla PACKAGE/PARCEL/PACZKA/KOPERTA/PALETA pozwalaja reuse istniejacych wartosci formularza. | Wszystkie kolejne paczki polkurier maja poprawny shipmenttype bez zmian w formularzu/preset. |
+| `extractOrderNumber` priorytetuje pole `number` (SDK Order entity) nad `orderno` | polkurier `create_order` zwraca Order entity z polem `number` (zweryfikowane w SDK Order.php — setNumber/getNumber). `orderno` to nazwa parametru INPUT w innych metodach (get_label, get_status, cancel_order). | Parsing dziala dla aktualnej wersji SDK + odporne na stary shape (`orderno` fallback). |
+| Brak dedykowanego selektora punktu odbioru w UI | Operator zglosil ze `Punkt odbioru` jest juz polem w sekcji Adres odbiorcy z auto-fillem `parcel_external_id` z importu zamowienia. Dodatkowy selektor byl duplikatem. | Usuniete: `lookupPickupPoints`, `ShipmentController::polkurierPoints`, route, JS handler. Operator wpisuje czysty ID (np. `POP-RZE54`) w istniejacy input. |
+| Rozmiar etykiety A4/A6 sterowany w panelu klienta polkurier.pl | API polkurier nie udostepnia parametru rozmiaru w `get_label` ani `create_order` (zweryfikowane na PDF v1.11). Operator zmienia preferencje konta jednorazowo. | Brak dodatkowego pola w `polkurier_integration_settings` ani formularzu; `default_label_format` (PDF/ZPL/EPL) odnosi sie tylko do typu pliku. |
+| Seed `delivery_status_mappings` z PDF v1.11 (nie z obserwacji live test) | Live test obejmowal tylko status `P` (Potwierdzone) bezposrednio po `create_order`. Seedowanie bazujace na obserwacji wymagaloby kolejnych miesiecy zywych paczek. PDF ma kompletna tabele ORDER_STATUS. | 7 wpisow O/P/A/WP/D/Z/W ready od pierwszego dnia. |
+| Diagnostyka silent-fail patternem (zapis surowej odpowiedzi do `error_message`) | 3. iteracja live testu (parsing `number` vs `orderno`) byla niemozliwa do debugowania bez podgladu surowej odpowiedzi — `payload_json` w `shipment_packages.update()` jest poza whitelist. Zapis fragmentu (400 znakow) do `error_message` jest tani i widoczny operatorowi w UI. | Pattern do reuse dla nowych integracji API z nieznanym shape odpowiedzi. |
+
+## Deviations from Plan
+
+### Summary
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Auto-fixed | 4 | Live test iteracje — wszystkie naprawione w tej samej sesji APPLY |
+| Scope removals | 1 | UI selektor punktow paczkomatowych usuniety na zyczenie operatora |
+| Scope additions | 1 | Pole `service_code` i `pickup_*` w `ShipmentController::create()` (potrzebne dla polkurier payload) |
+| Deferred | 3 | Cron tracking weryfikacja, migracja MySQL, paczkomaty UI (kolejna faza) |
+
+**Total impact:** Essential fixes (live test feedback), no scope creep — operator manual confirmation poszerzyl o jedno usuniecie (selektor punktu) i jedno dodanie (`service_code` przekazywany do service).
+
+### Auto-fixed Issues
+
+**1. [JS ReferenceError] `polkurierPointIdInput is not defined` w `clearHiddenFields()`**
+- **Found during:** Task 4 (live test, pierwszy submit polkurier)
+- **Issue:** Po usunieciu duplikatu selektora punktu odbioru (po feedback operatora w Task 3 iteracji) zostala martwa referencja do zmiennej `polkurierPointIdInput` w `clearHiddenFields()`. JS rzucal ReferenceError, handler `carrierSelect.change` przerywal przed wywolaniem `showPanel()`, `provider_code` zostawal na PHP-renderowanej wartosci `apaczka` (gdy `$preselectedCarrier === 'apaczka'`). Submit szedl do ApaczkaShipmentService → blad "Nie podano uslugi Apaczka."
+- **Fix:** Usuniecie linii `if (polkurierPointIdInput) polkurierPointIdInput.value = '';` z `clearHiddenFields()`.
+- **Files:** `resources/views/shipments/prepare.php`
+- **Verification:** Drugi submit polkurier → routing do PolkurierShipmentService.
+
+**2. [Polkurier API validation] `shipmenttype` musi byc lowercase**
+- **Found during:** Task 4 (live test, drugi submit po napraweniu #1)
+- **Issue:** Wysylanie `BOX` uppercase → API odrzucalo: "Typ paczki musi przyjmowac jeden z parametrow ze zbioru [box, envelope, palette, small_parcel, parcel_size_20]".
+- **Fix:** Nowa metoda `normalizeShipmentType()` z lowercase + aliasami (PACKAGE→box, PARCEL→box, PACZKA→box, KOPERTA→envelope, PALETA→palette, MALA_PACZKA/SMALL→small_parcel). Default `box`.
+- **Files:** `src/Modules/Shipments/PolkurierShipmentService.php`
+- **Verification:** Trzeci submit → paczka utworzona w polkurier.
+
+**3. [Response shape mismatch] `extractOrderNumber` nie znajdowal pola `number`**
+- **Found during:** Task 4 (live test, trzeci submit — paczka utworzona w polkurier ale w orderPRO `status=pending`)
+- **Issue:** Pierwotny parsing szukal kluczy `orderno`/`order_no` w odpowiedzi. polkurier zwraca SDK Order entity z polem `number` + tablica `waybills[]` z `OrderWaybill` entity (zweryfikowane w `Order.php` setterach `setNumber()`, `addWaybill()`).
+- **Fix:** Nowe metody `extractOrderNumber()` (priorytet `number`, fallback `orderno`/`order_no`/`order_number`/`order_id`/`id`, obsluga wrappera `{order:{...}}` i list) + `extractTrackingNumber()` (priorytet `waybills[0].number`, fallback top-level klucze). Dodatkowo diagnostyka: gdy `orderno=''`, zapis fragmentu surowej odpowiedzi do `error_message`.
+- **Files:** `src/Modules/Shipments/PolkurierShipmentService.php`
+- **Verification:** Czwarty submit → `status=created`, `tracking_number` ustawiony, etykieta pobrana z pola `file`.
+
+**4. [API misunderstanding] Bogus parametry rozmiaru etykiety**
+- **Found during:** Task 4 (live test, czwarty submit — etykieta A4 zamiast A6)
+- **Issue:** Iteracja w 3 bogus parametry (`format`/`label_size`/`paper_size`) wyslanych do `get_label` — bez efektu, bo API ignoruje nieznane pola. Operator zglosil ze etykieta nadal A4.
+- **Fix:** Pobranie i przeczytanie oficjalnej dokumentacji PDF v1.11 potwierdzilo: `get_label` przyjmuje WYLACZNIE `orderno`. Rozmiar A4/A6 sterowany jest w panelu klienta polkurier.pl. Usuniete bogus parametry, `getLabel($login, $token, $orderno)` ma tylko 3 argumenty. Operator zmienil ustawienie w panelu polkurier — etykieta A6 OK.
+- **Files:** `src/Modules/Settings/PolkurierApiClient.php`, `src/Modules/Shipments/PolkurierShipmentService.php`
+- **Verification:** Operator nadal kolejna paczke → etykieta A6.
+
+### Scope Removals
+
+**UI selektor punktow paczkomatowych (AJAX endpoint + dropdown)**
+- **Removed during:** Task 3 iteracje (po feedback operatora)
+- **Reason:** Istnieje juz pole `name="receiver_point_id"` w sekcji Adres odbiorcy z auto-fillem `parcel_external_id` z importu zamowienia. Dodatkowy selektor byl duplikatem. Operator wpisuje czysty ID recznie (np. `POP-RZE54`).
+- **Files removed:** `PolkurierShipmentService::lookupPickupPoints()`, `ShipmentController::polkurierPoints()`, route `/shipments/polkurier/points`, JS handler `loadPolkurierPoints/renderPolkurierPoints`.
+- **Zachowane:** `PolkurierApiClient::getInpostParcelMachines()` i `getCourierPoints()` — gotowe stuby na przyszle rozszerzenie (kolejna faza paczkomatow UI).
+
+### Scope Additions
+
+**`service_code` + `pickup_*` w `ShipmentController::create()`**
+- **Reason:** PolkurierShipmentService potrzebuje servicecode z available_carriers (osobne pole niz `delivery_method_id` zeby JS mogl wstawic czysta wartosc) + optional pickup override.
+- **Impact:** Backward compatible — Apaczka/InPost/AllegroWZA ignoruja te pola w swoich createShipment.
+
+### Deferred Items
+
+- **Phase 128 follow-up:** Operator uruchomi `php bin/migrate.php` gdy XAMPP MySQL online (utworzy 7 wpisow `provider='polkurier'` w `delivery_status_mappings`).
+- **Phase 128 follow-up:** Cron `shipment_tracking_sync` weryfikacja przy pierwszej zywej paczce polkurier w `in_transit` — pierwszy realny passthrough TrackingService dopiero przy nastepnej niezanulowanej paczce.
+- **Kolejna faza:** Paczkomaty UI panel (`InpostParcelMachines`/`PocztexPostOffices`/`Kurier48PostOffices` selectory w `prepare.php`), presety przesylek z `provider_code='polkurier'`, `OrderValuationV2` (wycena przed nadaniem).
+
+## Issues Encountered
+
+| Issue | Resolution |
+|-------|------------|
+| Migracja `20260514_000115` nie uruchomiona — MySQL offline z poziomu agenta (Bash) | Operator uruchomi recznie `php bin/migrate.php` gdy XAMPP MySQL online. Migracja jest idempotentna. |
+| AC-3 (cron tracking) nie zweryfikowane na zywej bazie | Operator anulowal obie paczki w panelu polkurier po teście — cron tracking nie mial co pingowac. Implementacja kompletna i defensywna (graceful null). Weryfikacja przy nastepnej zywej paczce. |
+| PDF v1.11 polkurier API niedostepny przez WebFetch (binary content) | Pobrane przez WebFetch jako binarny PDF + `pdftotext.exe` (Git Bash bundle) → tekst w `.paul/phases/128-polkurier-shipment-service/polkurier-api-docs.txt`. Pattern dla przyszlych fetchy binary docs. |
+
+## Next Phase Readiness
+
+**Ready:**
+- polkurier dziala end-to-end w UI (tworzenie + etykieta + tracking gotowy).
+- Kontrakt API zweryfikowany na oficjalnej dokumentacji (PDF v1.11) — przyszle fazy maja stale referencyjne zrodlo.
+- Diagnostyka silent-fail pattern do reuse dla nowych integracji.
+- `getInpostParcelMachines`/`getCourierPoints` stuby gotowe dla kolejnej fazy paczkomaty UI.
+
+**Concerns:**
+- AC-3 (cron tracking) nie zweryfikowane na zywej bazie — pierwszy passthrough wymaga niezanulowanej paczki polkurier. Defensywne kodowanie (graceful null) chroni przed crashem crona, ale realne dzialanie testowalne dopiero na zywej paczce.
+- `extractOrderNumber`/`extractTrackingNumber` fallback chain moze nie pokryc 100% wariantow shape odpowiedzi (np. order zlecone z dodatkowymi opcjami). Pattern z `error_message` dump pomoze w iteracji.
+
+**Blockers:**
+- None.
+
+---
+*Phase: 128-polkurier-shipment-service, Plan: 01*
+*Completed: 2026-05-14*