# Słownik i przepływ statusów zamówień

Generowane na żywo z wdrożonego kodu (OrdersStatusInput / OrdersService) pod adresem https://api.superlabel.ca/api/documentation/order-status-flow?lang=pl — pobierz ponownie w dowolnym momencie, aby uzyskać najnowszą wersję.

## Słownik statusów (`orders_status_id`)

| id | key |
|---|---|
| 1 | need_update_address |
| 2 | new_order |
| 3 | waiting_to_plan |
| 4 | planning |
| 5 | already_planned |
| 6 | plan_failed |
| 7 | already_pickup |
| 8 | successful |
| 9 | redelivered_later |
| 10 | need_rescheduled |
| 11 | rescheduled |
| 12 | cancelled |
| 14 | already_pickup |
| 16 | need_to_pick_up |
| 17 | waiting_for_self_pickup |
| 18 | self_pickup_completed |
| 19 | return_to_customer |
| 20 | out_for_delivery |
| 21 | out_for_pickup |
| 22 | partial_received |
| 23 | partial_delivered |
| 24 | partial_pickuped |
| 25 | hand_off |
| 26 | review |
| 27 | destroyed |
| 28 | need_convert_to_3rd_party_label |
| 29 | in_transit |
| 30 | package_lost |
| 31 | package_damaged |
| 32 | waiting_customer_options |
| 33 | handed_over_to_the_third_party_carrier |
| 34 | waiting_batch_pickup |
| 35 | payment_required |
| 36 | bulk_transshipment_pending |
| 37 | bulk_transshipment_in_transit |
| 38 | bulk_transshipment_pending_inbound |
| 39 | inbound_scan_required |
| 40 | rejected_by_recipient |
| 41 | package_outbound |
| 42 | waiting_for_quote |
| 43 | waiting_third_party_handover |
| 44 | waiting_for_assignment |
| 45 | start_pickup |
| 46 | start_delivery |

Kotwice semantyczne: out_for_delivery=20, successful=8, delivery failed=10 (need_rescheduled) / 9 (redelivered_later), rejected_by_recipient=40, cancelled=12, redelivery=11 (rescheduled).

Statusy końcowe: cancelled(12), waiting_for_self_pickup(17), waiting_customer_options(32).

## Słownik zdarzeń śledzenia (`status_code` / `tracking_event_key`)

Generowane z TrackingEvent::EVENT_KEY_MAPPING — tych samych stałych, które środowisko wykonawcze umieszcza w każdym ładunku śledzenia i webhooku. Klucze są stabilne: są wyłącznie dodawane, nigdy nie są zmieniane ani ponownie wykorzystywane.

| status_code | key |
|---|---|
| 100 | information_submitted |
| 110 | booking_confirmed |
| 120 | awaiting_pickup |
| 200 | pushed_successful |
| 201 | pushed_failed |
| 300 | received |
| 301 | arrival_scan |
| 400 | planned |
| 401 | removed_from_route |
| 402 | route_cancelled |
| 403 | cancelled |
| 410 | rider_assigned |
| 411 | rider_reassigned |
| 412 | rider_assignment_cancelled |
| 430 | in_transit |
| 431 | on_hold |
| 434 | collection_on_hold |
| 432 | customs_clearance |
| 433 | loaded |
| 435 | facility_received |
| 436 | arrived_at_facility |
| 450 | start_delivery |
| 500 | deliver_success |
| 501 | need_rescheduled |
| 502 | redelivered_later |
| 503 | not_delivered |
| 504 | partial_deliver_success |
| 460 | start_pickup |
| 470 | at_device |
| 471 | device_picked_up |
| 472 | device_expired |
| 473 | device_removed |
| 510 | pickuped |
| 512 | repickup_later |
| 513 | not_pickuped |
| 600 | return_to_sender |
| 700 | rejected_by_recipient |
| 800 | package_outbound |

## Główny przepływ doręczenia

