> For the complete documentation index, see [llms.txt](https://apidocs.gsped.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.gsped.com/gsped-api-english-version/spedizioni-e-dintorni/shipment/corrieri/dhl.md).

# DHL

## Gsped code list

<table data-full-width="true"><thead><tr><th>Service</th><th data-type="number">Courier code</th><th data-type="number">Service code</th><th>Notes</th></tr></thead><tbody><tr><td>Domestic Express</td><td>104</td><td>0</td><td>Domestic</td></tr><tr><td>Domestic Express H12</td><td>104</td><td>1</td><td>Domestic</td></tr><tr><td>Domestic Express H10:30</td><td>104</td><td>2</td><td>Domestic</td></tr><tr><td>Domestic Express H9</td><td>104</td><td>4</td><td>Domestic</td></tr><tr><td>Express Worldwide H12</td><td>104</td><td>7</td><td>International</td></tr><tr><td>Economy Select</td><td>104</td><td>8</td><td>International</td></tr><tr><td>Express Worldwide</td><td>104</td><td>9</td><td>International</td></tr><tr><td>Express Worldwide H9</td><td>104</td><td>10</td><td>International</td></tr><tr><td>Medical Express</td><td>104</td><td>20</td><td>Domestic / International</td></tr></tbody></table>

## DHL ICS2 (CIN)

For non-EU shipments the courier requires the following to be set in the Shipment call:

* **REQUIRED: ddt\_alpha** Alphanumeric reference
* [dettagli\_ordine](https://apidocs.gsped.com/gsped-api-english-version/spedizioni-e-dintorni/shipment/shipment-objects/dettagli_ordine)
* Optional: invoice\_date
* Optional: invoice\_number
* Optional: [additional\_charges](https://apidocs.gsped.com/gsped-api-english-version/spedizioni-e-dintorni/shipment/shipment-objects/courierdata/additional_charges)

### Additional Charges

You can define values that are not related to the actual value of the goods, such as shipping costs, packaging costs etc.\
To pass them to DHL you must fill in the [**additional\_charges**](https://apidocs.gsped.com/gsped-api-english-version/spedizioni-e-dintorni/shipment/shipment-objects/courierdata/additional_charges) section; below is the full list of available fields:

```json
"courierData": {
      "additional_charges": {
        "administration": 1,
        "delivery": 0,
        "documentation": 0,
        "expedit": 0,
        "export": 0,
        "freight": 0,
        "fuel": 0,
        "logistic": 0,
        "other": 0,
        "packaging": 0,
        "pickup": 0,
        "handling": 0,
        "vat": 0,
        "insurance": 0,
        "reverse": 0
      }
    }
```

## Sales invoices

You can send the Shipper's invoice data (for now only the VAT number / tax code) to the courier by setting the *fattura\_dhl* field as follows

```json
"fattura_dhl": [
    {
      "codice_fiscale": "02554360061", // codice fiscale o partita iva
      "pec": null,
      "sdi": "0000000",
      "nome": "Nome intestatario",
      "indirizzo": "Indirizzo completo",
      "cap": "20148",
      "citta": "Milano",
      "provincia": "MI",
      "nazione": "IT",
      "type": "privato",
      "email": "noreply@gsped.com",
      "nolo": 18.01,
      "totale_fattura": 18.01,
      "assicurazione": null,
      "valore": 0
    }
```

## Third-party billing

For DHL you can give a third party's client codes to charge them the shipping costs and/or the customs duties.

Below are some example payloads to use in the various cases:

**Shipping costs and customs duties to a third party:**

```json
"parties": {
        "freightPayer": {
            "country": "IT",
            "clientCode": "abcdef"
        },
        "customsPayer": {
            "country": "IT",
            "clientCode": "ghjki"
        }
    }
```

{% hint style="danger" %}
**WARNING:**

If the third-party code is based in the same country the shipment is destined to, the client code **MUST** be of type **IMPORT**
{% endhint %}

**Shipping costs to a third party:**

```json
"parties": {
        "freightPayer": {
            "country": "IT",
            "clientCode": "abcdef"
        }
    }
```

**Customs duties to a third party:**

```json
"parties": {
        "customsPayer": {
            "country": "IT",
            "clientCode": "ghjki"
        }
    }
```

## Customs codes for international shipments

For international shipments where the goods are subject to customs checks, you may need to give specific codes used by customs, such as the ITN code for **export** shipments from the United States.

Each code to give to the courier consists of two pieces of information: the code type (what it corresponds to) and its value.

Here is an example of the payload to use:

```json
"dhl": {
        "invoiceReferences": {
            "ITN": "codice_123",
            "FTR": "codice_456"
        }
    }
```

Below is the list of codes accepted by the courier:

* ACL -> Parent Shipment ID for BBX
* CID -> Customer Identifier
* CN -> Contract Number
* CU -> Consignor reference number
* ITN -> US Export declaration reference ID
* MRN -> Movement Reference number
* UCN -> Unique reference of a consignment (UCRN)
* OID -> Order Number
* PON -> Purchase Order Number
* RMA -> RMA Number
* AAM -> AWB Ref #
* ABT -> Goods Declaration number
* ADA -> Buyer Reference number
* AES -> AES Post Clearance
* AFD -> 1496 Item number
* ANT -> Consignee Reference number
* BKN -> Booking Number
* BOL -> Bill of Lading Number
* CDN -> Customs Declaration number
* COD -> Cash On Delivery
* DSC -> Weltpaket Reference
* FF -> Freight forwarder's reference number
* FN -> Freight bill number
* FTR -> Post Clearance Exemption US
* HWB -> Shipment Identifiers
* IBC -> Inbound center reference number
* IPP -> Insurance Policy Provider
* LLR -> Load list reference
* MAB -> Master Airwaybill Number
* MWB -> MAWB Reference number
* NLR -> ECCN - No License Required indicator (NLR)
* OBC -> Outbound center reference number
* PD -> Vendor Reference Number
* PRN -> Pickup request number
* RTL -> Return Leg waybill number
* SID -> Shipment ID 15 Digit CODA
* SS -> Seller Reference number
* SWN -> Original Waybill number (Return)

## Go Green Plus service

Low-emission transport services, enabled by sustainable aviation fuel.

```json
"dhl": {
        "goGreenPlus": true
    }
```

## Adult Signature service

DHL will require a delivery signature from an adult at the agreed delivery address.

```json
"dhl": {
        "adultSignature": true
    }
```

## Direct Signature service

DHL will obtain the signature from the recipient or from a representative at the delivery address. If nobody is at the delivery address, DHL will attempt delivery again. The Direct Signature service ensures that your shipments cannot be redirected, left in a mailbox or left with a neighbour.

```json
"dhl": {
        "directSignature": true
    }
```

## Proactive Tracking

Monitoring of your shipment's transit, with real-time incident and delivery notifications.

```json
"dhl": {
        "proactiveTracking": true
    }
```

## Editing a shipment (Shipment PATCH)

### Adding an electronic document to a shipment

To upload documents later, i.e. after the shipment has been created, you must state it explicitly when creating the shipment with the **Shipment POST**, because the courier **needs to know that documents will be uploaded later for a specific shipment.**

The parameter to use is **uploadDocAfterwards,** and it goes inside the **courierData** field.

Here is the documentation:

{% content-ref url="<https://apidocs.gsped.com/gsped-api-english-version/spedizioni-e-dintorni/shipment/shipment-objects/courierdata/uploaddocafterwards>" %}
<https://apidocs.gsped.com/gsped-api-english-version/spedizioni-e-dintorni/shipment/shipment-objects/courierdata/uploaddocafterwards>
{% endcontent-ref %}

## Barcode on the label

DHL lets you put a barcode on the label.

Payload to use when creating the shipment:

```json
"dhl": {
        "customerBarcode": {
            "barcodeType": TIPO_BARCODE,
            "barcodeContent": CONTENUTO_BARCODE,
            "textBelowBarcode": TESTO_DA_RIPORTARE_SOTTO_IL_BARCODE [OPZIONALE]
        }
    }
```

Where:

* **barcodeType:** Barcode type. Allowed values --> 39, 93 and 128
* **barcodeContent:** Content that will be shown as a barcode
* **textBelowBarcode:** This field is optional and is the text that will be shown below the barcode.

{% hint style="info" %}
**WARNING:**

In multi-parcel shipments, the barcode will be shown on all labels (you cannot have a different code for each of them)
{% endhint %}

{% hint style="info" %}
**WARNING:**

If you use ZPL labels, keep in mind that with this feature the labels provided by the courier will be in **10x20 CM** format
{% endhint %}

## Label-Free / Label-Less shipments

DHL lets you create shipments that do not require a label: the courier will not return a label, but a QR Code that the sender must show when handing over the parcel to be shipped at the DHL service point.

This type of service is very useful for returns, where the end customer can essentially bring their package to the service point and, by showing the QR code on their phone, drop off the parcel to be shipped or returned without having to print the label at home.

The shipment creation request through Shipment must include the following:

```json
"courierData": {
        "labelLessReturn": true
    }
```

Here is an example of the returned QrCode:

<figure><img src="https://1888732240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSMqbryyHACmde6RvwRY%2Fuploads%2F8DUfU2ITwqnhsymBAN0a%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>