# DHL Parcel UK Cloud

### <span style="color: rgb(245, 89, 64);">**Setting Up DHL Parcel UK Cloud**</span>

This document provides a step-by-step guide to integrating DHL Parcel UK Cloud with <span style="color: rgb(245, 89, 64);">**Voila**</span>. Follow these instructions to integrate DHL Parcel UK Cloud into your system:

1. Begin by **navigating** to the left panel and hovering your cursor over "API Accounts."
2. **Click** the plus icon to initiate the setup process under your preferred API Account.
3. In the first row, **choose** "DHL Parcel UK Cloud" from the list of available options.
4. The following fields are required for setting up DHL Parcel UK Cloud integration: 
    - **<span data-preserver-spaces="true">Company</span>**<span data-preserver-spaces="true">: **Enter** any identifier you prefer.</span>
    - **<span data-preserver-spaces="true">Testing</span>**<span data-preserver-spaces="true">: This is a simple **yes or no** selection. If enabled, the information will not be transmitted to the courier through their API, making it suitable for testing.</span>
    - **<span data-preserver-spaces="true">Client\_ID, Client\_Secret, Pickup\_Account</span>**<span data-preserver-spaces="true">: You can obtain these credentials in two ways:  
        </span>
        - <span data-preserver-spaces="true">**Through your Account Manager**: If you are unsure who your account manager is, DHL's customer service team can assist you.</span>
        - <span data-preserver-spaces="true">**Via the DHL Developers Portal**: Visit the **[DHL Developers Portal](https://developer.dhl.com/api-reference/parcel-uk#get-started-section/)** to request the necessary credentials.</span>
    - **<span data-preserver-spaces="true">Notes</span>**<span data-preserver-spaces="true">: Use this field to **enter** relevant information or notes regarding this courier. It will only be visible to you.</span>
5. To complete the setup, **click** on "Save Changes."

By following these steps, you will successfully configure the DHL Parcel UK Cloud integration with your <span style="color: rgb(245, 89, 64);">**Voila**</span> account.

<video controls="controls" height="479" src="https://shipping-documentation.despatchcloud.app/attachments/118?open=true" style="width: 852px; height: 479px;" width="852"></video>

<p class="callout info">**Click to Play or Pause the video**</p>

### <span style="color: rgb(245, 89, 64);">**The Authentication Process**</span>

<span data-preserver-spaces="true">An authentication process is initiated when you add your customer number, trading account, client ID, and secret to the system. This process involves calling DHL to fetch the trading location ID, a crucial element required for ad hoc collection customers.</span>

<span data-preserver-spaces="true">There are three potential outcomes of this authentication process:</span>

1. **<span data-preserver-spaces="true">Successful Response:</span>**<span data-preserver-spaces="true"> The authentication is successful, and the trading location ID is retrieved as expected.</span>
2. **<span data-preserver-spaces="true">Failed Response:</span>**<span data-preserver-spaces="true"> If the account number provided is not found or any other authentication failure occurs, a failed response is generated.</span>
3. **<span data-preserver-spaces="true">Partial Success:</span>**<span data-preserver-spaces="true"> Sometimes, the authentication process may result in partial success. Although the authentication succeeds in this scenario, the trading location ID is not found. Consequently, ad hoc collections become impossible. However, to alert users about this limitation, an amber warning is issued, stating: "No trading location ID found, ad hoc collections will not be possible."</span>

<span data-preserver-spaces="true">This authentication mechanism ensures secure integration of DHL Parcel UK Cloud services with customer accounts while providing clear feedback on authentication status and any potential limitations encountered.</span>

### <span style="color: rgb(245, 89, 64);">**Set Up a Collection Using the API**</span>

This process ensures the smooth addition of DHL Parcel UK Cloud to the courier directory and facilitates the creation of collections as needed.

You can submit the below JSON payload to the following endpoint:

- `https://production.courierapi.co.uk/api/couriers/v1/DHLParcelUKCloud/create-collection`

The following JSON code serves as an example for initiating a collection, referred to as a pickup by DHL. This action is necessary only when a daily collection has not been pre-scheduled with the courier. Utilise the provided code structure:

```JSON
{
    "auth_company": "xxx",
    "testing": false,
    "collection": {
        "customer_account_number": "CUS-049XX4",
        "trading_location_id": "A0V3L0000012X49XXX",
        "time_ready": "16:00",
        "latest_time": "17:00",
        "instructions": "Please pick up from door 12 at the back of the warehouse."
    }
}
```