Download the PHP package very-code-com/suus-php without Composer

suus-php

PHP client library for the SUUS Logistics (Rohlig Logistics) SOAP API.

The first open-source PHP package for SUUS/Rohlig freight integration - create shipments, pre-flight validate orders, track statuses, download documents, and handle multi-country business-day scheduling.

Requirements

• PHP 8.2+
• ext-curl
• ext-dom

Installation

Quick Start

See examples/ for complete, runnable scripts.

Configuration

Debug mode

Set the debug flag (constructor arg, SUUS_DEBUG=1, or 'debug' => true in fromArray) to make the client attach the raw SUUS response to every thrown exception and log a full debug report (message + raw XML + stack trace) at error level via the injected PSR-3 logger:

This is ideal for diagnosing unrecognised errors (e.g. bare BTN0001) where you need to see exactly what SUUS sent back. Leave debug off in production to keep exceptions and logs concise.

API Reference

createShipment(ShipmentOrder $order): ShipmentResult

Creates a shipment via SUUS addOrder. Validates locally first. Returns ShipmentResult with shipmentNo, reference, trackingUrl.

ShipmentOrder fields:

Address requires name, street, streetNo, postcode, city, countryCode and at least one of phone / mobilePhone; contactPerson and email are optional (some services require an e-mail on the relevant address).

-> additional services

validate(ShipmentOrder $order): ValidationError[]

Runs the same local business-rule checks as createShipment() with no network call, auto-selecting the sender-country calendar and applying the configured ValidationPolicy / RouteClassifier. Returns typed ValidationError objects (message / field / code); an empty array means the order is valid. Ideal for surfacing validation in your own UI before sending. See Pre-flight Validation, Policies & Route Classification.

-> full example

fetchStatus(string $shipmentNo): StatusResult

Polls events via SUUS getEvents. Returns StatusResult with status (ShipmentStatus enum), rawLatestCode, events[].

Note: getEvents always returns PRJ000001 in sandbox mode.

-> full example

Status mapping:

fetchDocument(string $shipmentNo, DocumentType $type): string

Downloads a document as raw PDF bytes via SUUS getDocument.

fetchLabel(string $shipmentNo): string

Convenience shortcut for fetchDocument(..., DocumentType::Label).

-> full example

getColliNumbers(string $shipmentNo): array

Returns per-package (colli) tracking numbers for multi-package shipments.

Package Types

Every Package carries weightKg (required) and optional lengthCm, widthCm, heightCm. For a returnable EUR pallet set returnable and stackable (SUUS requires stackable = 1 when symbol = EUR and returnable > 0). Returnable / stackable packaging is domestic-only.

SUUS package limits (enforced locally by ShipmentValidator): max 126 kg per package, max 800 kg per order, max 124 packages, max dimensions 240 x 120 x 220 cm, and a minimum height of 20 cm for EUR pallets.

Additional Services

Pass typed service objects in ShipmentOrder's additionalServices array. Each maps to a SUUS service symbol and its fields are serialized automatically.

Route-restricted services are enforced locally: domestic-only services on an international order (and the international-only document-return service on a domestic order) are rejected before the API call. Relax this with ValidationPolicy (enforceServiceRouteRestrictions).

Insurance note: InsuranceService always sends the mandatory SUUS declaration that the goods are not in an excluded group (int01 = 1; omitting it triggers PRJ000293). Disable it explicitly with confirmGoodsNotExcluded: false if ever required. Goods types: GOODS_STANDARD (UB_POZ), GOODS_PHARMA (UB_LEK), GOODS_TEMP (UB_TEMP). SUUS enforces a minimum insured value (1 000 PLN) and PLN-only currency.

-> full example

International Routes & Incoterms

A shipment is international whenever either the sender or the receiver is outside Poland. Only PL->PL counts as domestic. For every international route the following are enforced locally, before the API call (all confirmed against the SUUS WebApi docs, WS PK 1.0):

