Download the PHP package smart-dato/cbl-logistica-sdk without Composer

CBL Logistica SDK

Fluent PHP SDK for the CBL Logistica carrier web service, built on Saloon and spatie/laravel-data: shipment registration with ZPL labels, day confirmation, deletion, tracking and proof of delivery.

Coverage

ShipmentStatus/Get and ShipmentPod/Get are not modelled: despite their names they return a daily token, exactly like TokenAuth/Get.

Requirements

• PHP ^8.4
• Laravel ^11.0 || ^12.0 || ^13.0

Installation

Optionally publish the config file:

It holds endpoints, HTTP options and the token cache store. Credentials are passed per call (see below), so the credentials block is only a single-account convenience for standalone use.

Getting started

Credentials are per call, and the package holds no account state — one application can serve any number of CBL accounts, including several accounts of the same carrier:

withCredentials() returns a configured clone, so the container singleton is never mutated and two accounts never share a connector, a resource or a cached token:

You never deal with the daily token. CBL wants it in the body of every request; the package fetches it on first use, caches it until midnight under a key derived from the whole credential set, and injects it into each payload.

Outside Laravel, new \SmartDato\CblLogistica\CblLogistica() works the same way.

Create a shipment

The result carries the labels and the errors together — CBL reports business failures inside an HTTP 200 response, so nothing is thrown for a rejected shipment:

Labels are returned untouched. Rendering them is the caller's job — pair this with smart-dato/zpl or smart-dato/labelary.

Registering packages over several calls

A shipment declares its total package count up front, and the packages may arrive across several create() calls that reuse one clientReference — the flow CBL's own samples call "half way". Each call repeats numPackages and sends only the packages it is registering:

Both calls return the same carrierReference, and each returns labels for only the packages that call registered. The shipment sits at pending until the declared count is complete, then moves to closed and waits for confirmation.

Accounts without day confirmation cannot do this: there, a mismatch between numPackages and the packages sent is a package-count error rather than a part-registered shipment.

A shipment cannot be modified

Only the package count can change, and only if your account allows it. Every other field is fixed once sent — to correct an unconfirmed shipment, delete it and create it again:

Units and limits

• Weight in kilograms (max 999999), lengths in metres (max 999.99), volume in cubic metres (max 99.99). Exceeding one is a warning (code 105), not an error.
• Omit the shipment weight/volume totals and CBL derives them from the packages.
• Packages must be numbered. Send fewer than numPackages declares and an account with day confirmation leaves the shipment pending until the rest arrive, while an account without it returns a package-count error.

clientReference is capped at 20 characters

CBL stores only the first 20 characters, does not document this, and does not complain — a longer reference is truncated silently and still answers status: OK, so two references sharing a 20-character prefix collapse into one shipment. The package refuses the call instead:

Confirm the day

Accounts configured for day confirmation leave newly created shipments registered but not handed over — create() alone is not enough. Confirmation is a separate call, mirroring the API:

confirm() authenticates as one account and only confirms that account's own references, so a batch job serving several accounts must group references by account.

Delete and reprint

A reference or SSCC CBL does not recognise is a silent no-op — the count comes back 0 with an empty errorList, so check the count rather than the absence of errors. Deleting a package from a complete shipment moves it from closed back to pending.

Pickups

Where CBL has enabled a pickup service on the account, it is selected per shipment through serviceType, with its own observation fields:

The codes are account-specific — ask CBL which apply to yours.

Track a shipment

Proof of delivery

Both date-range endpoints cap their window — 30 days for status, 7 for proof of delivery. CBL silently narrows a wider request and attaches warning 300; the package clamps client-side too, so the window you get is the window you asked for.

Error handling

CBL answers business failures with HTTP 200 and a populated errorList, so results are always returned and inspected. The package throws only for problems above that layer:

Every response object exposes hasErrors(), errors(), errorMessages(), hasWarnings(), warnings() and warningMessages().

Auditing the raw exchange

Resources retain the last exchange, for applications that journal carrier traffic:

Character encoding

CBL renders labels with ^CI10, so anything present in CP850 survives — Müller & Söhne, Josép Peñá Ürüñ, Città àèìòù and früh all print correctly. Characters outside it do not: a typographic em dash (—) prints as ÔÇö. Prefer ASCII punctuation in observations1/observations2.

Faking in your tests

Saloon's MockClient intercepts everything the package sends, the daily-token call included — queue that response first:

Development

The live carrier tests are excluded from composer test and gated twice — by group and by environment variable. They create, confirm and delete real shipments on the test account:

The fixtures in tests/Fixtures/responses were recorded from that account; see the README there for the quirks they preserve.

Credits

• SmartDato

License

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