Integration guides

Order lifecycle

A shipment order goes through the same stages regardless of carrier:

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

order_valuation is optional — see step 2. Examples below use the PHP SDK; each stage names the underlying API method, so the flow maps 1:1 to raw envelope requests from any language. Full payload shapes live in the API v2 reference.

Not sure which service to use?

If you don't pass a fixed service_id but want to pick from the services that can actually carry the parcel, start with Choosing a service from the offer and come back here at order_send.

1. Pick a service — `service_structure`

Fetch the services available on your account and let the user (or your config) pick one — don't hardcode the list:


Code
$structure = $client->getServiceStructure();
$services  = $structure->getServices();      // carriers + service ids
$packages  = $structure->getPackageTypes();  // PACZKA, PALETA, ...
$options   = $structure->getOptions();       // COD, insurance, ...

2. (Optional) Price the shipment — `order_valuation`

Get a quote before committing. The same order object works for valuation and creation:


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) {
    // Prices are in groszy (1 PLN = 100 gr)
    printf("Service %d: %.2f PLN gross\n",
        $price->getServiceId(), $price->getPriceGross() / 100);
}

Skipping valuation entirely?

Many integrations create orders without ever calling order_valuation — they know the service and take the price as invoiced. That's fine. Just remember the price is only settled at creation: order-level changes and surcharges (see step 2b) mean an assumed price can differ. Read the real amount back from getOrder() / getOrders() (price / price_gross, in groszy) after order_send.

2b. (Optional) Re-price the final payload — `order_valuation`

If you changed the order after an earlier quote — added a pickup, options, customs or a point — re-run order_valuation on the final payload before sending. Order-level changes can move the price, so the earlier quote may be stale:

a courier pickup scheduled for the same day may be surcharged,
additional services / COD add cost,
point routing or customs handling can change the applicable tariff.


Code
// $order now carries everything you're about to send (service, pickup, options, customs…)
$finalPrice = $client->getValuation($order)->getPriceForService($service);
// Show/store the confirmed price, then send the *same* $order in step 3.

Same object, no surprises

Quote what you are about to send — valuate the final $order, then pass that exact object to order_send.

3. Create the order — `order_send`


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

$orderId = $created->getId();
$created->getWaybillNumber();   // carrier tracking number
$created->getTrackingUrl();     // public tracking link
$created->getStatus();          // e.g. NEW

order_send is not idempotent — a retried timeout can create a duplicate order. See best practices.

The pickup object decides how the parcel reaches the carrier (courier pickup vs. your own drop-off) — the details have their own guide: Pickup types.

4. Documents — `waybill`, `dispatch_code`, `turn_in`

Every document is returned base64-encoded:


Code
// Shipping label (PDF) — required on the parcel
$waybill = $client->getWaybill($orderId);
file_put_contents('label.pdf', base64_decode($waybill->getWaybill()));

// Dispatch/return code — some carriers require it at drop-off;
// carriers that don't issue one return no code
$dispatch = $client->getDispatchCode($orderId);

// Turn-in confirmation for a batch of parcels handed to one courier
$turnIn = $client->getTurnIn([$orderId, $anotherOrderId]);

5. Track it — `tracking`

Poll getTracking($waybillNumber) or receive push notifications — see the Tracking guide.

6. Cancel if needed — `cancel_order`


Code
$client->cancelOrder($orderId);   // throws ApiException if not cancellable

Orders can be cancelled only until the carrier takes over the parcel; after that the API returns an error envelope. Note that a cancelled order also stops serving its documents — waybill and turn_in return an API error for it, so download anything you need before cancelling.

Inspecting orders later


Code
$order  = $client->getOrder($orderId);        // full detail (incl. price / price_gross, in groszy)
$orders = $client->getOrders(page: 1, limit: 25);  // paginated list, max 25/page

Last modified on October 5, 2026

Authentication Choosing a service from the offer

Integration guides

Order lifecycle

A shipment order goes through the same stages regardless of carrier:

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

Not sure which service to use?

If you don't pass a fixed service_id but want to pick from the services that can actually carry the parcel, start with Choosing a service from the offer and come back here at order_send.

