# 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*