README

The DHL Parcel DE Returns API SDK package offers an interface to the following web services:

• Returns API

Requirements

System Requirements

• PHP 8.1+ with JSON extension

Package Requirements

• netresearch/jsonmapper: Mapper for deserialization of JSON response messages into PHP objects
• php-http/discovery: Discovery service for HTTP client and message factory implementations
• php-http/httplug: Pluggable HTTP client abstraction
• php-http/logger-plugin: HTTP client logger plugin for HTTPlug
• psr/http-client: PSR-18 HTTP client interfaces
• psr/http-factory: PSR-7 HTTP message factory interfaces
• psr/http-message: PSR-7 HTTP message interfaces
• psr/log: PSR-3 logger interfaces

Virtual Package Requirements

• psr/http-client-implementation: Any package that provides a PSR-18 compatible HTTP client
• psr/http-factory-implementation: Any package that provides PSR-7 compatible HTTP message factories
• psr/http-message-implementation: Any package that provides PSR-7 HTTP messages

Development Package Requirements

• nyholm/psr7: PSR-7 HTTP message factory & message implementation
• phpunit/phpunit: Testing framework
• php-http/mock-client: HTTPlug mock client implementation
• phpstan/phpstan: Static analysis tool
• fig/log-test: PSR-3 logger implementation for testing purposes
• squizlabs/php_codesniffer: Static analysis tool
• rector/rector: Automatic refactoring tool to help with PHP upgrades

Installation

composer require dhl/sdk-api-parcel-de-returns

Uninstallation

composer remove dhl/sdk-api-parcel-de-returns

Testing

./vendor/bin/phpunit -c test/phpunit.xml

Features

The DHL Parcel DE Returns API SDK supports the following features:

• Book return labels (POST /orders)

Authentication

The DHL Parcel DE Returns API requires a two-level authentication (see API User Guide):

1. The application submits a Consumer Key Header ("API Key") that must be created in the DHL API Developer Portal.
2. The user is identified via HTTP Basic Authentication with credentials configured in the DHL Business Customer Portal.

These credentials are passed to the SDK via \Dhl\Sdk\ParcelDe\Returns\Api\Data\AuthenticationStorageInterface. Use the default implementation or create your own.

Book Return Label

Create a return label PDF, or a QR code to be scanned by a place of committal (e.g. post office). For return shipments from outside the EU, a customs document can also be requested.

The destination address of the return shipment is determined via Receiver ID parameter. Return recipients and their ID ("Return recipient's name") are configured in the DHL Business Customer Portal, Returns Settings section. More detailed information can be found in the API FAQ.

Public API

The library's components suitable for consumption comprise

• service:
  • service factory
  • return label service
  • data transfer object builder
• data transfer objects:
  • authentication storage
  • booking confirmation with label data

Usage

$authStorage = new \Dhl\Sdk\ParcelDe\Returns\Auth\AuthenticationStorage(
    'apiKey',
    'user',
    'password'
);
$logger = new \Psr\Log\NullLogger();

$serviceFactory = new \Dhl\Sdk\ParcelDe\Returns\Service\ServiceFactory();
$service = $serviceFactory->createReturnLabelService($authStorage, $logger, $sandbox = true);

$requestBuilder = new \Dhl\Sdk\ParcelDe\Returns\Model\ReturnLabelRequestBuilder();
$requestBuilder->setReceiverId($returnRecipient = 'deu');
$requestBuilder->setShipper(
    $name = 'Jane Doe',
    $countryCode = 'DEU',
    $postalCode = '53113',
    $city = 'Bonn',
    $streetName = 'Sträßchensweg',
    $streetNumber = '2'
);

$returnOrder = $requestBuilder->create();
$confirmation = $service->createReturnOrder($returnOrder);