README

A framework-agnostic PHP client for the OLC v2 customer API, built on Saloon. Create shipments, fetch labels and return labels, and read tracking events.

For Laravel projects, use smart-dato/olc-sdk.

Requirements

PHP 8.4+

Installation

composer require smart-dato/php-olc-sdk

Usage

Both the base URL and the API token are required:

use SmartDato\Olc\Olc;

$olc = new Olc(
    url: 'https://your-olc-host',
    token: 'your-api-token',
);

Create a shipment

use SmartDato\Olc\DataObjects\AddressObject;
use SmartDato\Olc\DataObjects\ContentObject;
use SmartDato\Olc\DataObjects\ContentObjectCollection;
use SmartDato\Olc\DataObjects\ParcelObject;
use SmartDato\Olc\DataObjects\ParcelObjectCollection;
use SmartDato\Olc\DataObjects\ShipmentObject;

$shipment = new ShipmentObject(
    shipmentType: 'PARCEL',
    shippingService: 'EC',
    pickupAddress: new AddressObject(warehouse: 'WH_1'),
    deliveryAddress: new AddressObject(
        personName: 'John Doe',
        companyName: 'Acme Inc.',
        street: '123 Main St',
        city: 'Anytown',
        zipcode: '12345',
        countryCode: 'DE',
    ),
    parcels: (new ParcelObjectCollection)
        ->add(new ParcelObject(weight: 2.5, width: 10, height: 10, length: 10))
        ->add(new ParcelObject(weight: 1.23)),
    reference_1: 'order-1001',
    content: (new ContentObjectCollection)
        ->add(new ContentObject(
            description: 'Cotton shirt',
            hsCode: '6109.10',
            quantity: 2,
            unitValue: 12.50,
            netWeight: 0.2,
            manufacturerCountry: 'CN',
            currency: 'EUR',
            invoiceNumber: 'INV-1',
            invoiceDate: '2026-09-23',
        )),
);

$data = $olc->createShipment($shipment);

shipmentType and shippingService must be keys configured for your OLC account; PARCEL and EC are the values used in the tests.

ShipmentObject also accepts reference_2, comment, products (ProductObject — delivery options such as b2cDelivery or scheduledDelivery), cashOnDelivery (CashOnDeliveryObject), insurance (amount) and carrierObject (CarrierObject). Null values are left out of the request.

content is optional and describes the goods, e.g. for customs. Each ContentObject maps to one item; every field is optional and only the ones you set are sent. invoiceDate, invoiceNumber and invoiceImage are grouped into an invoice object.

createShipment() returns the data field of the response.

Labels and tracking

Both look a shipment up by its OLC shipment key by default:

$label = $olc->getLabel('OLS000000000001');          // the `file` field of the response
$events = $olc->getTrackingEvents('OLS000000000001'); // the decoded JSON response

To look up by one of your own references, send the request through the connector with a ShipmentReferenceTyp (KEY, REFERENCE1, REFERENCE2):

use SmartDato\Olc\Enums\ShipmentReferenceTyp;
use SmartDato\Olc\Requests\GetShipmentLabelRequest;

$response = $olc->connector->send(
    new GetShipmentLabelRequest('order-1001', ShipmentReferenceTyp::REFERENCE1)
);

Return labels

use SmartDato\Olc\Requests\GetReturnShipmentLabelRequest;

$response = $olc->connector->send(new GetReturnShipmentLabelRequest('OLS000000000001'));

Using the connector directly

Every request can also be sent through OlcConnector, which returns the raw Saloon Response:

use SmartDato\Olc\OlcConnector;
use SmartDato\Olc\Requests\CreateShipmentRequest;

$connector = new OlcConnector(url: 'https://your-olc-host', token: 'your-api-token');

$response = $connector->send(new CreateShipmentRequest($shipment));

Errors

createShipment(), getLabel() and getTrackingEvents() throw GenericOlcException with the response body when OLC returns an error status.

Testing

composer test

The suite replays recorded responses with Saloon's MockClient, so it needs no credentials or network access.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

smart-dato / php-olc-sdk

Package info

Security

Fund package maintenance!

Statistics