README

A Laravel package for the OLC v2 customer API, built on Saloon. Create shipments, fetch labels and read tracking events.

For plain PHP projects without Laravel, use smart-dato/php-olc-sdk.

Requirements

PHP 8.3+
Laravel 10 – 13

Installation

composer require smart-dato/olc-sdk

Publish the config file:

php artisan vendor:publish --tag="olc-sdk-config"

OLC_URL=https://your-olc-host
OLC_TOKEN=your-api-token

Usage

use SmartDato\Olc\Olc;

$olc = new Olc(); // URL and token from config
$olc = new Olc(url: 'https://your-olc-host', token: 'your-token'); // or explicitly

The Olc facade resolves the same class with the configured values.

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)
);

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 / olc-sdk

Package info

Security

Fund package maintenance!

Statistics