Copy page

Przewodniki integracyjne

Śledzenie przesyłek

Przesyłkę można śledzić na dwa sposoby: odpytywać endpoint tracking albo pozwolić platformie wypychać zmiany statusów na Twój endpoint. Push to lepszy domyślny wybór — bez pętli odpytywania, aktualizacje przychodzą na bieżąco.

Oba kanały używają różnych słowników statusów — zobacz Statusy odpytywania i Statusy webhooków. Nie używaj dla nich jednego wspólnego mapowania.

Odpytywanie — endpoint tracking

Pytaj po numerze listu przewozowego przewoźnika (zwróconym przez order_send):

Code
$tracking = $client->getTracking($waybillNumber);

foreach ($tracking->getEvents() as $event) {
    $event->getStatus();          // status znormalizowany, np. IN_TRANSIT
    $event->getStatusOriginal();  // surowy status przewoźnika
    $event->getDescription();
    $event->getPlace();
    $event->getUpdatedAt();       // ISO 8601 w UTC, np. 2026-07-21T08:15:00+00:00
}

Każde zdarzenie zawiera zarówno status znormalizowany (spójny między przewoźnikami), jak i oryginalny status przewoźnika. Logikę buduj na znormalizowanym; oryginalny pokazuj zespołowi wsparcia. Zdarzenia są zwracane od najnowszego.

Bez SDK: POST tracking/<waybill_number>/ — zobacz referencję API v2.

Statusy odpytywania

Status	Znaczenie
NEW	Zamówienie utworzone, paczka nie jest jeszcze u przewoźnika
PICKUP	Nadana / odebrana przez kuriera
IN_TRANSIT	W drodze — także wydana do doręczenia i czekająca w punkcie odbioru
DELIVERED	Doręczona
DELIVERED_NO_SYSTEM	Doręczona, potwierdzona poza systemem przewoźnika
EXCEPTION	Wymaga uwagi — nieudana próba doręczenia, awizo, nierozpoznany status przewoźnika
RETURNED_TO_SHIPPER	Zwrot do nadawcy (także paczki nieodebrane w terminie)
CANCELLED	Anulowana
CORRECTION	Reklamacja / korekta — w panelu widoczna jako anulowana
UNKNOWN	Nie udało się ustalić statusu

Webhooki push tracking

Wskaż platformie, dokąd wysyłać zmiany statusów — na jeden z dwóch sposobów:

• Per zamówienie — wyślij push_tracking_url razem z zamówieniem. Z SDK: OrderRequest::create()->...->setPushTrackingUrl('https://example.com/apaczka/tracking').
• Per aplikacja WebAPI — ustaw domyślny URL webhooka trackingu w ustawieniach WebAPI w panelu klienta. Dotyczy wszystkich zamówień utworzonych kluczami tej aplikacji; push_tracking_url podany w zamówieniu ma pierwszeństwo.

Platforma będzie wtedy POST-ować podpisaną notyfikację JSON na ten URL przy każdej zmianie statusu. Notyfikacja jest podpisana kluczami app_id / app_secret aplikacji WebAPI, która utworzyła zamówienie — zawsze weryfikuj podpis przed przetworzeniem (dlaczego). Z SDK:

Code
use AlsendoOne\SDK\Exception\WebhookVerificationException;
use AlsendoOne\SDK\Webhook\PushTrackingWebhook;

$webhook = new PushTrackingWebhook('your_app_id', 'your_app_secret');

try {
    $notification = $webhook->parse(file_get_contents('php://input'));
} catch (WebhookVerificationException $e) {
    http_response_code(400);   // niezgodny podpis — nie przetwarzaj
    exit;
}

foreach ($notification->getStatuses() as $status) {
    updateShipmentStatus(
        $notification->getOrderNumber(),   // id zamówienia zwrócone przez order_send
        $status->getStatus(),              // np. DELIVERED
        $status->getUpdatedAt()
    );
}

http_response_code(200);   // potwierdź odbiór notyfikacji

Payload

