Skip to content
BranchesTags

Repository files navigation

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.

Latest Version Total Downloads CI Integration PHPStan PHP License

Requirements

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

Installation

composer require very-code-com/suus-php

Quick Start

use VeryCodeCom\Suus\SuusClient;
use VeryCodeCom\Suus\Dto\{Address, Package, ShipmentOrder};
use VeryCodeCom\Suus\Enum\{Incoterm, PackageSymbol};

$client = SuusClient::sandbox('ws_yourlogin', 'your_password');

$result = $client->createShipment(new ShipmentOrder(
    reference: 'ORDER-2025-001',
    sender:    new Address('Sender GmbH', 'Musterstr.', '1', '10115', 'Berlin', 'DE', phone: '+4930123'),
    receiver:  new Address('Odbiorca Sp. z o.o.', 'Marszałkowska', '100', '00-026', 'Warszawa', 'PL', phone: '+48600000'),
    packages:  [new Package(PackageSymbol::EUR, weightKg: 120.0)],
    incoterms: Incoterm::DAP,
));

echo $result->shipmentNo;   // e.g. OPLKRI2600895
echo $result->trackingUrl;  // https://portal.suus.com/order-details/OPLKRI2600895

See examples/ for complete, runnable scripts.

Configuration

// Named constructors
$client = SuusClient::sandbox('ws_login', 'secret');
$client = SuusClient::production('ws_login', 'secret');

// From environment variables (recommended)
$config = SuusConfig::fromEnv();

// From array (framework config)
$config = SuusConfig::fromArray(['login' => '...', 'password' => '...', 'env' => 'production']);
Env variable Required Default Description
SUUS_LOGIN yes - API login (e.g. ws_yourlogin)
SUUS_PASSWORD yes - API password
SUUS_ENV no production sandbox or production
SUUS_TIMEOUT no 30 Request timeout (seconds)
SUUS_CONNECT_TIMEOUT no 10 Connection timeout (seconds)
SUUS_DEBUG no 0 1/true to enable verbose debug output (see below)

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:

$config = new SuusConfig('ws_login', 'secret', sandbox: true, debug: true);
$client = new SuusClient($config, logger: $myPsrLogger);

try {
    $client->createShipment($order);
} catch (SuusException $e) {
    // Raw response is always available for inspection, regardless of the flag:
    echo $e->getRawResponse();   // the exact XML SUUS returned (or null)

    // Full developer report: class + message + raw response + stack trace:
    echo $e->getDebugReport();
}

That matters most for unrecognised errors such as a 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:

Field Type Required Notes
reference string yes Your unique reference (<= 50 chars)
sender Address yes Loading address
receiver Address yes Unloading address
packages Package[] yes >= 1 package
loadingDate ?DateTimeImmutable no null = auto (+2 business days in sender's calendar)
unloadingDate ?DateTimeImmutable no null = loadingDate + 3 business days
incoterms ?Incoterm intl. Required for international routes
orderType OrderType no B2C default; must be B2B for international
category ShipmentCategory no DROBNICA / PLUS24 / PTL (international)
descriptionOfGoods string no Defaults to General cargo
remarks string no Free-text remarks (<= 100 chars)
additionalServices array no Typed service objects - see Additional Services
costGroup ?string no Cost-group tag, <= 20 chars (e.g. /SI)
freight ?string no International only; must be paired with currency
currency ?string no 3-letter code; must be paired with freight

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

-> full example | international routes | 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. Use it to surface 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[]. Each event's occurredAt is a ?DateTimeImmutable: SUUS fractional seconds and timezone offsets are parsed, while a missing date or invalid timestamp is returned as null. The client never substitutes the current time for data it could not parse.

A SUUS error (e.g. PRJ000001, unknown shipment) raises SuusApiException rather than returning an empty event list.

fetchStatusByReference(string $reference): StatusResult

Same call keyed by your own order reference - SUUS treats shipmentNo and reference as interchangeable and resolves a reference to the most recently added order carrying it.

-> full example

Status mapping:

SUUS native codes Normalized ShipmentStatus
J_CR, KOL, M_KOL Created
LOAD, ZALF, ZAL, M_DYS, WTRF InTransit
ROZF, UNDI, UNLO Delivered
ANUL Cancelled
ZWRON, ZTF Failed

fetchDocument(string $shipmentNo, DocumentType $type, array $colliNumbers = []): string

Downloads a document as raw PDF bytes via SUUS getDocument.

DocumentType Description
Label Standard A4 shipping label
LabelA6 Thermal printer label (A6)
ShippingOrder Shipping order document
LoadingList Loading list (see below)

$colliNumbers narrows Label / LabelA6 to individual packages - pass numbers from getColliNumbers(). Left empty, SUUS returns every label the shipment has.

fetchDocumentByReference(string $reference, DocumentType $type, array $colliNumbers = []): string

Same call keyed by your own order reference instead of the waybill number.

fetchLabel(string $shipmentNo): string

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

fetchLoadingList(string $masterNo): string

The collective loading list - the one document keyed by the master waybill number rather than by shipment.

-> full example

getColliNumbers(string $shipmentNo): array

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

SUUS does not return them in a stable order between calls, so treat the result as a set

  • never match a colli number to a package by index.

getColliNumbersByReference(string $reference): array

Same call keyed by your own order reference.

Package Types

PackageSymbol Description
KAR Cardboard box (karton)
EUR EUR pallet
JED Disposable pallet
PLT Industrial pallet
SKR Crate (skrzynia)
ROL Roll (rolka)
DPL DPPL container
DHP DHP pallet
CHP CHEP pallet
AGD Appliance (gabaryt AGD)
INN Other / re-handling
WIA Bundle (wiązka)
HB Hobok

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.

new Package(PackageSymbol::EUR, weightKg: 50.0, lengthCm: 120.0, widthCm: 80.0, heightCm: 144.0, returnable: 1, stackable: 1);

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.

Service class SUUS symbol Availability Key options
CodService RohligCOD B2B & B2C amount (<= 15 000 PLN), currency (PLN)
InsuranceService RohligUbezpieczenie3 B2B & B2C amount, goodsType, additionalCosts, strikeClause, warClause, confirmGoodsNotExcluded
EmailNotificationService RohligZatwierdzeniePowiadomienie B2B & B2C notifySender, notifyReceiver (each party notified needs an e-mail on its address)
LiftService RohligWinda B2B & B2C tail-lift (<= 750 kg)
PalletTruckService StdPaleciak B2B & B2C pallet truck at delivery
SmsNotificationService StdAwizacjaSms B2C, domestic only receiver mobilePhone required (PRJ00355)
InsideDeliveryService StdWniesienie2 B2C, domestic only carry goods inside
DocumentReturnDomesticService StdDokumentyZwrotneINiezwrotneGrid2 domestic only documentNumber, tag (DZ/DT), documentType (FK/WZ/ZLEC/SPEC), description
DocumentReturnInternationalService StdDokumentyZwrotneINiezwrotneGrid3 international only same fields as the domestic variant

Route restrictions 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).

