## DHL ICS2 (CIN)
Per le spedizioni extraUe il corriere richiede obbligatoriamente che nella chiamata Shipment vengano valorizzati:
* **RICHIESTO: ddt\_alpha** Riferimento alfanumerico
* [dettagli\_ordine](/spedizioni-e-dintorni/shipment/shipment-objects/dettagli_ordine.md)
* Opzionale: invoice\_date
* Opzionale: invoice\_number
* Opzionale: [additional\_charges](/spedizioni-e-dintorni/shipment/shipment-objects/courierdata/additional_charges.md)
### Additional Charges
E' possibile definire dei valori che non sono relativi al valore reale della merce, come ad esempio i costi di spedizione, costi di packaging etc.\
Per passarli a DHL bisogna compilare la sezione [**additional\_charges**](/spedizioni-e-dintorni/shipment/shipment-objects/courierdata/additional_charges.md), di seguito la lista completa dei campi disponibili:
```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
}
}
```
## Fatture attive
C'è la possibilità di inviare dati della fattura (per ora solamente la p.iva / codice fiscale) dello Shipper al corriere valorizzando il campo *fattura\_dhl* in questo modo
```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
}
```
## Addebito terzo
Per DHL è stato reso possibile indicare i codici clienti di un terzo per addebitargli i costi di spedizione e/o gli oneri doganali.
Di seguito alcuni esempi di payload da utilizzare nelle varie casistiche :
**Costi spedizione e oneri doganali a terzo :**
```json
"parties": {
"freightPayer": {
"country": "IT",
"clientCode": "abcdef"
},
"customsPayer": {
"country": "IT",
"clientCode": "ghjki"
}
}
```
{% hint style="danger" %}
**ATTENZIONE:**
In caso il codice terzo sia radicato nella stessa nazione in cui è destinata la spedizione, il codice cliente **DEVE** essere di tipo **IMPORT**
{% endhint %}
**Costi spedizione a terzo e oneri doganali a mittente :**
```json
"parties": {
"freightPayer": {
"country": "IT",
"clientCode": "abcdef"
}
}
```
**Costi spedizione a mittente e oneri doganali a terzo :**
```json
"parties": {
"customsPayer": {
"country": "IT",
"clientCode": "ghjki"
}
}
```
## Codici utili alla dogana in spedizioni internazionali
Per le spedizioni internazionali dove la merce è soggetta a controlli doganali, vi può essere la necessità di indicare dei codici specifici utili alla doaana, come può essere ad esempio il codice ITN per le spedizioni in **export** dagli Stati Uniti.
Ogni codice da indicare al corriere è composto da due informazioni : Il tipo di codice (a cosa corrisponde) ed il rispettivo valore.
Ecco un esempio del payload da utilizzare :
```json
"dhl": {
"invoiceReferences": {
"ITN": "codice_123",
"FTR": "codice_456"
}
}
```
Di seguito l'elenco di codici ammessi dal corriere :
* 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)
## Servizio Go Green Plus
Servizi di trasporto a basse emissioni, facilitati da carburante per l'aviazione sostenibile.
```json
"dhl": {
"goGreenPlus": true
}
```
## Servizio Firma Adulto
DHL richiederà la firma di consegna da parte di un adulto all'indirizzo di consegna concordato.
```json
"dhl": {
"adultSignature": true
}
```
## Servizio Firma Diretta
DHL otterrà la firma dal destinatario o da un rappresentante all'indirizzo di consegna. Nel caso in cui non ci sia nessuno all'indirizzo di consegna, DHL ritenterà la consegna. Il servizio Firma Diretta assicura che le tue spedizioni non possano essere reindirizzate, lasciate in una cassetta postale o lasciate al vicino.
```json
"dhl": {
"directSignature": true
}
```
## Proactive Tracking
Monitoraggio del transito della tua spedizione, con incidenti e notifiche di consegna in tempo reale.
```json
"dhl": {
"proactiveTracking": true
}
```
## Modifica di una spedizione (Shipment PATCH)
{% hint style="danger" %}
**ATTENZIONE! nel caso in cui sia attivata la generazione della proforma automatica non è possibile eseguire la patch della spedizione**
{% endhint %}
Di seguito un payload completo dei dati aggiornabili senza la necessità di ribollettazione delle spedizione:
```json
{
"currency": "EUR",
"order_ref": "Rif. modificato 3",
"invoice_date": "2024-09-20",
"invoice_number": "123",
"incoterm": {
"incoterm_code": "FCA",
"location": "C.So felice cavallotti 4 15121 Alessandria"
},
"dettagli_ordine": [
{
"sku": "PBK1_mod",
"description": "Cosa verde",
"qty": "2",
"um": "KG",
"barcode_riga": "11111111",
"hs_code": "222222222",
"prezzo_singolo": "20",
"peso_riga": "3",
"country_of_origin": "FR"
},
{
"sku": "PBK12",
"description": "Cosa nera",
"qty": "1",
"um": "BOX",
"barcode_riga": "12345465",
"hs_code": "123456454",
"prezzo_singolo": "7",
"peso_riga": "1",
"country_of_origin": "FR"
}
],
"courierData": {
"additional_charges": {
"fuel": 1
}
},
"dhl": {
"invoiceReferences": {
"ITN": "codice_123"
}
}
}
```
{% hint style="danger" %}
**N.B.** è possibile mandare solo alcuni dati ma gli oggetti della chiamata: dettagli\_ordine, courierData, dhl se ci sono devono essere completi, i precedenti valori verranno sovrascritti!
{% endhint %}
### Aggiungere Documento elettronico a spedizione
Per poter caricare documenti postumi, ovvero dopo aver generato la spedizione, all'atto della creazione della spedizione con la **Shipment POST** bisogna indicarlo esplicitamente, dato che il corriere **ha bisogno di sapere che per una specifica spedizione verranno caricati dei documenti in un secondo momento.**
Il parametro da utilizzare è **uploadDocAfterwards,** ed è da indicare all'interno del campo **courierData**.
Esempio :
```json
{
"client_id": "CLIENT_ID_SPECIFICO",
"corriere": 104,
"servizio": 8,
"ddt_alpha": "S012507NOR22668",
"ddt_num": "5123025",
"merce": "Descrizione",
"origine": "IT",
"courierData": {
"uploadDocAfterwards": true
},
"peso": 0.92,
"colli": 1,
"dettagli_ordine": [
{
"sku": "PBK1",
"description": "Cosa blu",
"qty": "1",
"um": "PCS",
"barcode_riga": "12345464",
"hs_code": "123456454",
"prezzo_singolo": "12.50",
"peso_riga": "1",
"country_of_origin": "IT"
},
{
"sku": "PBK12",
"description": "Cosa blu e rossa",
"qty": "1",
"um": "BOX",
"barcode_riga": "12345465",
"hs_code": "123456454",
"prezzo_singolo": "25.00",
"peso_riga": "1",
"country_of_origin": "FR"
}
],
"daticolli": [
{
"altezza": 21.5,
"larghezza": 30,
"lunghezza": 20,
"peso": 0.92,
"volume": 0.0129
}
],
"rcpt_phone": "32781012345",
"rcpt_name": "Test destinatario",
"rcpt_contact": "Test destinatario",
"rcpt_addr": "3 Springett Way, coxheath",
"rcpt_cap": "ME174HQ",
"rcpt_city": "Maidstone",
"rcpt_country_code": "GB",
"rcpt_prov": "GB",
"rcpt_email": "test@gsped.net",
"sender_name": "Test mittente",
"sender_addr": "Via Cal Longa 10",
"sender_city": "Santa Giustina",
"sender_prov": "BL",
"sender_cap": "32035",
"sender_country_code": "IT",
"sender_contact": "Test mittente",
"sender_email": "test@gsped.it"
}
```
Una volta generata la spedizione utilizzando questa opzione, sarà possibile aggiungere il documento alla spedizione attraverso la Shipment PATCH utilizzando il seguente payload :
```json
{
"trade_documents": [
{
"nome": "COMMERCIAL_INVOICE_5123025_1.pdf",
"contenuto": "Tm90aWNlDQpJbi......"
}
]
}
```
## Barcode in etichetta
DHL offre la possibilità di inserire in etichetta un codice barcode.
Payload da utilizzare al momento della creazione della spedizione :
```json
"dhl": {
"customerBarcode": {
"barcodeType": TIPO_BARCODE,
"barcodeContent": CONTENUTO_BARCODE,
"textBelowBarcode": TESTO_DA_RIPORTARE_SOTTO_IL_BARCODE [OPZIONALE]
}
}
```
Dove :
* **barcodeType :** Tipologia di Barcode. Valori ammessi --> 39, 93 e 128
* **barcodeContent :** Contenuto che verrà riportato sotto forma di Barcode
* **textBarlowBarcode :** Questo campo è opzionale e sarà il testo che verrà riportato sotto il barcode.
{% hint style="info" %}
**ATTENZIONE :**
Nelle spedizioni multicollo, il barcode verrà riportato su tutte le etichette (non è possibile avere un codice diverso per ognuna di esse)
{% endhint %}
{% hint style="info" %}
**ATTENZIONE :**
Se utilizzate le etichette ZPL, dovete tenere a mente che con questa funzionalità le etichette fornite dal corriere saranno in formato **10x20 CM**
{% endhint %}
## Spedizioni Label-Free / Label-Less
DHL offre la possibilità di generare spedizioni sulle quali non viene richiesta un etichetta, ovvero, il corriere non restiuirà un etichetta, ma ritornerà un QR Code che il mittente dovrà mostrare all'atto della consegna del collo da spedire nel service point DHL.
Questi tipo di servizio è molto utile per i resi, dove sostanzialmente viene permesso al cliente finale di portare il proprio pacchetto da spedire al service point e, fornendo il QR code dal proprio cellulare, depositare il collo da inviare o rendere senza dover stampare l'etichetta a casa.
Nella richiesta di generazione spedizione attraverso la Shipment dovrà essere indicato quanto segue:
```json
"courierData": {
"labelLessReturn": true
}
```
Ecoo un esempio del QrCode restituito :
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://apidocs.gsped.com/spedizioni-e-dintorni/shipment/corrieri/dhl.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.