netresearch / dhl-sdk-api-bcs

Library package encapsulating API communication to the DHL Geschäftskundenversand 3.0 web service.

DHL BCS API SDK

The DHL Business Customer Shipping API SDK package offers an interface to the following web services:

• Geschäftskundenversand 3.1.2
• DHL Parcel DE Shipping 2.1.6

Requirements

System Requirements

• PHP 7.2+ with SOAP and JSON extension

Package Requirements

• league/openapi-psr7-validator: Schema validator for JSON request messages
• 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
• squizlabs/php_codesniffer: Static analysis tool

Installation

$ composer require dhl/sdk-api-bcs

Uninstallation

$ composer remove dhl/sdk-api-bcs

Testing

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

Features

The DHL BCS API SDK is able to connect to the legacy Business Customer Shipping SOAP API as well as its successor, the Parcel DE Shipping REST web service.

While the connection to the REST API includes some shipping services that were introduced after BCS v3.1.2, both connections share the same high-level functionality:

• Validate Shipment: Validate a shipment order without booking a label
• Create Shipment Order: Book a shipment label
• Delete Shipment Order: Cancel a shipment label

Please note that the Parcel DE Shipping REST API takes different arguments in some cases:

• sandbox credentials and EKP
• countries must be specified as three-letter codes

Authentication

Both APIs require a two-level authentication to identify application and user. The API SDK offers an authentication storage to pass credentials in.

// BCS
$authStorage = new \Dhl\Sdk\Paket\Bcs\Auth\AuthenticationStorage('appId', 'appToken', 'user', 'signature');

// Parcel DE Shipping
$authStorage = new \Dhl\Sdk\Paket\Bcs\Auth\AuthenticationStorage('', 'apiKey', 'user', 'password');

• API user credentials (user and signature/password) are created in the DHL Business Customer Portal
• SOAP access: application ID and token are created in the Developer Portal
• REST access: API key is created in the API Developer Portal

API Selection

By default, the SDK connects to the legacy Business Customer Shipping SOAP API. In order to switch to the REST web service, pass an additional argument to the service factory:

$serviceFactory = new \Dhl\Sdk\Paket\Bcs\Service\ServiceFactory(
    \Dhl\Sdk\Paket\Bcs\Api\ServiceFactoryInterface::API_TYPE_REST
);

When using the request builder to create outgoing messages, then pass the respective argument there as well:

$requestBuilder = new \Dhl\Sdk\Paket\Bcs\RequestBuilder\ShipmentOrderRequestBuilder(
    \Dhl\Sdk\Paket\Bcs\Api\ShipmentOrderRequestBuilderInterface::REQUEST_TYPE_REST
);

More thorough examples on using service factory and request builder can be found in the section about web service operations.

Web Service Operations

Validate Shipment

Validate shipments for DHL Paket including the relevant shipping documents.

Public API

The library's components suitable for consumption comprise

• services:
  • service factory
  • shipment service
  • data transfer object builder
• data transfer objects:
  • authentication storage
  • order/label settings
  • validation result with status message

Usage

$logger = new \Psr\Log\NullLogger();

$serviceFactory = new \Dhl\Sdk\Paket\Bcs\Service\ServiceFactory();
$service = $serviceFactory->createShipmentService($authStorage, $logger, $sandbox = true);

$requestBuilder = new \Dhl\Sdk\Paket\Bcs\RequestBuilder\ShipmentOrderRequestBuilder();
$requestBuilder->setShipperAccount($billingNumber = '22222222220101');
$requestBuilder->setShipperAddress(
    $company = 'DHL',
    $country = 'DE',
    $postalCode = '53113',
    $city = 'Bonn',
    $street = 'Charles-de-Gaulle-Straße',
    $streetNumber = '20'
);
$requestBuilder->setRecipientAddress(
    $recipientName = 'Jane Doe',
    $recipientCountry = 'DE',
    $recipientPostalCode = '53113',
    $recipientCity = 'Bonn',
    $recipientStreet = 'Sträßchensweg',
    $recipientStreetNumber = '2'
);
$requestBuilder->setShipmentDetails($productCode = 'V01PAK', $shipmentDate = '2019-09-09');
$requestBuilder->setPackageDetails($weightInKg = 2.4);

