New

Just launched: Vueblocks, a brand-new search engine for Vue packages! Explore Vueblocks →

smart-dato/asendia-sync-sdk

Laravel SDK for the Asendia Sync shipping API (parcels, labels, manifests, tracking, PUDO points, customs documents)
1,321
Install
composer require smart-dato/asendia-sync-sdk
Latest Version:0.0.4
PHP:^8.4
Laravel:12 · 13
Older releases:11
License:MIT
Last Updated:Nov 9, 2026
Links: GitHub  ·  Packagist
Maintainer: smart-dato

Asendia Sync SDK for Laravel

Latest Version on Packagist Tests

A Saloon SDK for the Asendia Sync API: parcels and their labels, manifests, tracking, PUDO points, commercial invoices and customs documents. Payloads and responses are spatie/laravel-data DTOs.

Installation

composer require smart-dato/asendia-sync-sdk
php artisan vendor:publish --tag="asendia-sync-sdk-config"
ASENDIA_SYNC_USERNAME=
ASENDIA_SYNC_PASSWORD=
ASENDIA_SYNC_CUSTOMER_ID=

The API login is the Asendia Sync portal login. customer_id is the default for tracking and the parcel/manifest lists; AsendiaSync::customers()->all() lists the ids a login may use.

Authentication

The SDK logs in with POST /api/authenticate and sends the JWT as bearer token. Asendia issues it for 24 hours; it is cached per login (cache_store, default store) until five minutes before its exp claim. A request answered with 401 drops the cached token, logs in again and is retried once.

Usage

Through the facade (config credentials) or per account:

use SmartDato\AsendiaSync\AsendiaSync;

$asendia = AsendiaSync::make([
    'username' => 'user',
    'password' => 'secret',
    'customer_id' => 'IT19050010',
    // 'base_url' => 'https://www.asendia-sync.com',
    // 'cache' => Cache::store('redis'),
]);

Parcels

use SmartDato\AsendiaSync\Data\Parcels\{AddressesData, AsendiaServiceData, CustomsInfoData, CustomsItemData, ParcelRequestData};
use SmartDato\AsendiaSync\Data\Shared\AddressData;
use SmartDato\AsendiaSync\Enums\{LabelType, Product, ReasonForExport, Service, ServiceOption};

$parcel = $asendia->parcels()->create(new ParcelRequestData(
    referenceNumber: 'OLC-1001',
    weight: 1.25, // kg, including packaging
    labelType: LabelType::Pdf,
    asendiaService: new AsendiaServiceData(
        product: Product::EpaqSelect,
        service: Service::CustomsPrepaidByRetailer,
        options: [ServiceOption::SmartgateDirect],
    ),
    addresses: new AddressesData(
        receiver: new AddressData(name: 'Peter Baer', address1: 'Bahnhofstrasse 1', postalCode: '3011', city: 'Bern', country: 'CH'),
    ),
    customsInfo: new CustomsInfoData(currency: 'EUR', items: [
        new CustomsItemData(articleDescription: 'Cotton T-shirt', quantity: 2, unitValue: 19.9, unitWeight: 0.2, harmonizationCode: '610910', originCountry: 'IT'),
    ]),
    reasonForExport: ReasonForExport::Merchandise,
));

if ($parcel->hasErrors()) {
    // Asendia accepted the parcel (202) but reports failed checks in errorMessage / errorMessages
}

$label = $asendia->parcels()->label($parcel->id); // DocumentData: contents(), contentType
$asendia->parcels()->delete($parcel->id);         // cancels the label, the parcel is not billed

update(), get(), returnLabel(), customsDocument(), commercialInvoice() and list() work alike. Unset optional fields are left out of the payload. ParcelFormat (B/N/L/XL) is chosen by the shipper; e-PAQ Select and Elite may omit it.

Manifests, tracking, PUDO, documents

$manifest = $asendia->manifests()->create([$parcel->id]);
$asendia->manifests()->createForTrackingNumbers(['99CH123456789012']);
$asendia->manifests()->document($manifest->id);

$events = $asendia->tracking()->get('99CH123456789012');           // list<TrackingEventData>
$trackings = $asendia->tracking()->many($trackingNumbers);          // batches of 100
$events[0]->milestone();                                            // ?TrackingEventCode

$asendia->pudo()->byAddress(new PudoSearchAddressData(...), [new PudoServiceData('SUP00138')]);
$asendia->pudo()->byCountry('FR', pageNumber: 1, pageSize: 50);

$asendia->documents()->createCommercialInvoice(new CommercialInvoiceData(...)); // PDF
$asendia->documents()->uploadCustomsDocument(new CustomsDocumentData(...), $pdf);

Lists page from 0 (page, size); the total is in lastResponse->header('X-Total-Count'). PUDO searches page from 1.

Errors

Failed requests throw AsendiaSyncApiException (a Saloon RequestException), or one of ValidationException (400, with fieldErrors and, for manifests, alreadyManifestedParcels), NotFoundException (404) and RateLimitExceededException (429). The message lists the reasons.

A booking the last mile carrier rejects ("Unknown Carrier Error") still leaves a parcel in error state at Asendia; its id is $exception->parcelId. Delete it, or it lingers.

Asendia Sync requires asendiaService.format for every product, and Swiss Post needs an articleNumber on every customs item.

Not covered: POST /api/logtrade/transport-instructions, which is meant for LogTrade.

Testing

composer test
composer analyse

License

The MIT License (MIT). Please see License File for more information.

Related Packages

smart-dato/dhl-parcel-sdk

Laravel SDK for the DHL Parcel DE Shipping v2 API

10,117 1
smart-dato/dhl-unified-sdk

Laravel SDK for the DHL developer portal APIs authenticated with a DHL-API-Key (...

5,111 0
smart-dato/dhl-parcel-returns-sdk

Laravel SDK for the DHL Parcel DE Returns API

9,395 0
crescat-io/saloon-sdk-generator

Simplified SDK Scaffolding for Saloon

36,596 138
smart-dato/eushipments

EuShipments Laravel SDK

10,992 0

Version History

Version Released PHP Laravel License
0.0.4 ^8.4 ^12.0||^13.0 MIT
0.0.3 ^8.4 ^12.0||^13.0 MIT
0.0.2 ^8.4 ^12.0||^13.0 MIT
0.0.1 ^8.4 ^11.0||^12.0||^13.0 MIT