• incoterms is required (otherwise SUUS returns PRJ00313);
• orderType must be B2B - B2C is not supported for international routes;
• returnable / stackable packaging is not available (PRJ00372 / PRJ00373);
• the domestic-only B2C services (SMS pre-advice, inside delivery) cannot be used;
• freight + currency may optionally be declared (both together, per PRJ00387).

The international-only rules above (except the always-on incoterms and freight/currency checks) can be relaxed or redefined per integrator - see Pre-flight validation & policies.

Supported incoterms: EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DDP.

-> full example

Pre-flight Validation, Policies & Route Classification

Validate before you send

SuusClient::validate() runs the same local business-rule checks as createShipment() but makes no network call, auto-selecting the sender-country calendar. It returns structured ValidationError objects (each is Stringable):

SuusValidationException::getValidationErrors() returns the same typed objects; getErrors(): string[] still returns plain messages.

Relax the international-only rules (ValidationPolicy)

Strict by default. Turn off the international-only enforcement when your contract allows it (SUUS still validates server-side):

Override the domestic/international decision (RouteClassifierInterface)

The classifier decides which routes the library treats as international. That drives both local validation and the generated XML (<shipper>/<consignee> blocks

• incoterms emission):

⚠️ This is a client-side override, not a SUUS-side one. SUUS classifies each shipment on its own side from the address country codes: any route where either country is not PL is an international product, regardless of what the classifier returns. Verified against the sandbox — a DE->DE order forced to "domestic" is still rejected (BTN0002: "Kraj … nie jest dostępny dla kontrahenta typu B2C dla produktu Drobnica międzynarodowa … nie określono warunków Incoterms"). Use this seam only when your SUUS contract/product already supports the treatment you are forcing (e.g. a local in-country contract); it cannot create capability the contract does not include. For simply relaxing the local intl-only checks, prefer ValidationPolicy.

-> full example

Business-Day Calendars

The library ships calendars for all countries where SUUS operates. SuusClient defaults to PolishCalendar (required +2 PL business days advance notice).

Auto-detection: SuusClient automatically picks the right calendar based on the sender's country code - no manual configuration needed for standard routes.

To override (e.g. force a specific calendar regardless of sender country):

All calendars implement BusinessCalendarInterface and work standalone:

CalendarFactory::forCountry(string $cc) returns the right instance for any supported country code; unknown codes fall back to PolishCalendar.

-> full example

Exceptions

All exceptions extend VeryCodeCom\Suus\Exception\SuusException.

Every exception extends SuusException and exposes getRawResponse(): ?string (the exact XML SUUS returned, when captured) and getDebugReport(): string (message + raw response + stack trace) - see Debug mode. To validate an order before sending (and avoid the exception entirely), use SuusClient::validate().

Dependency Injection & Testing

The client accepts a custom TransportInterface, PSR-3 logger, and calendar override:

-> testing example

Known SUUS API Quirks

1. lenghtCm typo - SUUS uses <lenghtCm> (missing one t). Preserved intentionally.
2. PHP's SoapClient is incompatible - SUUS uses RPC/encoded SOAP 1.1. This library uses raw cURL with manually constructed XML.
3. Response namespace quirk - SUUS SOAP responses swap xmlns:cw and xmlns:ns1. Child elements carry no namespace prefix.
4. getEvents / getDocument always fail in sandbox - Only addOrder returns real data in the test environment.
5. Loading date minimum - SUUS requires +2 Polish business days advance notice.
6. <auth> in every body - Unlike most SOAP services, SUUS embeds the auth block inside every operation's body, not in the SOAP header.

Running Tests

The smoke test (test_sandbox.php) hits the sandbox endpoint directly and prints the full XML exchange - useful for verifying credentials and connectivity without running the full test suite. A successful run looks like:

License

NOTICE for attribution requirements.

You may use, distribute, and modify this library freely. You must retain the NOTICE file and copyright notices in any redistribution or derivative work.

Built by Very Code. Contributions welcome - open an issue or PR.