A PHP SDK for interacting with the DHL Parcel DE Shipping API (Post & Parcel Germany). This package allows you to easily create shipments, print labels, and manage shipments through the DHL API.
You can install the package via composer:
composer require sonnenglas/dhl-parcel-de-sdk- PHP 8.0 or higher
- Composer
- DHL API credentials (username, password, and API key)
- Create shipments and generate labels
- Delete shipments
- Support for various DHL products (DHL Paket, DHL Paket International, etc.)
- Address validation
- Custom package dimensions and weight
- Support for production and sandbox environments
use Sonnenglas\DhlParcelDe\Dhl;
use Sonnenglas\DhlParcelDe\Enums\ShipmentProduct;
use Sonnenglas\DhlParcelDe\ValueObjects\Address;
use Sonnenglas\DhlParcelDe\ValueObjects\Shipment;
use Sonnenglas\DhlParcelDe\ValueObjects\Package;
// Initialize with your DHL API credentials
$dhl = new Dhl(
username: 'your_username',
password: 'your_password',
apiKey: 'your_api_key',
productionMode: false // Set to true for production
);
$shipmentService = $dhl->getShipmentService();// 1. Create the shipper address
$shipper = new Address(
name: 'Your Company Name',
addressStreet: 'Your Street 123',
postalCode: '12345',
city: 'Your City',
country: 'DE',
email: 'info@example.com'
);
// 2. Create the recipient address
$recipient = new Address(
name: 'John Doe',
addressStreet: 'Customer Street 456',
postalCode: '54321',
city: 'Customer City',
country: 'DE',
email: 'customer@example.com',
phone: '123456789'
);
// 3. Define the package details
$package = new Package(
height: 200, // in mm
length: 300, // in mm
width: 400, // in mm
weight: 2000 // in g
);
// 4. Create the shipment object
$shipment = new Shipment(
product: ShipmentProduct::DhlPacket,
billingNumber: '33333333330102', // Your DHL billing number
referenceNo: '123456789', // Your reference number (min 8 characters)
shipper: $shipper,
recipient: $recipient,
package: $package
);
// 5. Send the shipment to DHL
try {
$response = $shipmentService
->setShipments([$shipment])
->createShipment();
// The shipment was created successfully
$shipmentNumber = $response->shipmentNumber;
$labelUrl = $response->labelUrl;
echo "Shipment created with number: " . $shipmentNumber;
echo "Label URL: " . $labelUrl;
} catch (Exception $e) {
// Handle any errors
echo "Error: " . $e->getMessage();
echo "API Error Response: " . $shipmentService->getLastErrorResponse();
}The SDK supports DHL Packstation deliveries, allowing customers to receive packages at automated parcel stations throughout Germany.
DHL Packstations are automated parcel stations where customers can receive and send packages 24/7. They are located throughout Germany and provide a convenient alternative to home delivery.
To send a package to a DHL Packstation, you need:
- Packstation ID - A 3-digit number (100-999) identifying the specific packstation
- Customer's DHL Account Number (Postnummer) - A 6-10 digit number that customers receive when they register for DHL services
- Packstation Location - The postal code and city where the packstation is located
- Customer Name - The name of the person who will collect the package
$packstationAddress = new Address(
name: 'Max Mustermann', // Customer name
addressStreet: '', // Ignored for packstation
postalCode: '50667', // Packstation postal code
city: 'Köln', // Packstation city
country: 'DE', // Must be 'DE' for packstations
state: '',
email: 'max.mustermann@example.com', // Optional
phone: '', // Optional
additionalInfo: '', // Ignored for packstation
company: '', // Must be empty for packstation
packstationId: 171, // 3-digit packstation number
packstationCustomerNumber: '1234567890' // Customer's DHL account number
);use Sonnenglas\DhlParcelDe\Dhl;
use Sonnenglas\DhlParcelDe\Enums\ShipmentProduct;
use Sonnenglas\DhlParcelDe\ValueObjects\Address;
use Sonnenglas\DhlParcelDe\ValueObjects\Shipment;
use Sonnenglas\DhlParcelDe\ValueObjects\Package;
// Initialize DHL client
$dhl = new Dhl($username, $password, $apiKey, $productionMode);
$shipmentService = $dhl->getShipmentService();
// Sender address
$shipper = new Address(
name: 'Your Company',
addressStreet: 'Your Street 123',
postalCode: '12345',
city: 'Your City',
country: 'DE'
);
// Packstation recipient
$recipient = new Address(
name: 'Max Mustermann',
addressStreet: '', // Will be ignored
postalCode: '50667', // Packstation location
city: 'Köln', // Packstation city
country: 'DE', // Must be DE
packstationId: 171, // 3-digit packstation number
packstationCustomerNumber: '1234567890' // Customer's DHL account number
);
// Package details
$package = new Package(
height: 200, // mm
length: 300, // mm
width: 150, // mm
weight: 1000 // grams
);
// Create shipment
$shipment = new Shipment(
product: ShipmentProduct::DhlPacket,
billingNumber: '33333333330102',
referenceNo: 'REF123456789',
shipper: $shipper,
recipient: $recipient,
package: $package
);
// Send shipment
try {
$response = $shipmentService->setShipments([$shipment])->createShipment();
echo "Packstation shipment created successfully!";
} catch (Exception $e) {
echo "Error: " . $e->getMessage();
}The SDK validates packstation addresses according to DHL requirements:
- Packstation ID: Must be a 3-digit integer between 100 and 999
- Customer Number: Must be 6-10 digits (string)
- Country: Must be 'DE' (packstations are only available in Germany)
- Both Fields Required: If you provide one packstation field, you must provide both
- Company Field: Must be empty for packstation deliveries (private customers only)
The SDK automatically converts packstation addresses to the correct DHL API format:
Packstation Address (Locker format):
{
"name": "Max Mustermann",
"lockerID": 171,
"postNumber": "1234567890",
"city": "Köln",
"postalCode": "50667",
"country": "DEU"
}Regular Address (ContactAddress format):
{
"name1": "John Doe",
"addressStreet": "Musterstraße 123",
"postalCode": "50667",
"city": "Köln",
"country": "DEU"
}Customers can find nearby packstations using:
- DHL website: https://www.dhl.de/de/privatkunden/pakete-empfangen/an-einem-abholort-empfangen/packstation-finden.html
- DHL mobile app
- DHL customer portal
Customers need to register for DHL services to get their Postnummer (customer number):
- Online at: https://www.dhl.de/de/privatkunden/kundenservice/dhl-kundenkonto.html
- At DHL retail locations
- Through the DHL mobile app
The Postnummer is required for all packstation deliveries and is unique to each customer.
try {
$success = $shipmentService->deleteShipment('1234567890');
if ($success) {
echo "Shipment deleted successfully";
} else {
echo "Failed to delete shipment";
echo "Error: " . $shipmentService->getLastErrorResponse();
}
} catch (Exception $e) {
echo "Error: " . $e->getMessage();
}$shipmentService->setProfile('CUSTOM_PROFILE');use Sonnenglas\DhlParcelDe\Enums\LabelFormat;
$shipmentService->setLabelFormat(LabelFormat::A4);Here's a complete example showing how to use the SDK to create a shipment:
<?php
declare(strict_types=1);
require_once('./vendor/autoload.php');
use Sonnenglas\DhlParcelDe\Dhl;
use Sonnenglas\DhlParcelDe\Enums\ShipmentProduct;
use Sonnenglas\DhlParcelDe\ValueObjects\Address;
use Sonnenglas\DhlParcelDe\ValueObjects\Shipment;
use Sonnenglas\DhlParcelDe\ValueObjects\Package;
$user = 'your_api_username';
$pass = 'your_api_password';
$key = 'your_api_key_here';
$productionMode = false;
$dhl = new Dhl($user, $pass, $key, $productionMode);
$shipmentService = $dhl->getShipmentService();
$shipper = new Address(
name: 'Stellar Widgets GmbH',
addressStreet: 'Industrieweg 42',
postalCode: '28195',
city: 'Bremen',
country: 'DE',
state: '',
email: 'info@stellarwidgets.example',
phone: '',
additionalInfo: '',
);
$recipient = new Address(
name: 'Anna Schmidt',
addressStreet: 'Rosenstraße 67',
postalCode: '10115',
city: 'Berlin',
country: 'DE',
state: '',
email: 'anna.schmidt@example.com',
phone: '01761234567',
additionalInfo: 'Second Floor',
);
$package = new Package(
height: 200,
length: 200,
width: 400,
weight: 4000,
);
$shipment = new Shipment(
product: ShipmentProduct::DhlPacket,
billingNumber: '33333333330102',
referenceNo: 'ORD987654321',
shipper: $shipper,
recipient: $recipient,
package: $package,
);
try {
$response = $shipmentService->setShipments([$shipment])
->createShipment();
echo "Result:";
var_dump($response);
} catch (Exception $e) {
echo $shipmentService->getLastErrorResponse();
}The SDK supports the following DHL products:
ShipmentProduct::DhlPacket- DHL Paket (V01PAK)ShipmentProduct::DhlPacketInternational- DHL Paket International (V53WPAK)ShipmentProduct::DhlEuropaket- DHL Europaket (V54EPAK)ShipmentProduct::WarenPost- Warenpost (V62WP)ShipmentProduct::DhlKleinpaket- DHL Kleinpaket (V62KP)ShipmentProduct::WarenPostInternational- Warenpost International (V66WPI)
Since v2.5.0 Address accepts an optional addressHouse argument that maps to DHL's dedicated house-number field on ContactAddress:
$customer = new Address(
name: 'Max Mustermann',
addressStreet: 'Hauptstraße', // street name only
addressHouse: '1', // house number — separate field
postalCode: '10115',
city: 'Berlin',
country: 'DE'
);For the Parcel DE Returns API the separated form is mandatory — concatenating the number into addressStreet causes DHL to respond with 400 "Please add your data in the field 'Number'.". The Shipping API is more lenient and accepts both forms, but using addressHouse is recommended.
addressHouse is silently ignored for Packstation/Locker addresses.
The SDK provides several ways to handle errors:
- Exceptions are thrown for critical errors
- The
getLastErrorResponse()method provides detailed error messages from the DHL API - The
getLastRawResponse()method returns the complete API response for debugging
Contributions are welcome! Please feel free to submit a Pull Request.
Built and maintained by Przemek Peron.
The MIT License (MIT). Please see License File for more information.