README

A Laravel package for the DHL Parcel DE Shipping v2 API. Create shipments, retrieve labels, manage manifests, and more. Built on Saloon and Spatie Laravel Data.

Installation

composer require smart-dato/dhl-parcel-sdk

Publish the config file:

php artisan vendor:publish --tag="dhl-parcel-sdk-config"

Add your credentials to .env:

# OAuth2 (recommended — Basic Auth is deprecated by DHL):
DHL_PARCEL_API_KEY=your-client-id
DHL_PARCEL_CLIENT_SECRET=your-client-secret
DHL_PARCEL_USERNAME=your-business-customer-username
DHL_PARCEL_PASSWORD=your-business-customer-password

# Or legacy API key only:
# DHL_PARCEL_API_KEY=your-api-key

# Or legacy Basic Auth:
# DHL_PARCEL_USERNAME=your-username
# DHL_PARCEL_PASSWORD=your-password

# Enable sandbox for testing:
# DHL_PARCEL_SANDBOX=true

OAuth2 mode is enabled automatically when DHL_PARCEL_CLIENT_SECRET is set together with the API key, username and password. The SDK then exchanges the credentials for a Bearer token against the DHL ROPC token endpoint and caches the token in memory until it expires.

Usage

Create a shipment

use SmartDato\DhlParcel\Data\Orders\ContactAddressData;
use SmartDato\DhlParcel\Data\Orders\ShipmentData;
use SmartDato\DhlParcel\Data\Orders\ShipmentDetailsData;
use SmartDato\DhlParcel\Data\Orders\ShipmentOrderRequestData;
use SmartDato\DhlParcel\Data\Orders\ShipperData;
use SmartDato\DhlParcel\Data\Orders\WeightData;
use SmartDato\DhlParcel\Enums\DocFormat;
use SmartDato\DhlParcel\Enums\Product;
use SmartDato\DhlParcel\Enums\WeightUom;
use SmartDato\DhlParcel\Facades\DhlParcel;

$response = DhlParcel::orders()->create(
    data: new ShipmentOrderRequestData(
        profile: 'STANDARD_GRUPPENPROFIL',
        shipments: [
            new ShipmentData(
                product: Product::V01PAK,
                billingNumber: '33333333330102',
                details: new ShipmentDetailsData(
                    weight: new WeightData(WeightUom::Grams, 500),
                ),
                shipper: new ShipperData(
                    name1: 'My Online Shop GmbH',
                    addressStreet: 'Sträßchensweg 10',
                    city: 'Bonn',
                    country: 'DEU',
                    postalCode: '53113',
                ),
                consignee: new ContactAddressData(
                    name1: 'Maria Musterfrau',
                    addressStreet: 'Kurt-Schumacher-Str. 20',
                    city: 'Bonn',
                    country: 'DEU',
                    postalCode: '53113',
                ),
            ),
        ],
    ),
    docFormat: DocFormat::Pdf,
);

// Access the label
$label = $response->items[0]->label;

Validate a shipment (dry run)

$response = DhlParcel::orders()->validate(
    data: $shipmentOrderRequest,
);

Retrieve existing labels

$response = DhlParcel::orders()->get(
    shipments: ['340434310428091700'],
);

Delete shipments

$response = DhlParcel::orders()->delete(
    profile: 'STANDARD_GRUPPENPROFIL',
    shipments: ['340434310428091700'],
);

Manifests

use SmartDato\DhlParcel\Data\Manifests\ManifestRequestData;

// Get daily manifest
$manifest = DhlParcel::manifests()->get(date: '2025-01-15');

// Close out shipments
$response = DhlParcel::manifests()->create(
    data: new ManifestRequestData(
        profile: 'STANDARD_GRUPPENPROFIL',
        shipmentNumbers: ['340434310428091700'],
    ),
);

Download a label PDF

$pdfContent = DhlParcel::labels()->download(token: 'label-token-from-response');

Using without the Facade

You can create a DhlParcel instance directly using DhlParcel::make(). This is useful when you prefer not to use the facade, need different credentials per request, or want to support multi-tenant setups:

use SmartDato\DhlParcel\DhlParcel;

// With OAuth2 (recommended)
$dhl = DhlParcel::make([
    'api_key' => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'username' => 'your-business-customer-username',
    'password' => 'your-business-customer-password',
    'sandbox' => true,
]);

// Or with legacy API key
$dhl = DhlParcel::make([
    'api_key' => 'your-api-key',
    'sandbox' => true,
]);

// Or with legacy Basic Auth
$dhl = DhlParcel::make([
    'username' => 'your-username',
    'password' => 'your-password',
]);

$response = $dhl->orders()->create($data);

You can also optionally pass a custom base_url if needed:

$dhl = DhlParcel::make([
    'api_key' => 'your-api-key',
    'base_url' => 'https://api-eu.dhl.com/parcel/de/shipping/v2',
]);

Available products

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• SmartDato
• All Contributors

License

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