Copy page

Przewodniki integracyjne

Wybór usługi z oferty

Większość integracji z góry wie, której usługi przewoźnika chce, i przekazuje stały service_id. Gdy tak nie jest — gdy chcesz pokazać klientowi (albo własnemu silnikowi reguł) zbiór usług, które faktycznie mogą przewieźć tę paczkę, i jedną z nich wybrać — najpierw wyceń przesyłkę we wszystkich usługach, a potem wybieraj według pełnego zestawu ograniczeń, nie samej ceny.

Najtańsza wycena to często zły wybór: usługa punkt–punkt potrzebuje identyfikatora automatu, międzynarodowa — danych celnych, część usług wymaga zamówionego odbioru kurierskiego. Usługa, której wymagań nie spełnisz, wywali się przy order_send, nie przy wycenie.

Ten przewodnik obejmuje początek przepływu. Wszystko po utworzeniu zamówienia (etykieta, śledzenie, anulowanie) jest identyczne jak w Cyklu życia zamówienia — ta strona zastępuje tylko sposób wyboru usługi.

order_valuation (bez service_id) → service_structure (mapowanie wymagań) → uzupełnienie payloadu (odbiór / punkt / cło) → order_send → etykieta / śledzenie / … (zobacz Cykl życia zamówienia)

Przykłady używają SDK PHP; każdy krok podaje nazwę metody API, więc przepływ mapuje się 1:1 na surowe żądania z kopertą z dowolnego języka.

1. Wyceń we wszystkich usługach — order_valuation bez usługi

Zbuduj zamówienie na neutralnym szkielecie — odbiór SELF, bez punktu, bez cła — i pomiń usługę. order_valuation zwróci wtedy price_table z każdą usługą, która może przewieźć tę paczkę.

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

$shipment = new ShipmentRequest('PACZKA', 2.5, 40, 30, 20); // kg, cm

$order = OrderRequest::create()
    ->setSenderAddress(new Address(/* ... */))
    ->setReceiverAddress(new Address(/* ... */))
    ->addShipment($shipment)
    ->setPickup(new PickupRequest('SELF'));   // neutralnie — bez setService()

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

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

Bez SDK — to samo wywołanie, bez service_id w payloadzie:

Code
--data-urlencode 'request={"order":{"address":{"sender":{...},"receiver":{...}},"pickup":{"type":"SELF"},"shipment":[{"dimension1":40,"dimension2":30,"dimension3":20,"weight":2.5,"is_nstd":0}]}}'
# POST order_valuation/  → response.price_table, jeden wpis na service_id, kwoty w groszach

2. Zmapuj ofertę na service_structure — sprawdź wymagania

price_table mówi, kto może przewieźć paczkę i za ile. service_structure mówi, czego każda usługa wymaga. Połącz je po service_id. Słownik czytaj z cache (odświeżaj mniej więcej raz dziennie), zamiast wołać go przy każdej wycenie — zobacz Dobre praktyki.

Code
$structure = $client->getServiceStructure();

$byId = [];
foreach ($structure->getServices() as $svc) {
    $byId[(int) $svc['service_id']] = $svc;
}

$offer = [];
foreach ($valuation->getPriceTable() as $price) {
    $svc = $byId[$price->getServiceId()] ?? null;
    if ($svc === null) {
        continue; // wycenione, ale nieobecne w aktualnym słowniku — pomiń
    }

    $offer[] = [
        'service_id'     => $price->getServiceId(),
        'name'           => $svc['name'],
        'supplier'       => $svc['supplier'],
        'price_gross'    => $price->getPriceGross(),   // grosze
        'domestic'       => (int) $svc['domestic'],        // 1 krajowa / 0 międzynarodowa
        'pickup_courier' => (int) $svc['pickup_courier'],  // 0 niedostępny / 1 dostępny / 2 wymagany
        'door_to_door'   => (int) $svc['door_to_door'],
        'door_to_point'  => (int) $svc['door_to_point'],
        'point_to_point' => (int) $svc['point_to_point'],
        'point_to_door'  => (int) $svc['point_to_door'],
    ];
}

