DHL Parcel API client for PHP

DHL Parcel API documentation

Installation

You can install the package via composer:

composer require mvdnbrk/dhlparcel-php-api

Usage

Initialize the DHL Parcel client and set your credentials.

$dhlparcel = new \Mvdnbrk\DhlParcel\Client();

$dhlparcel->setUserId('your-user-id');
$dhlparcel->setApiKey('your-api-key');

If you have multipe accounts, you may optionally set an account id:

$dhlparcel->setAccountId('123456');

Create a parcel

$parcel = new \Mvdnbrk\DhlParcel\Resources\Parcel([
    'reference' => 'your own reference for the parcel (optional)',
    'recipient' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'street' => 'Poststraat',
        'number' => '1',
        'number_suffix' => 'A',
        'postal_code' => '1234AA',
        'city' => 'Amsterdam',
        'cc' => 'NL',
    ],
    'sender' => [
        'company_name' => 'Your Company Name',
        'street' => 'Pakketstraat',
        'number' => '99',
        'postal_code' => '9999AA',
        'city' => 'Amsterdam',
        'cc' => 'NL',
    ],
    // Optional. This will be set as the default.
    'pieces' => [
        [
            'parcel_type' => \Mvdnbrk\DhlParcel\Resources\Piece::PARCEL_TYPE_SMALL,
            'quantity' => 1,
        ],
    ],
]);

Create the shipment

$shipment = $dhlparcel->shipments->create($parcel);

$shipment->id;
$shipment->label_id;
$shipment->barcode;

You have created your first shipment!

Retrieving a label

A label can be retrieved by using the label_id. This will return a PDF label as a string.

$dhlparcel->labels->get($shipment->label_id);

Or you may pass the Shipment instance directly to this method:

$dhlparcel->labels->get($shipment);

Setting delivery options for a parcel

You can set delivery options for a parcel by passing in the options directly when you create a parcel:

$parcel = new \Mvdnbrk\MyParcel\Resources\Parcel([
    ...
    'recipient' => [
        ...
    ],
    'options' => [
        'description' => 'Order #123',
        'signature' => true,
        'only_recipient' => true,   
        ...
    ],
]);

Or you may use a method like signature(), onlyRecipient() and labelDescription().
You may call any of these after constructing the parcel.

$parcel->onlyRecipient()
       ->signature()
       ->labelDescription('Order #123');

Mailbox package

If you would like to send a parcel that fits in a standard mailbox you may use the mailboxpackage() method:

$parcel->mailboxpackage();

Deliver a parcel to a DHL service point

You may send a parcel to a DHL service point where a customer can pick up the parcel. The ID of the service point can be set directly when creating a parcel or with the servicePoint method:

$parcel = new \Mvdnbrk\MyParcel\Resources\Parcel([
    ...
    'options' => [
        'service_point_id' => '8004-NL-272403',
        ...
    ],
]);

$parcel->servicePoint('8004-NL-272403');

Tracking a shipment

$tracktrace = $dhlparcel->tracktrace->get('JVGL...');

// Check if the shipment is delivered:
$tracktrace->isDelivered;

Retrieving service points

$servicepoints = $dhlparcel->servicePoints->setPostalcode('1012AA')->setHousenumber('1')->get();

This will return a collection of ServicePoint objects:

$servicepoints->each(function ($item) {
    $item->id;
    $item->name;
    $item->latitude;
    $item->longitude;
    $item->distance;
    $item->distanceForHumans();
});

Usage with Laravel

You may incorporate this package in your Laravel application by using this package.

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Mark van den Broek
• All Contributors

License

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