feat(27-shipment-tracking-backend): infrastruktura sledzenia przesylek — statusy, tracking services, cron handler

Dwupoziomowy system statusow dostawy (normalized + raw z API), implementacje trackingu dla InPost ShipX, Apaczka i Allegro WZA, cron handler odpytujacy aktywne przesylki co 15 minut. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23 20:33:44 +01:00
parent c59d431083
commit 228c0e96cf
17 changed files with 1365 additions and 27 deletions
--- a/DOCS/SHIPMENT_TRACKING_STATUSES.md
+++ b/DOCS/SHIPMENT_TRACKING_STATUSES.md
@@ -0,0 +1,207 @@
+# Statusy śledzenia przesyłek — dokumentacja API przewoźników
+
+## Spis treści
+- [InPost ShipX API v1](#inpost-shipx-api-v1)
+- [Apaczka API v2](#apaczka-api-v2)
+- [Allegro Shipment Management API](#allegro-shipment-management-api)
+- [Mapowanie na statusy znormalizowane](#mapowanie-na-statusy-znormalizowane)
+
+---
+
+## InPost ShipX API v1
+
+Endpoint: `GET /v1/organizations/{orgId}/shipments/{shipmentId}`
+Pole statusu: `status` (string)
+Historia: tablica `tracking_details[]` z polami `status`, `origin_status`, `datetime`, `agency`
+
+### Tworzenie i przygotowanie
+
+| Status | Opis PL |
+|--------|---------|
+| `created` | Przesyłka utworzona |
+| `offers_prepared` | Oferty cenowe przygotowane |
+| `offer_selected` | Oferta wybrana |
+| `confirmed` | Przesyłka potwierdzona / opłacona |
+| `dispatched` | Przesyłka nadana (etykieta wygenerowana) |
+
+### Odbiór od nadawcy
+
+| Status | Opis PL |
+|--------|---------|
+| `collected` | Przesyłka odebrana od nadawcy / wrzucona do paczkomatu |
+| `taken_by_courier` | Przesyłka odebrana przez kuriera |
+| `adopted_at_source_branch` | Przyjęta w oddziale źródłowym |
+
+### Sortowanie i transport
+
+| Status | Opis PL |
+|--------|---------|
+| `adopted_at_sorting_center` | Przyjęta w centrum sortowania |
+| `sent_from_sorting_center` | Wysłana z centrum sortowania |
+| `adopted_at_target_sorting_center` | Przyjęta w docelowym centrum sortowania |
+| `sent_from_target_sorting_center` | Wysłana z docelowego centrum sortowania |
+| `adopted_at_target_branch` | Przyjęta w oddziale docelowym |
+
+### Dostarczanie
+
+| Status | Opis PL |
+|--------|---------|
+| `out_for_delivery` | W drodze do odbiorcy / paczkomatu |
+| `ready_to_pickup` | Gotowa do odbioru w paczkomacie |
+| `pickup_reminder_sent` | Wysłano przypomnienie o odbiorze |
+| `delivered` | Dostarczona / odebrana |
+| `pickup_time_expired` | Czas odbioru z paczkomatu upłynął |
+
+### Awizo i ponowne doręczenie
+
+| Status | Opis PL |
+|--------|---------|
+| `avizo` | Awizowana (pierwsza próba doręczenia nieudana) |
+| `claimed` | Odebrana po awizo |
+| `readdressed` | Przekierowana na inny adres |
+| `stack_in_box_machine` | Umieszczona w paczkomacie (overflow) |
+| `stack_parcel_pickup_time_expired` | Czas odbioru ze stack upłynął |
+
+### Zwrot do nadawcy
+
+| Status | Opis PL |
+|--------|---------|
+| `returned_to_sender` | Zwrócona do nadawcy |
+| `undelivered` | Niedoręczona |
+| `undelivered_wrong_address` | Niedoręczona — błędny adres |
+| `undelivered_incomplete_address` | Niedoręczona — niepełny adres |
+| `undelivered_unknown_recipient` | Niedoręczona — nieznany odbiorca |
+| `undelivered_cod_cash_receiver` | Niedoręczona — problem z pobraniem |
+
+### Anulowanie i wygaśnięcie
+
+| Status | Opis PL |
+|--------|---------|
+| `cancelled` | Anulowana |
+| `expired` | Wygasła |
+
+### Inne / specjalne
+
+| Status | Opis PL |
+|--------|---------|
+| `ready_to_pickup_from_branch` | Gotowa do odbioru z oddziału |
+| `ready_to_pickup_from_pok` | Gotowa do odbioru z POK |
+| `oversized` | Przesyłka ponadgabarytowa |
+| `missing` | Przesyłka zagubiona |
+| `delay_in_delivery` | Opóźnienie w dostawie |
+| `redirect_to_box` | Przekierowana do paczkomatu |
+| `stack_in_customer_service_point` | Umieszczona w punkcie obsługi |
+| `pickup_reminder_sent_address` | Przypomnienie wysłane na adres |
+
+### Uwagi
+- InPost okresowo dodaje nowe statusy — warto sprawdzać `tracking_details` zamiast polegać na zamkniętej liście
+- W `tracking_details` każdy wpis zawiera: `status`, `origin_status`, `datetime`, `agency`
+- Dokładna lista może się różnić w zależności od typu usługi (paczkomat vs kurier vs POP)
+
+---
+
+## Apaczka API v2
+
+Endpoint: `GET /api/v2/order/{orderId}/`
+Pole statusu: `status` (integer)
+Autentykacja: `app_id` + podpis HMAC-SHA256 z `app_secret`
+
+### Statusy zamówienia
+
+| Wartość | Nazwa | Opis PL |
+|---------|-------|---------|
+| `0` | PENDING | Zamówienie utworzone, oczekuje na przetworzenie |
+| `1` | CONFIRMED | Zamówienie potwierdzone |
+| `2` | PICKED_UP | Przesyłka odebrana przez kuriera |
+| `3` | IN_TRANSIT | Przesyłka w transporcie |
+| `4` | OUT_FOR_DELIVERY | Przesyłka w doręczeniu |
+| `5` | DELIVERED | Przesyłka doręczona |
+| `6` | RETURNED | Przesyłka zwrócona do nadawcy |
+| `7` | CANCELLED | Zamówienie anulowane |
+| `8` | ERROR | Błąd zamówienia |
+| `9` | WAITING_FOR_PICKUP | Oczekuje na odbiór w punkcie |
+| `10` | REDIRECT | Przesyłka przekierowana |
+
+### Dodatkowe pola w odpowiedzi
+
+- `tracking_number` — numer śledzenia
+- `tracking_status` — szczegółowy status śledzenia (może różnić się od `status`)
+- `service_id` — identyfikator usługi kurierskiej
+
+### Uwagi
+- Apaczka nie publikuje pełnej dokumentacji API publicznie — dostęp wymaga konta
+- Powyższa lista wymaga weryfikacji z oficjalną dokumentacją (panel.apaczka.pl)
+- Endpoint trackingu: `GET /api/v2/order/{orderId}/tracking/` (jeśli dostępny)
+
+---
+
+## Allegro Shipment Management API
+
+Endpoint: `GET /shipment-management/shipments/{shipmentId}`
+Pole statusu: `status` (string)
+
+### Statusy przesyłki (Shipment Management)
+
+| Status | Opis PL |
+|--------|---------|
+| `NEW` | Przesyłka utworzona, nie przekazana przewoźnikowi |
+| `READY_TO_SHIP` | Etykieta wygenerowana, oczekuje na odbiór/nadanie |
+| `IN_TRANSIT` | Przesyłka odebrana przez przewoźnika |
+| `DELIVERED` | Przesyłka doręczona |
+| `CANCELLED` | Przesyłka anulowana |
+| `ERROR` | Błąd przetwarzania |
+| `RETURNED` | Przesyłka zwrócona do nadawcy |
+
+### Statusy realizacji zamówienia (Order Fulfillment)
+
+Endpoint: `GET /order/checkout-forms/{checkoutFormId}`
+Pole: `fulfillment.status`
+
+| Status | Opis PL |
+|--------|---------|
+| `NEW` | Zamówienie złożone, nie przetworzone |
+| `PROCESSING` | Sprzedawca przetwarza zamówienie |
+| `READY_FOR_SHIPMENT` | Spakowane, oczekuje na wysyłkę |
+| `SENT` | Wysłane (numer śledzenia podany) |
+| `DELIVERED` | Potwierdzone doręczenie |
+| `CANCELLED` | Zamówienie anulowane |
+
+### Ważne ograniczenia
+- **Allegro NIE ma dedykowanego API śledzenia przesyłek** (brak endpointu typu `/tracking/{trackingNumber}`)
+- Shipment Management API daje statusy TYLKO dla przesyłek utworzonych przez zintegrowanych przewoźników Allegro
+- Dla szczegółowego śledzenia trzeba odpytywać **API przewoźnika bezpośrednio** (InPost, DPD, DHL, etc.)
+- Dla ręcznie wpisanych numerów śledzenia — brak automatycznego trackingu przez Allegro
+
+---
+
+## Mapowanie na statusy znormalizowane
+
+System orderPRO używa dwupoziomowego systemu statusów:
+1. **`delivery_status`** — znormalizowany status (dla UI, filtrów, logiki)
+2. **`delivery_status_raw`** — surowy status z API przewoźnika
+
+### Tabela mapowania
+
+| Znormalizowany | InPost ShipX | Apaczka | Allegro SM |
+|----------------|-------------|---------|------------|
+| `unknown` | *(brak danych)* | *(brak danych)* | *(brak danych)* |
+| `created` | `created`, `offers_prepared`, `offer_selected` | `0` (PENDING) | `NEW` |
+| `confirmed` | `confirmed`, `dispatched` | `1` (CONFIRMED) | `READY_TO_SHIP` |
+| `in_transit` | `collected`, `taken_by_courier`, `adopted_at_sorting_center`, `sent_from_sorting_center`, `adopted_at_target_sorting_center`, `sent_from_target_sorting_center`, `adopted_at_target_branch`, `adopted_at_source_branch` | `2` (PICKED_UP), `3` (IN_TRANSIT) | `IN_TRANSIT` |
+| `out_for_delivery` | `out_for_delivery` | `4` (OUT_FOR_DELIVERY) | — |
+| `ready_for_pickup` | `ready_to_pickup`, `ready_to_pickup_from_branch`, `ready_to_pickup_from_pok`, `stack_in_box_machine`, `stack_in_customer_service_point` | `9` (WAITING_FOR_PICKUP) | — |
+| `delivered` | `delivered`, `claimed` | `5` (DELIVERED) | `DELIVERED` |
+| `returned` | `returned_to_sender`, `undelivered`, `undelivered_wrong_address`, `undelivered_incomplete_address`, `undelivered_unknown_recipient`, `undelivered_cod_cash_receiver` | `6` (RETURNED) | `RETURNED` |
+| `cancelled` | `cancelled`, `expired` | `7` (CANCELLED) | `CANCELLED` |
+| `problem` | `avizo`, `pickup_time_expired`, `stack_parcel_pickup_time_expired`, `missing`, `delay_in_delivery`, `oversized` | `8` (ERROR), `10` (REDIRECT) | `ERROR` |
+
+### Uwagi do mapowania
+- Status `problem` zbiera wszystkie nietypowe sytuacje wymagające uwagi (awizo, zagubienie, opóźnienie)
+- Surowy status (`delivery_status_raw`) zawsze zachowuje oryginalną wartość z API
+- Dla przesyłek `manual` — `delivery_status` zawsze `unknown` (brak automatycznego trackingu)
+- Mapowanie powinno być zaimplementowane jako stałe w klasie per provider (łatwe do rozszerzenia)
+
+---
+
+*Dokument utworzony: 2026-03-23*
+*Źródła: InPost ShipX API docs, Apaczka API v2 docs (ograniczony dostęp), Allegro REST API docs*