Project-Pro/orderPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
orderPRO/DOCS/SHIPMENT_TRACKING_STATUSES.md
Jacek Pyziak 228c0e96cf 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

8.5 KiB
Raw Permalink Blame History

Statusy śledzenia przesyłek — dokumentacja API przewoźników

Spis treści

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

Reference in New Issue View Git Blame Copy Permalink