$shipmentOrder = $requestBuilder->create();
$result = $service->validateShipments([$shipmentOrder]);

Create Shipment Order

Create shipments for DHL Paket including the relevant shipping documents. In addition to the primary shipment data (shipper, consignee, etc.), further settings can be defined per request via the order configuration object, including label printing size, profile, and more.

Public API

The library's components suitable for consumption comprise

• services:
  • service factory
  • shipment service
  • data transfer object builder
• data transfer objects:
  • authentication storage
  • order/label settings
  • shipment with shipment/tracking number and label(s)

Usage

$logger = new \Psr\Log\NullLogger();

$serviceFactory = new \Dhl\Sdk\Paket\Bcs\Service\ServiceFactory();
$service = $serviceFactory->createShipmentService($authStorage, $logger, $sandbox = true);

$orderConfiguration = new \Dhl\Sdk\Paket\Bcs\Service\ShipmentService\OrderConfiguration(
    $printOnlyIfCodable = true,
    $combinedPrinting = null,
    $docFormat = \Dhl\Sdk\Paket\Bcs\Api\Data\OrderConfigurationInterface::DOC_FORMAT_PDF,
    $printFormat = \Dhl\Sdk\Paket\Bcs\Api\Data\OrderConfigurationInterface::PRINT_FORMAT_A4
);

$requestBuilder = new \Dhl\Sdk\Paket\Bcs\RequestBuilder\ShipmentOrderRequestBuilder();
$requestBuilder->setShipperAccount($billingNumber = '22222222220101');
$requestBuilder->setShipperAddress(
    $company = 'DHL',
    $country = 'DE',
    $postalCode = '53113',
    $city = 'Bonn',
    $street = 'Charles-de-Gaulle-Straße',
    $streetNumber = '20'
);
$requestBuilder->setRecipientAddress(
    $recipientName = 'Jane Doe',
    $recipientCountry = 'DE',
    $recipientPostalCode = '53113',
    $recipientCity = 'Bonn',
    $recipientStreet = 'Sträßchensweg',
    $recipientStreetNumber = '2'
);
$requestBuilder->setShipmentDetails($productCode = 'V01PAK', $shipmentDate = '2019-09-09');
$requestBuilder->setPackageDetails($weightInKg = 2.4);

$shipmentOrder = $requestBuilder->create();
$shipments = $service->createShipments([$shipmentOrder], $orderConfiguration);

Delete Shipment Order

Cancel earlier created shipments.

Public API

The library's components suitable for consumption comprise

• services:
  • service factory
  • shipment service
• data transfer objects:
  • authentication storage

Usage

$logger = new \Psr\Log\NullLogger();

$serviceFactory = new \Dhl\Sdk\Paket\Bcs\Service\ServiceFactory();
$service = $serviceFactory->createShipmentService($authStorage, $logger, $sandbox = true);

$shipmentNumber = '222201011234567890';
$cancelled = $service->cancelShipments([$shipmentNumber]);

dhl-sdk-api-bcs's Issues

Validate Shipments Error

Hi I am trying to test this dhl package using REST API.

I have this:

       $dhl->setApiKey($apiKey);

        $authStorage = $dhl->getAuthenticationStorage();
        $serviceFactory = $dhl->getServiceFactory();
        $logger = new NullLogger();
        $service = $serviceFactory->createShipmentService($authStorage, $logger, true);
        $requestBuilder = $dhl->getRequestBuilder();
        $requestBuilder->setShipperAccount($dhl->getBillNumberLocal());
        $requestBuilder->setShipperAddress(
            'DHL',
            'DE',
            '53113',
            'Bonn',
            'Charles-de-Gaulle-Straße',
            '20'
        );
        $requestBuilder->setRecipientAddress(
            'Jane Doe',
            'DE',
            '53113',
            'Bonn',
            'Sträßchensweg',
            '2'
        );
        $requestBuilder->setShipmentDetails($dhl->getProductCodeLocal(), new DateTime());
        $requestBuilder->setPackageDetails(2.4);
        
        $shipmentOrder = $requestBuilder->create();
        $result = $service->validateShipments([$shipmentOrder]);

