Copy page

Przewodniki integracyjne

Cykl życia zamówienia

Zamówienie przesyłki przechodzi te same etapy niezależnie od przewoźnika:

service_structure → [order_valuation] → order_send → waybill / dispatch_code / turn_in → opcjonalnie cancel_order

order_valuation jest opcjonalne — zobacz krok 2. Poniższe przykłady używają SDK PHP; każdy etap podaje nazwę metody API, więc przepływ mapuje się 1:1 na surowe żądania z kopertą z dowolnego języka. Pełne kształty payloadów znajdziesz w referencji API v2.

1. Wybierz usługę — service_structure

Pobierz usługi dostępne na Twoim koncie i pozwól użytkownikowi (albo swojej konfiguracji) wybrać — nie hardkoduj listy:

Code
$structure = $client->getServiceStructure();
$services  = $structure->getServices();      // przewoźnicy + id usług
$packages  = $structure->getPackageTypes();  // PACZKA, PALETA, ...
$options   = $structure->getOptions();       // pobranie, ubezpieczenie, ...

2. (Opcjonalnie) Wyceń przesyłkę — order_valuation

Pobierz wycenę przed utworzeniem zamówienia. Ten sam obiekt zamówienia działa dla wyceny i utworzenia:

Code
use AlsendoOne\SDK\DTO\Address;
use AlsendoOne\SDK\DTO\Request\OrderRequest;
use AlsendoOne\SDK\DTO\Request\PickupRequest;
use AlsendoOne\SDK\DTO\Request\ShipmentRequest;
use AlsendoOne\SDK\Type\Service;

$service = Service::from(Service::DpdCourier);

$order = OrderRequest::create()
    ->setService($service)
    ->setSenderAddress(new Address(/* ... */))
    ->setReceiverAddress(new Address(/* ... */))
    ->addShipment(new ShipmentRequest('PACZKA', 2.5, 40, 30, 20))
    ->setPickup(new PickupRequest('COURIER', '2026-08-19', '10:00', '16:00'));

$valuation = $client->getValuation($order);

foreach ($valuation->getPriceTable() as $price) {
    // Ceny są w groszach (1 PLN = 100 gr)
    printf("Usługa %d: %.2f PLN brutto\n",
        $price->getServiceId(), $price->getPriceGross() / 100);
}

2b. (Opcjonalnie) Wyceń ponownie finalny payload — order_valuation

Jeśli po wcześniejszej wycenie zmieniłeś zamówienie — dodałeś odbiór, usługi dodatkowe, dane celne albo punkt — uruchom order_valuation ponownie na finalnym payloadzie przed wysłaniem. Zmiany na poziomie zamówienia mogą zmienić cenę, więc wcześniejsza wycena bywa nieaktualna:

• odbiór kurierski zamówiony na ten sam dzień może być objęty dopłatą,
• usługi dodatkowe / pobranie podnoszą koszt,
• trasa przez punkt albo obsługa celna mogą zmienić obowiązującą taryfę.

Code
// $order zawiera teraz wszystko, co zaraz wyślesz (usługa, odbiór, opcje, dane celne…)
$finalPrice = $client->getValuation($order)->getPriceForService($service);
// Pokaż/zapisz potwierdzoną cenę, potem w kroku 3 wyślij *ten sam* $order.

3. Utwórz zamówienie — order_send

Code
$created = $client->sendOrder($order);

$orderId = $created->getId();
$created->getWaybillNumber();   // numer śledzenia przewoźnika
$created->getTrackingUrl();     // publiczny link do śledzenia
$created->getStatus();          // np. NEW

Obiekt pickup decyduje, jak paczka trafi do przewoźnika (odbiór kurierski vs. własne nadanie) — szczegóły mają osobny przewodnik: Typy odbioru.

4. Dokumenty — waybill, dispatch_code, turn_in

Każdy dokument jest zwracany w base64:

Code
// Etykieta (PDF) — wymagana na paczce
$waybill = $client->getWaybill($orderId);
file_put_contents('label.pdf', base64_decode($waybill->getWaybill()));

// Kod nadania/zwrotu — część przewoźników wymaga go przy nadaniu;
// przewoźnicy, którzy go nie wydają, nie zwracają kodu
$dispatch = $client->getDispatchCode($orderId);

// Zbiorcze potwierdzenie nadania paczek przekazanych jednemu kurierowi
$turnIn = $client->getTurnIn([$orderId, $anotherOrderId]);

5. Śledź przesyłkę — tracking

Odpytuj getTracking($waybillNumber) albo odbieraj notyfikacje push — zobacz przewodnik śledzenia.

6. W razie potrzeby anuluj — cancel_order

Code
$client->cancelOrder($orderId);   // rzuca ApiException, gdy nie można anulować

Zamówienie można anulować tylko do momentu przejęcia paczki przez przewoźnika; później API zwraca kopertę błędu. Pamiętaj, że anulowane zamówienie przestaje też udostępniać dokumenty — waybill i turn_in zwracają dla niego błąd API, więc pobierz wszystko, czego potrzebujesz, przed anulowaniem.

Późniejszy wgląd w zamówienia

Code
$order  = $client->getOrder($orderId);        // pełne szczegóły (w tym price / price_gross, w groszach)
$orders = $client->getOrders(page: 1, limit: 25);  // lista z paginacją, max 25/stronę

---

Zobacz też: Wybór usługi z oferty · Typy odbioru · Śledzenie · Dobre praktyki