```mermaid
stateDiagram-v2
    [*] --> new_order: zamówienie utworzone
    new_order --> waiting_to_plan
    waiting_to_plan --> planning
    planning --> already_planned
    planning --> plan_failed
    plan_failed --> waiting_to_plan: ponowne planowanie
    already_planned --> out_for_delivery: kierowca rozpoczyna trasę
    out_for_delivery --> successful: doręczono (POD)
    out_for_delivery --> need_rescheduled: doręczenie nieudane
    out_for_delivery --> redelivered_later: ponowna próba na tej samej trasie
    out_for_delivery --> rejected_by_recipient: odmowa przyjęcia
    redelivered_later --> successful
    redelivered_later --> need_rescheduled
    need_rescheduled --> rescheduled: ponownie zakolejkowane
    rescheduled --> waiting_to_plan
    successful --> [*]
```

## Korekty przyjęcia zwrotnego (generowane z ALLOWED_RECEIVE_STATUS_MAP)

Stosowane, gdy paczka zostaje fizycznie przyjęta ponownie. Krawędź `successful --> rescheduled` to przypadek „status doręczono może zostać cofnięty", który integratorzy muszą obsłużyć: traktuj najnowsze zdarzenie (najwyższe id) jako rozstrzygające. Gdy koperta ładunku jest włączona (webhook_payload_envelope=1), takie zdarzenia zawierają również `is_correction: true`.

```mermaid
stateDiagram-v2
    in_transit --> new_order: przyjęto z powrotem
    package_outbound --> new_order: przyjęto z powrotem
    need_to_pick_up --> new_order: przyjęto z powrotem
    waiting_batch_pickup --> new_order: przyjęto z powrotem
    already_pickup --> new_order: przyjęto z powrotem
    out_for_pickup --> new_order: przyjęto z powrotem
    partial_received --> new_order: przyjęto z powrotem
    partial_pickuped --> new_order: przyjęto z powrotem
    already_pickup --> already_pickup: przyjęto z powrotem
    waiting_customer_options --> waiting_customer_options: przyjęto z powrotem
    out_for_delivery --> rescheduled: przyjęto z powrotem
    hand_off --> rescheduled: przyjęto z powrotem
    redelivered_later --> rescheduled: przyjęto z powrotem
    need_rescheduled --> rescheduled: przyjęto z powrotem
    rescheduled --> rescheduled: przyjęto z powrotem
    successful --> rescheduled: przyjęto z powrotem
    handed_over_to_the_third_party_carrier --> successful: przyjęto z powrotem
    bulk_transshipment_in_transit --> new_order: przyjęto z powrotem
    bulk_transshipment_pending_inbound --> new_order: przyjęto z powrotem
    inbound_scan_required --> new_order: przyjęto z powrotem
    package_damaged --> review: przyjęto z powrotem
    package_lost --> review: przyjęto z powrotem
```

## Zasady anulowania

- Statusy możliwe do anulowania przez API: need_update_address(1), new_order(2), already_planned(5), redelivered_later(9), need_rescheduled(10), rescheduled(11), cancelled(12), plan_failed(6), status_15(15), already_pickup(7), already_pickup(14), need_to_pick_up(16), waiting_for_self_pickup(17), self_pickup_completed(18), return_to_customer(19), out_for_delivery(20), out_for_pickup(21), partial_received(22), partial_delivered(23), partial_pickuped(24), hand_off(25), review(26), destroyed(27), need_convert_to_3rd_party_label(28), in_transit(29), inbound_scan_required(39), payment_required(35).
- Dodatkowo możliwe do anulowania wyłącznie przez konta klientów/pracowników: successful(8).
- Anulowane zamówienia są wykluczane z wyszukiwań śledzenia i nigdy nie są automatycznie przywracane.

## Słowniki przyczyn niepowodzenia / odmowy

1. Znormalizowane kody incydentów (stabilne, wyłącznie dodawane): `incident_reason` w zdarzeniach śledzenia — kategorie carrier_* / retailer_* / consignee_* / customs_* / weather / other.
2. Konfigurowalne przez sprzedawcę przyczyny zwrotu (dowolny tekst, mogą się zmieniać): udostępniane jako `reason` w ładunkach śledzenia.

Integratorzy powinni rozgałęziać logikę na podstawie (1), a (2) jedynie wyświetlać.