Code
{
  "signature": "3f1c…e9a0",
  "response": {
    "orderNumber": "123456789",
    "statuses": [
      {
        "status": "ON_THE_WAY",
        "updatedAt": "2026-10-06T00:45:00",
        "trackingOperatorStatuses": [
          {
            "status": "IT",
            "description": "In transit",
            "place": "Warszawa",
            "updatedAt": "2026-10-06T00:45:00"
          }
        ]
      }
    ]
  }
}

• orderNumber — id zamówienia w Apaczce (zwrócone przez order_send), nie numer listu przewozowego. Po nim dopasujesz notyfikację do swojego zamówienia.
• statuses[].status — status znormalizowany, zobacz Statusy webhooków.
• statuses[].trackingOperatorStatuses — oryginalne zdarzenia przewoźnika stojące za tym statusem (status, description, place, updatedAt).

Weryfikacja podpisu bez SDK

Podpis to HMAC-SHA256 z {app_id}::{json}: — ten sam schemat co przy podpisywaniu żądań, z pustą trasą i czasem wygaśnięcia — gdzie {json} to obiekt response ponownie zakodowany bez escapowania unicode, ukośników i znaków końca linii:

Code
$body = json_decode(file_get_contents('php://input'), true);

$json = json_encode(
    $body['response'] ?? null,
    JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_LINE_TERMINATORS
);
$expected = hash_hmac('sha256', sprintf('%s::%s:', $appId, $json), $appSecret);

if (!is_string($body['signature'] ?? null) || !hash_equals($expected, $body['signature'])) {
    http_response_code(400);   // niezgodny podpis — nie przetwarzaj
    exit;
}

Flagi kodowania są istotne: bez nich polskie znaki i ukośniki zostaną zakodowane inaczej i podpis nigdy się nie zgodzi.

Statusy webhooków

Webhooki mają własny zestaw statusów. Prawa kolumna to najbliższy status odpytywania.

Status webhooka	Znaczenie	Odpowiednik w odpytywaniu
NEW	Zamówienie zarejestrowane	NEW
READY_TO_SEND	Gotowa do nadania	NEW
ADVISING	—	NEW
POSTED	Nadana / przekazana przewoźnikowi	PICKUP
ON_THE_WAY	W drodze do odbiorcy	IN_TRANSIT
OUT_FOR_DELIVERY	Przekazana kurierowi do doręczenia	IN_TRANSIT
READY_TO_PICKUP	Gotowa do odbioru w punkcie	IN_TRANSIT
DELIVERED	Doręczona	DELIVERED
WAITING_FOR_PAYOUT	Doręczona, pobranie czeka na wypłatę	DELIVERED
SENT	Pobranie wypłacone	DELIVERED
AVIZO	Przesyłka awizowana	EXCEPTION
REMINDER_SENT	Wysłano przypomnienie do odbiorcy	EXCEPTION
OTHER	Nierozpoznany status przewoźnika	EXCEPTION
UNKNOWN	Status nieznany	EXCEPTION
PICKUP_EXPIRED	Nieodebrana w terminie	RETURNED_TO_SHIPPER
RETURNED	Zwrócona do nadawcy	RETURNED_TO_SHIPPER
CANCELED	Anulowana	CANCELLED
CLAIMED	Zgłoszono reklamację	CORRECTION

Uwaga na pisownię: webhook wysyła CANCELED (jedno L), odpytywanie zwraca CANCELLED. A SENT oznacza wypłatę pobrania, nie nadanie paczki.

Warto wiedzieć

• Odpowiadaj HTTP 200. Dopóki endpoint nie zwróci 200, platforma ponawia doręczenie notyfikacji; po 200 kolejna przyjdzie przy następnej zmianie statusu. Handler powinien być idempotentny.
• Push tracking jest rejestrowany tylko dla obsługiwanych przewoźników; statuses może być pustą tablicą — potwierdź ją kodem 200 i nic więcej.
• Znaczniki czasu mają format Y-m-d\TH:i:s bez offsetu, w czasie Europe/Warsaw.