1. Pick a service — `service_structure`

Fetch the services available on your account and let the user (or your config) pick one — don't hardcode the list:


Code
$structure = $client->getServiceStructure();
$services  = $structure->getServices();      // carriers + service ids
$packages  = $structure->getPackageTypes();  // PACZKA, PALETA, ...
$options   = $structure->getOptions();       // COD, insurance, ...

2. (Optional) Price the shipment — `order_valuation`

Get a quote before committing. The same order object works for valuation and creation:


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) {
    // Prices are in groszy (1 PLN = 100 gr)
    printf("Service %d: %.2f PLN gross\n",
        $price->getServiceId(), $price->getPriceGross() / 100);
}

Skipping valuation entirely?

2b. (Optional) Re-price the final payload — `order_valuation`

a courier pickup scheduled for the same day may be surcharged,
additional services / COD add cost,
point routing or customs handling can change the applicable tariff.


Code
// $order now carries everything you're about to send (service, pickup, options, customs…)
$finalPrice = $client->getValuation($order)->getPriceForService($service);
// Show/store the confirmed price, then send the *same* $order in step 3.

Same object, no surprises

Quote what you are about to send — valuate the final $order, then pass that exact object to order_send.

3. Create the order — `order_send`


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

$orderId = $created->getId();
$created->getWaybillNumber();   // carrier tracking number
$created->getTrackingUrl();     // public tracking link
$created->getStatus();          // e.g. NEW

order_send is not idempotent — a retried timeout can create a duplicate order. See best practices.

The pickup object decides how the parcel reaches the carrier (courier pickup vs. your own drop-off) — the details have their own guide: Pickup types.

4. Documents — `waybill`, `dispatch_code`, `turn_in`

Every document is returned base64-encoded:


Code
// Shipping label (PDF) — required on the parcel
$waybill = $client->getWaybill($orderId);
file_put_contents('label.pdf', base64_decode($waybill->getWaybill()));

// Dispatch/return code — some carriers require it at drop-off;
// carriers that don't issue one return no code
$dispatch = $client->getDispatchCode($orderId);

// Turn-in confirmation for a batch of parcels handed to one courier
$turnIn = $client->getTurnIn([$orderId, $anotherOrderId]);

5. Track it — `tracking`

Poll getTracking($waybillNumber) or receive push notifications — see the Tracking guide.

6. Cancel if needed — `cancel_order`


Code
$client->cancelOrder($orderId);   // throws ApiException if not cancellable

Inspecting orders later


Code
$order  = $client->getOrder($orderId);        // full detail (incl. price / price_gross, in groszy)
$orders = $client->getOrders(page: 1, limit: 25);  // paginated list, max 25/page

Last modified on October 5, 2026

Authentication Choosing a service from the offer

1. Pick a service — service_structure

2. (Optional) Price the shipment — order_valuation

2b. (Optional) Re-price the final payload — order_valuation

3. Create the order — order_send

4. Documents — waybill, dispatch_code, turn_in

5. Track it — tracking

6. Cancel if needed — cancel_order

Inspecting orders later

1. Pick a service — service_structure

2. (Optional) Price the shipment — order_valuation

2b. (Optional) Re-price the final payload — order_valuation

3. Create the order — order_send

4. Documents — waybill, dispatch_code, turn_in

5. Track it — tracking

6. Cancel if needed — cancel_order

Inspecting orders later

1. Pick a service — `service_structure`

2. (Optional) Price the shipment — `order_valuation`

2b. (Optional) Re-price the final payload — `order_valuation`

3. Create the order — `order_send`

4. Documents — `waybill`, `dispatch_code`, `turn_in`

5. Track it — `tracking`

6. Cancel if needed — `cancel_order`

1. Pick a service — `service_structure`

2. (Optional) Price the shipment — `order_valuation`

2b. (Optional) Re-price the final payload — `order_valuation`

3. Create the order — `order_send`

4. Documents — `waybill`, `dispatch_code`, `turn_in`

5. Track it — `tracking`

6. Cancel if needed — `cancel_order`