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

dpd-de-php

PHP client library for the DPD Cloud Service Webservice (DPD Deutschland).

An open-source PHP client for DPD Germany's Cloud Service - create shipments (with PDF/ZPL labels), pre-flight validate orders server-side, track parcels via two different tracking models, find pickup ParcelShops, and fetch account pickup rules. SOAP by default (fully verified against the live WSDL), with an optional REST transport.

Requirements

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

Installation

Quick Start

See examples/ for complete, runnable scripts.

Configuration

DPD Cloud Service uses two credential pairs, both issued by DPD:

• PartnerCredentials (Name + Token) - identifies the software/integration (your "Partner" slot, e.g. DPD Cloud Service Alpha2).
• UserCredentials (cloudUserID + Token) - identifies the DPD customer account (your own account).

Sandbox vs. production endpoints:

DPD issues separate credentials per environment - your production PartnerCredentials/UserCredentials will not work against the sandbox and vice versa.

Debug mode

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

Leave debug off in production to keep exceptions and logs concise.

API Reference

createShipment(OrderItem $item, ?OrderSettings $settings = null): SetOrderResult

createShipments(array $items, ?OrderSettings $settings = null): SetOrderResult

Creates one shipment, or up to 30 in a single call (DPD method: setOrder, OrderAction=startOrder). Runs local pre-flight validation first (see below).

Note: DPD Cloud Service does not support multi-parcel shipments (MPS) - each physical package needs its own OrderItem with its own shipAddress.

SetOrderResult exposes labelPdf (already Base64-decoded document bytes - PDF, or ZPL text when LabelSize::ZplA6 is requested) and items (one OrderResult per parcel, yourInternalId + parcelNo); firstParcelNo() is a convenience shortcut.

OrderItem fields:

Parcel fields: shipService (ShipService enum), weightKg (0-31.5), content, yourInternalId, reference1, reference2 (all max 35 chars), and a deprecated cod (DPD discontinued cash-on-delivery on 2020-05-11).

checkOrderData(array $items, ?OrderSettings $settings = null): void

Server-side dry run (DPD method: setOrder, OrderAction=checkOrderData) - asks DPD to validate the order data without creating a real shipment or consuming a parcel number. Throws DpdCloudApiException if DPD rejects the data.

validateLocally(array $items): string[]

Runs the same local field/weight checks createShipment() performs, with no network call. Returns an empty array when the items are locally valid.

fetchParcelLifeCycle(string $parcelNo): TrackingResult

Tracking via the older, UI-rendering-oriented "Parcel Life Cycle Service 2.0" (DPD method: getParcelLifeCycle). Returns a TrackingResult with a shipmentInfo header, a statusInfo list (one per milestone) and a contactInfo list - each built from pre-formatted ContentLine/ContentItem text blocks (bold/paragraph flags included) meant for direct UI rendering. Always uses SOAP, regardless of the configured transport mode (see REST caveats).

fetchOrderStatus(string $parcelNo, ?string $deliveryZipCode = null): OrderStatus

Tracking via the newer, structured "Parcel Life Cycle Service 3.1" (DPD method: getOrderStatus). Returns an OrderStatus with orderInformation (service/weight/ reference/receiver), shipAddress, lastStatusInfo and a statusInfoContainer with five named milestones (start, onTheRoad, deliveryDepot, carLoad, delivered). Provide deliveryZipCode to receive full (non-anonymised) tracking data, per DPD's privacy rules.

findParcelShops(ParcelShopQuery $query): ParcelShop[]

Searches for DPD ParcelShop pickup points (DPD method: getParcelShopFinder), either by address or by geo-coordinates:

Each ParcelShop carries shopAddress, geoData (distance + coordinates), openingHoursList, holidayList, shopServiceList (ShopService[]), and isParcelLocker(): bool.

fetchZipCodeRules(): ZipCodeRules