use VeryCodeCom\Suus\Service\{CodService, InsuranceService, EmailNotificationService};

additionalServices: [
    new CodService(amount: 250.0, currency: 'PLN'),
    new InsuranceService(amount: 2500.0, goodsType: InsuranceService::GOODS_STANDARD),
    new EmailNotificationService(notifySender: true, notifyReceiver: true),
],

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 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.

Route Classified as Incoterms required
PL->PL Domestic No
PL->DE International Yes
PL->CH International Yes (Swiss customs docs)
DE->DE International Yes
DE->AT International Yes
DE->CH International Yes (Swiss customs docs)

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

$result = $client->createShipment(new ShipmentOrder(
    reference: 'INT-2025-001',
    sender:    new Address('Versender GmbH', 'Musterstr.', '1', '10115', 'Berlin', 'DE', phone: '+4930123'),
    receiver:  new Address('Empfänger GmbH', 'Hauptstr.', '10', '80331', 'Munich', 'DE', phone: '+4989654'),
    packages:  [new Package(PackageSymbol::KAR, weightKg: 10.0, lengthCm: 50.0, widthCm: 30.0, heightCm: 25.0)],
    incoterms: Incoterm::DAP,
    orderType: OrderType::B2B,   // required for international
    category:  ShipmentCategory::DROBNICA,
    freight:   '150.00',          // optional - must be paired with currency
    currency:  'EUR',
));

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

use VeryCodeCom\Suus\Validation\ValidationError;

foreach ($client->validate($order) as $error) {
    // $error->code   e.g. "PRJ00372"  (reuses the SUUS code where one exists)
    // $error->field  e.g. "packages[0].returnable"
    // $error->message / (string) $error  human-readable text
    echo "[{$error->code}] {$error}\n";
}

SuusValidationException::getValidationErrors() returns the same typed objects; getErrors(): string[] flattens them to 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):

use VeryCodeCom\Suus\Validation\ValidationPolicy;

$client = new SuusClient($config, policy: ValidationPolicy::relaxed());
// or fine-grained:
$client = new SuusClient($config, policy: new ValidationPolicy(
    enforceInternationalB2B: false,                     // allow B2C internationally
    enforceServiceRouteRestrictions: true,              // keep service/route checks
    enforceInternationalPackagingRestrictions: true,
));

Override the domestic/international decision (RouteClassifierInterface)

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

use VeryCodeCom\Suus\Routing\CallableRouteClassifier;

$client = new SuusClient($config, routeClassifier: new CallableRouteClassifier(
    fn (ShipmentOrder $o): bool =>
        ($o->sender->getCountryCode() === 'DE' && $o->receiver->getCountryCode() === 'DE')
            ? false                    // treat DE->DE as domestic in the library
            : $o->isInternational(),   // default rule otherwise
));

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. To simply relax the local international-only checks, use ValidationPolicy instead.

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

SuusClient picks the calendar from the sender's country code, so standard routes need no manual configuration.