Co każda flaga oznacza dla payloadu, który zbudujesz w kroku 3:

Warunek usługi (z service_structure)	Co musisz dodać przed order_send
pickup_courier = 2 (kurier wymagany)	pickup.type = COURIER + date / hours_from / hours_to — okno wybierz z pickup_hours
pickup_courier = 0 (kurier niedostępny)	tylko SELF / nadanie własne — bez odbioru kurierskiego
trasa przez punkt (door_to_point / point_to_point / point_to_door = 1)	foreign_address_id z points/{type}/ po właściwej stronie (nadawca i/lub odbiorca)
domestic = 0 (międzynarodowa)	cło: customs_data per pozycja przesyłki (+ blok customs na poziomie zamówienia, gdy usługa go wymaga)
pobranie / usługi dodatkowe	sprawdź options w słowniku oraz option_cod / option_send / option_deliver na wybranym punkcie

3. Uzupełnij payload dla wybranej usługi

Po wyborze ustaw usługę i dodaj tylko te pola, których ta usługa potrzebuje.

Code
use AlsendoOne\SDK\DTO\Request\CustomsDataRequest;
use AlsendoOne\SDK\DTO\Request\PickupRequest;
use AlsendoOne\SDK\Type\Service;

$serviceId = /* Twój wybór z $offer */;
$svc       = $byId[$serviceId];
$service   = Service::from($serviceId);

$order->setService($service);

// Kurier wymagany → zamów odbiór w dostępnym oknie
if ((int) $svc['pickup_courier'] === 2) {
    $days = $client->getPickupHours($senderPostalCode, $service)->getHours();
    $day  = reset($days);
    $order->setPickup(new PickupRequest('COURIER', $day->getDate(), '09:00', '15:00'));
}

// Trasa przez punkt → dołącz punkt przez foreign_address_id u odbiorcy
// (id punktu weź z points/<type>/). Address jest niemutowalny — zbuduj nowy.
if ((int) $svc['point_to_point'] === 1 || (int) $svc['door_to_point'] === 1) {
    $order->setReceiverAddress(new Address(
        name: 'Jan Kowalski',
        phone: '+48600000000',
        email: '[email protected]',
        postalCode: '00-001',
        city: 'Warszawa',
        countryCode: 'PL',
        foreignAddressId: $pointId,          // np. id automatu InPost
    ));
}

// Międzynarodowa → zadeklaruj cło per pozycja
if ((int) $svc['domestic'] === 0) {
    $shipment->addCustomsData(new CustomsDataRequest(
        'Cotton T-shirt', 3, 1550, 1, '6109100010', 'PL' // opis, ilość, cena jedn. (gr), waga, kod HS, pochodzenie
    ));
}

Blok customs na poziomie zamówienia (content_type, EORI_number, documents_form, documents) nie ma jeszcze typowanego buildera. Jeśli usługa go wymaga, zamień zamówienie przez toArray(), dodaj blok i przekaż tablicę do sendOrder() — przyjmuje obie formy.

Uzupełnienie zamówienia może zmienić jego cenę — jeśli pokazałeś klientowi pierwszą wycenę, wyceń finalny payload ponownie przed wysłaniem (zobacz Cykl życia zamówienia → krok 2b).

4. Utwórz zamówienie — order_send

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

$created->getId();            // id zamówienia Apaczka
$created->getWaybillNumber(); // numer śledzenia przewoźnika
$created->getStatus();        // np. NEW

5. Dalej jak zwykle

Od tego miejsca przepływ jest identyczny jak w Cyklu życia zamówienia: pobierz etykietę, opcjonalnie kod nadania / potwierdzenie zbiorcze, potem śledź przesyłkę (Śledzenie). Anulowanie i wgląd w zamówienia bez zmian.

---

Zobacz też: Cykl życia zamówienia · Typy odbioru · Śledzenie · Dobre praktyki · Podpisywanie żądań (HMAC)