Fetches pickup rules for your own account's pickup address (DPD method: getZipCodeRules; no parameters needed) - no-pickup days, Express/Classic cut-off times, pickup depot, state. getNoPickupDaysList(): DateTimeImmutable[] parses the raw comma- separated date list.

Local validation

Every createShipment()/createShipments()/checkOrderData() call is pre-validated locally (no network call) against the field constraints documented in the DPD Cloud Service Webservice documentation (error-code appendix):

This is a best-effort local check mirroring DPD's own validation - it does not replace checkOrderData() for a full server-side dry run. Failures throw DpdCloudValidationException before any network call is made.

Exceptions

All exceptions extend VeryCodeCom\DpdDe\Exception\DpdCloudException.

Every exception exposes getRawResponse(): ?string (the exact response DPD returned, when captured) and getDebugReport(): string (message + raw response + stack trace) - see Debug mode.

REST caveats

DPD Cloud Service exposes both SOAP and REST endpoints for the same five operations. This library fully supports both via the TransportMode constructor argument:

However, SOAP is the recommended default and is used unless you explicitly opt into REST, for these reasons:

1. The SOAP contract is fully verified against the live WSDL (https://cloud.dpd.com/services/v1/DPDCloudService.asmx?wsdl) - every field name, type and namespace behaviour is confirmed.
2. The REST contract was reconstructed from the official PDF documentation and empirical sandbox probing (no real production credentials were available during development). Version/Language headers and the setOrder JSON body shape are confirmed working; however, the exact HTTP header names for PartnerCredentials/UserCredentials could not be conclusively verified without a real account. The convention used (PartnerCredentials.Name, PartnerCredentials.Token, UserCredentials.cloudUserID, UserCredentials.Token) is the most likely candidate but you should verify it against your own sandbox account (enable debug mode to inspect the raw response) before relying on REST in production.
3. fetchParcelLifeCycle() always uses SOAP, regardless of TransportMode - its deeply nested, UI-oriented JSON response shape was never empirically confirmed over REST, so no REST parser was implemented for it.

Known DPD Cloud Service API quirks

1. Two tracking models - getParcelLifeCycle ("Parcel Life Cycle Service 2.0") returns pre-formatted, UI-rendering-oriented text blocks (ContentLine/ContentItem, with bold/paragraph flags); getOrderStatus ("Parcel Life Cycle Service 3.1") returns a newer, more structured model with named milestones. They are not interchangeable and have different DTOs (TrackingResult/StatusInfo vs. OrderStatus/StatusInfoDetail).
2. ParcelLifeCycleService/2.0 namespace quirk - this schema declares elementFormDefault="qualified" but every individual element inside TrackingResult (shipmentInfo, statusInfo, status, label, content, etc.) explicitly overrides this with form="unqualified". In practice, these elements carry no namespace at all in the real SOAP response - not even the schema's own ParcelLifeCycleService/2.0 namespace. Internal\Soap\ResponseParser queries them with unprefixed XPath expressions, not a registered prefix.
3. Document/literal SOAP style - unlike some other German carrier APIs, DPD Cloud Service is plain document/literal: no xsi:type attributes, and the default namespace https://cloud.dpd.com/ is declared once on the outer request element and inherited by every descendant.
4. No multi-parcel shipment (MPS) support in this API - every physical package needs its own OrderItem / ship address (see the DPD Cloud Service FAQ).
5. Cash-on-delivery is deprecated - DPD fully discontinued "Nachnahme" (COD) on 2020-05-11. The Cod DTO, PaymentType enum, and *_COD ShipService variants remain 1:1 with the WSDL for completeness but should not be relied on for new integrations.
6. Separate credentials per environment - sandbox and production each require their own PartnerCredentials/UserCredentials pair; they are not interchangeable.

Dependency Injection & Testing

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

Implement TransportInterface::send(TransportRequest): TransportResponse to swap in a PSR-18 HTTP client adapter, or a scripted fake for tests - see tests/Unit/DpdCloudClientTest.php for the pattern used by this library's own test suite (no real network calls).

Running Tests

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.