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:

DHL_PARCEL_API_KEY=your-api-key
# Or use Basic Auth instead:
# DHL_PARCEL_USERNAME=your-username
# DHL_PARCEL_PASSWORD=your-password

# Enable sandbox for testing:
# DHL_PARCEL_SANDBOX=true

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 API key
$dhl = DhlParcel::make([
    'api_key' => 'your-api-key',
    'sandbox' => true,
]);

// Or with 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

Enum	Product
`Product::V01PAK`	DHL Paket
`Product::V53WPAK`	DHL Paket International
`Product::V54EPAK`	DHL Europaket
`Product::V62WP`	Warenpost
`Product::V62KP`	DHL Kleinpaket
`Product::V66WPI`	Warenpost International

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

License

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

smart-dato / dhl-parcel-sdk

Maintainers

Package info

Fund package maintenance!

Statistics

Security