Evething has default values as described in readme file execept I am using REST API with product code 33333333330101

Here are the dhl funcions

    /**
     * Creates the AuthenticationStorage for the DHL (REST API).
     */
    public function getAuthenticationStorage(): AuthenticationStorage
    {
        return new AuthenticationStorage('', $this->apiKey, $this->username, $this->password);
    }

    /**
     * Creates the ServiceFactory for the DHL (REST API).
     */
    public function getServiceFactory(): ServiceFactory
    {
        return new ServiceFactory(ShipmentOrderRequestBuilderInterface::REQUEST_TYPE_REST);
    }

    /**
     * Creates the ShipmentOrderRequestBuilder for the DHL (REST API).
     */
    public function getRequestBuilder(): ShipmentOrderRequestBuilder
    {
        return new ShipmentOrderRequestBuilder(ShipmentOrderRequestBuilder::REQUEST_TYPE_REST);
    }

But I am getting :

Missing detailed error description when label could not be created

We couldn't create a label and got the error:

Versandetikett konnte nicht erstellt werden: Keyword validation failed: Data must match exactly one schema, but matched none. Value: "{"name1":"Anonymized","addressStreet":"Anonymized","postalCode":"12345 ","city":"Anonymized","country":"DEU","addressHouse":"3"}". Path: "shipments[0]"

The error tells nothing about the reason. The real reason is hidden in League\OpenAPIValidation\Schema\Exception\NotEnoughValidSchemas::$innerExceptions.

But this property is swallowed and is not evaluated or shown to the user. The $innerExceptions contains the errors why the four different schemas ContactAddress, Locker, PostOffice and POBox failed.

In our case, those four errors were:

Keyword validation failed: Data does not match pattern '#^[0-9A-Za-z]+([ -]?[0-9A-Za-z]+)*$#u'
Keyword validation failed: Required property 'lockerID' must be present in the object
Keyword validation failed: Required property 'name' must be present in the object
Keyword validation failed: Required property 'poBoxID' must be present in the object

Since it was a contact address, the pattern #^[0-9A-Za-z]+([ -]?[0-9A-Za-z]+)*$#u did not match. While not visible at the first glance, this means the postal code could not be validated. In our case the postal code contained a trailing space, leading to the failed generation of the shipping label. The trailing space was not visible in the GUI.

So it would be nice if the real reason, the innerExceptions would be presented to the user, so he immediately sees, why the label could not be generated.

International Shipping Sender Endorsement

Error:

Error 400: 0 of 1 shipment validated OK. Details included.
[1] A hard validation error occured in the shipment.
Warning (services.endorsement): Please note that for Shipments using the product "DHL Paket International" the service "Endorsement (Sender's Instructions)" is mandatory.

In ShipmentOrderRequestBuilderInterface.php
I can see:

public const ENDORSEMENT_TYPE_IMMEDIATE = 'IMMEDIATE';
public const ENDORSEMENT_TYPE_ABANDONMENT = 'ABANDONMENT';

But in the API documentations it seems that type is RETURN :

$this->requestBuilder = new ShipmentOrderRequestBuilder(ShipmentOrderRequestBuilder::REQUEST_TYPE_REST);
$this->requestBuilder->setShipmentEndorsementType(ShipmentOrderRequestBuilderInterface::ENDORSEMENT_TYPE_IMMEDIATE);

Does IMMEDIATE means RETURN ? Thanks.

how to get geschaeftskunden credentials

Hi
I am trying to implement your API on my Laravel project but not able to get below details. How can I get below details
'appId', 'appToken', 'user', 'signature'