Class Country Holidays included
PolishCalendar PL - Poland 9 fixed + 4 Easter-based (Western)
GermanCalendar DE - Germany 5 federal fixed + 4 Easter-based (federal only, no Bundesland)
AustriaCalendar AT - Austria 9 fixed + 4 Easter-based (Western)
SwitzerlandCalendar CH - Switzerland 4 widely-observed fixed + 4 Easter-based (22/26 cantons)
CzechCalendar CZ - Czech Rep. 11 fixed + Good Friday + Easter Monday (Western)
SlovakCalendar SK - Slovakia 13 fixed + Good Friday + Easter Monday (Western)
HungarianCalendar HU - Hungary 8 fixed + 4 Easter-based (Western)
RomanianCalendar RO - Romania 10 fixed + 5 Easter-based (Orthodox Easter - differs from Western by up to 5 weeks)
SlovenianCalendar SI - Slovenia 12 fixed + Easter Sun/Mon + Whit Sunday (Western)

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

use VeryCodeCom\Suus\Calendar\GermanCalendar;

$client = new SuusClient($config, calendar: new GermanCalendar());

All calendars implement BusinessCalendarInterface and work standalone:

$cal = new RomanianCalendar();
$cal->isBusinessDay(new DateTimeImmutable('2024-05-06'));  // false - Orthodox Easter Monday
$cal->isBusinessDay(new DateTimeImmutable('2024-04-01'));  // true  - Western Easter Mon (not RO holiday)

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.

Exception Trigger
SuusValidationException Local validation failed - carries typed getValidationErrors(): ValidationError[] (code + field + message) and getErrors(): string[] (plain messages)
SuusAuthException SUUS rejects credentials (DRG00001)
SuusDuplicateReferenceException Reference already exists (PRJ00310)
SuusApiException Other SUUS API errors - carries returnCode + errorCodes; the message also includes SUUS's returnDesc for bare codes (e.g. BTN0001 = service temporarily unavailable). Every read method raises this on success=false, including PRJ000001; none of them report a rejected request as an empty result
SuusTransportException Network error or non-200 HTTP response
SuusResponseParseException SUUS returned unparseable XML

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:

new SuusClient(
    config:    SuusConfig,
    transport: TransportInterface        = new CurlTransport(),
    logger:    ?Psr\Log\LoggerInterface  = null,
    calendar:  ?BusinessCalendarInterface = null,  // null = auto-detect from sender country
)

-> 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. PRJ000001 often means a malformed request, not a missing order - getEvents, getColliNo and getDocument all answer "order not found" when the envelope is wrong. getEvents / getColliNo need the <shipments><shipment> wrapper (never a bare <shipmentNo>), and getDocument names the document symbol <document>, not <documentType>.
  5. Colli numbers nest twice - the <colliNo> element in a getColliNo response is an ArrayOfColli wrapper holding <colli><colliNo> leaves.
  6. Loading date minimum - SUUS requires +2 Polish business days advance notice.
  7. <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

composer install

# Unit tests (no network required)
vendor/bin/phpunit --testsuite unit

# Integration tests against the real SUUS sandbox.
# The two addOrder tests register real sandbox orders; add SUUS_ALLOW_ORDERS=0 to skip them.
SUUS_SANDBOX=1 SUUS_LOGIN=ws_xxx SUUS_PASSWORD=xxx \
  vendor/bin/phpunit --testsuite integration

# Manual sandbox smoke test (creates a real shipment, prints raw SOAP request/response)
SUUS_LOGIN=ws_xxx SUUS_PASSWORD=xxx php examples/09_sandbox_smoke_test.php

The smoke test hits the sandbox endpoint directly and prints the full XML exchange, which verifies credentials and connectivity without running the whole test suite. A successful run looks like:

--- SUCCESS ---
Shipment No : OPLKRI2600931
Reference   : TEST-20260603110000
Tracking URL: https://portal.suus.com/order-details/OPLKRI2600931

Continuous integration

Workflow Runs What it does
ci.yml every push and pull request Unit tests on PHP 8.2/8.3/8.4, PHPStan level 8, composer validate, lints every example
integration.yml pushes to master, nightly, manual The sandbox integration suite

The integration workflow stays out of the pull-request gate: forks cannot read repository secrets, and the addOrder tests register real sandbox orders, so it runs on a schedule and is serialised through a concurrency group.

To enable it, add SUUS_LOGIN and SUUS_PASSWORD as repository secrets. Without them the job reports "not configured" and stops rather than failing the build. Running it manually (workflow_dispatch) offers a checkbox to skip the order-creating tests.

License

Apache License 2.0 - see 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. Issues and pull requests are welcome.

About

PHP client library for the SUUS Logistics SOAP API: create shipments, track parcels, download labels, fetch delivery points and use typed additional services (COD, insurance, SMS, lift and more).

packagist.org/packages/very-code-com/suus-php

Topics

api-clientcarrierfreightlogisticsphpphp82shippingsoapsuus

Resources

Readme
Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages