MyDHL è un servizio web di DHL, leader nella logistica a livello globale.
In questo articolo imparerai a collegare MyDHL a ShippyPro. Scoprirai anche le funzioni aggiuntive come la creazione di un'etichetta di reso da inserire direttamente nella scatola (return label in the box) e la Paperless Trade (documentazione Paperless). ✨
Sommario:
1. Prima di iniziare
Registrati al DHL Developer Portal
Per procedere con la connessione è necessario avere una chiave API, un API Secret e un Account Number che puoi recuperare registrandoti al DHL Developer Portal se non ne hai ancora uno.
Compila il modulo DHL
Vai su APIs > Browse all services
Clicca su DHL Express - MyDHL API
Poi su Get Access:
Compila i dati inerenti alla tua azienda
Alla voce "Come vorresti utilizzare l'API?" seleziona l'opzione "Richiedo le credenziali per DHL Express – API MyDHL per un plug-in esistente/piattaforma di ecommerce/soluzione di terze parti" e aggiungi semplicemente ShippyPro.
Per quanto riguarda la sezione denominata "Servizi richiesti", basterà selezionare tutti i servizi disponibili. Il campo "Volume delle transazioni mensili" è utile a DHL solo a fini statistici, quindi non influenzerà il tuo utilizzo dell'API.
Dopo qualche ora potrai controllare il tuo profilo DHL Developer dove dovresti essere in grado di visualizzare l'App Status come approvato.
Clicca su DHL EXPRESS - MYDHL API sotto App Name e troverai un pulsante rosso Request Production Access, una volta selezionato riceverai la conferma di invio della richiesta in pochi minuti e sarà il team DHL locale a doverla approvare secondo le loro tempistiche.
In caso la richiesta resti pendente ti invitiamo a contattare direttamente DHL per velocizzare l'approvazione.
In caso di dubbi o domande, non esitare a dare un'occhiata a questa guida DHL passo-passo.
2. Collega MyDHL a ShippyPro
Ora che tutto è impostato correttamente nel portale MyDHL, potrai collegarti a ShippyPro.
Vai su Corrieri > Connessione e clicca su logo MyDHL (digita semplicemente "MyDHL" sulla barra di ricerca per individuarlo immediatamente).
Se effettua spedizioni in contrassegno, ricordati di contrassegnare la casella "Confermo di essere a conoscenza del messaggio sottostante" (I confirm that I am aware of the below message):
Inserisci chiave API, API Secret e Account Number
❗Assicurati di evitare gli spazi quando copi e incolli, altrimenti ti apparirà il messaggio di errore "Invalid Credentials".
Scegli il tuo Tipo di etichetta e il codice prodotto. Ricordati di chiedere al tuo Account Manager DHL quali sono i tuoi codici prodotto attivi. Se desideri aggiungere più servizi, dovrai creare una nuova connessione per ognuno di questi.
Ricorda che il servizio EXPRESS WORLDWIDE NONDOC riguarda solo la merce e il servizio EXPRESS WORLDWIDE DOC riguarda i documenti e non altri tipi di beni fisici.
📌 Se vuoi includere più servizi all'interno della stessa connessione corriere, dovrai selezionare Product Code: ALL SERVICES.
📌Se dopo aver aggiunto le credenziali da Corrieri > Modifica, o dopo aver effettuato la prima spedizione, viene restituito un errore di credenziali non valide, verificare che la richiesta di credenziali sia stata effettuata correttamente e che non vi siano spazi vuoti prima o dopo tutti i dettagli delle credenziali.
3. Opzioni aggiuntive
🔁 Stampa etichette di reso
Se vuoi stampare sia l'etichetta di andata che quella di reso con una label in the box, e quindi in una sola volta, aggiungi il tuo Account Number nel campo "Account Number" e il tuo Return Account Number (impex) nel campo "Return Account Number". A questo punto, spunta la voce Enable Return Label in the box in basso e conferma.
Nota: Il formato dell'etichetta sarà quello scelto per le spedizioni in uscita. Non potrà essere cambiato per le etichette di reso.
📌 Se desideri effettuare i Resi separatamente dalla spedizione principale, devi creare una nuova connessione MyDHL: inserisci il tuo Return Account Number (impex) nel campo "Account Number" e il tuo Account Number nel campo "Return Account Number". In pratica, l'esatto opposto della prima configurazione. NON spuntare la voce Enable Return Label in the box. In questo modo puoi creare una spedizione manuale per il Reso: clicca qui per scoprire come.
Cliccando su Fixed Return Receiver Address (Only for 'Enable Return Label in the box'), se l'opzione Enable Return Label in the box è stata spuntata e si seleziona un indirizzo dal menu a tendina, le label in the box non verranno reindirizzate all'indirizzo del mittente, ma all'indirizzo impostato nel menu a tendina.
È possibile aggiungere e modificare gli indirizzi disponibili in qualsiasi momento da Amministrazione > I miei indirizzi e pacchi > I miei indirizzi.
🧾 Generare una fattura in formato DHL
Questa funzione ti permetterà di stampare automaticamente le tue fatture per le spedizioni internazionali (Generat Invoice with DHL format). Puoi scegliere se generare una fattura proforma o commerciale.
Selezionando questa opzione, la fattura verrà generata insieme all'etichetta di spedizione!
🌱 Paperless Trade
Puoi decidere di attivare l'opzione Paperless selezionando "Paperless Trade" da Corrieri > MyDHL > Modifica. In questo caso, sarà necessario trasmettere digitalmente al corriere una fattura caricando la fattura ETD dalla pagina Label Creator > Invoice Manager, tramite la chiamata API UploadPaperlessDocumentation, oppure richiedendo a DHL la generazione di una fattura con il loro formato (in questo caso, leggere i punti successivi).
È anche possibile caricare il tipo di dichiarazione doganale da Label Creator > Invoice Manager e decidere di attivare l'opzione Generate Invoice with DHL format da Corrieri > MyDHL > Modifica.
È importante notare che al momento del caricamento della documentazione è necessario selezionare la tipologia corretta, ad esempio "Dichiarazione doganale".
Se selezionate entrambe le opzioni Generate Invoice with DHL format e Paperless da Corrieri > MyDHL > Modifica, e caricate la dichiarazione doganale da Label Creator > Invoice Manager, sia la fattura commerciale che la dichiarazione doganale saranno trasmesse elettronicamente al corriere.
Alcuni esempi pratici:
l'opzione "Paperless Trade" è abilitata, ma non è stato né caricato l'ETD per uno specifico ordine, né abilitata l'opzione "Generate Invoice with DHL format": verrà restituito un errore poiché si sta richiedendo l'invio di una fattura paperless, ma nessuna fattura è associata a quell'ordine
sia l'opzione "Generate Invoice with DHL format" che l'opzione Paperless sono abilitate: in questo modo, si chiede a DHL di generare una fattura e di inviarla in formato digitale senza doverla allegare fisicamente al pacco (Paperless Trade)
è stato sia caricato il documento ETD sia attivata l'opzione "Generate Invoice with DHL format": verrà restituito un errore perché si sta chiedendo di trasmettere 2 fatture diverse per un unico ordine
Non è stata attivata l'opzione "Paperless Trade", ma ha comunque proceduto al caricamento del documento tramite la chiamata "UploadPaperlessDocumentation" o tramite Invoice Manager: la documentazione verrà comunque trasmessa al corriere in modalità Paperless.
🗓 Extend label validity
Questo servizio viene solitamente usato per le label di ritorno, e aggiungerà l'estensione RET sulla label creata da MyDHL.
Selezionando l'opzione Extend label validity, potrai estendere la durata di un LDV senza conoscere la data effettiva di affidamento al Corriere.
🚚 Add freight charges to commercial invoice
Se selezioni questa opzione, le spese di spedizione verranno aggiunte alla fattura commerciale creata.
🧪 Test Mode
Abilita la modalità Test se desideri effettuare spedizioni di prova. Tieni presente che questa opzione deve essere contrassegnata solo se disponi delle credenziali di test, non delle credenziali di produzione!
⚠️ Merce Pericolosa
Per ogni spedizione contenente merce pericolosa dovrai inserire il contentId della merce pericolosa spedita.
Se la spedizione contiene ghiaccio secco UN1845 dovrai inserire il peso del ghiaccio secco trasportato.
Se la merce è in quantità esentata secondo la IATA, dovrai inoltre inserire il codice UNCode della merce pericolosa, disponibile qui.
✍🏻 Etichette personalizzate
Puoi anche creare un'Etichetta Personalizzata per riconoscere immediatamente la connessione tra tutte le altre.
📆 Default amount of additional weekdays required to prepare the shipments
Questo dato serve a DHL per sapere la data pianificata di spedizione, ma non equivale alla richiesta di ritiro (che puoi effettuare così). Il numero predefinito di giorni necessari per la preparazione è 1 giorno, ma è possibile modificarlo a piacere selezionando il numero di giorni dalla modale. Il sistema salta automaticamente i giorni festivi e i fine settimana nel conteggio dei giorni richiesti.
📌Assicurati di eseguire questa operazione su tutte le connessioni myDHL, anche se utilizzate un solo servizio.
📌 Se scegli "same day" chiedi a DHL qual è l'orario entro cui puoi creare le spedizioni, altrimenti potresti riscontrare un errore.
4. Attivazione del Servizio Service Point
Se desideri utilizzare il Service Point di myDHL, dovrai contattare il tuo referente di verificare l’abilitazione al servizio ODD (necessario per utilizzare questa funzionalità).
Una volta attivato il servizio ODD, sarà necessario inviare al reparto tecnico del corriere un screenshot dell'Opzione Corriere dove viene scelto il Service Point, e richiedere l’abilitazione al servizio sul username desiderato.
Sulla label non compare mai il Service Point che invece viene trasmesso elettronicamente al corriere incaricato della consegna.
5. Risoluzione errori & troubleshooting
Potresti riscontrare alcuni errori durante la connessione di MyDHL o nella fase di utilizzo. Niente panico: continua a leggere per scoprire come risolverli facilmente! 🧑🔧
Requested product not available for pickup date:
Se il giorno successivo è un giorno festivo, potreste ricevere questo errore, poiché il sistema sceglie di default il giorno successivo per il ritiro. Assicuratevi di modificare il valore "Select the default amount of additional weekdays required to prepare the shipments" in 2 o più giorni da Corrieri > Connessione > myDHL > Modifica per tutte le vostre connessioni myDHL (non solo quella che state utilizzando per la spedizione specifica).7008: The requested Special Service Code: #/valueAddedServices /0/serviceCode ‘WY’ is not available between this origin and destination. Please validate the products and services combination (via the /rates or/products service) or contact our customer service.
Questo errore appare quando:
Hai selezionato l'opzione Paperless per una spedizione non tassabile (come per esempio una spedizione nazionale o all'interno dell'EU). Rimuovi la spunta dalla sezione Corrieri:
L'opzione Paperless non è disponibile per quella destinazione extra EU.
In questo caso è necessario:rimuovere l'opzione Paperless
rimuovere eventuali ETD caricati nella sezione Gestione Fatture
flaggare l'opzione Generate Invoice with DHL format nella connessione del vettore nella sezione Corrieri solo se vuoi stampare la fattura. Oppure invia direttamente la tua fattura a DHL.
7008: The requested Special Service Code #/valueAddedServices/0/serviceCode ‘SA' is not available between this origin and destination. Please validate the products and services combination (via the /rates or /products service) or contact our customer service.
Questo errore indica che l’Opzione Corriere del “Delivery Signature” non è supportata verso quella specifica località di destinazione. Verifica direttamente con DHL verso quali destinazioni è possibile utilizzare questo servizio aggiuntivo.
** NB: questo servizio potrebbe essere attivo o non attivo per singole località di una stessa nazione.
** NB: ricorda che il servizio “Delivery Signature” (codice servizio: SA) è un servizio diverso dal “Direct Signature” (codice servizio: SF).
7120: Required either #/outputImageProperties/imageOptions where typeCode=invoice or provide #/documentImages
Il messaggio di errore indica che è necessario selezionare il flag "Stampa fattura commerciale" nella modale del corriere (da Carriers > Connections > Edit) OPPURE caricare il file ETD.
''100002: Null Validator: SHIPMENT_ID not found in request map., 100002: Null Validator: SHIPMENT_ID_CHECK_DIGIT not found in request map.''
Questo messaggio di errore si riferisce ad un problema interno DHL che non permette l’assegnazione del numero AWB e JJD. Solitamente si tratta di un malfunzionamento temporaneo.Se il disagio dovesse persistere, contattare il proprio referente DHL.
Error Da rielaborare: #/customerReferences/0: required key [value] not found, #/outputImageProperties/customerBarcodes/0: required key [content] not found
Assicurati di aver aggiunto correttamente l'ID dell'ordine, essendo questa un'informazione obbligatoria per il Corriere.
Da rielaborare: 1001: The requested product(s) (P) not available based on your search criteria (Il/i prodotto/i richiesto/i (P) non sono disponibili in base ai criteri impostati nella ricerca). (409224511)
La città di destinazione indicata non è valida. Per esempio "cityName":"NA". Puoi verificare CAP e località accettate dal sistema myDHL al link: https://dct.dhl.com/
MyDHL error: 1001: The requested product(s) (W) not available based on your search criteria (Da rielaborare: 1001: Il/i prodotto/i richiesto/i (W) non è disponibile in base ai criteri di ricerca.)
Il servizio indicato non può essere utilizzato per la spedizione in questione. Scegli un altro servizio e prova a spedire l'ordine di nuovo.
410138: Requested product(s) not available at payer, H/- (Il/i prodotto/i richiesto/i non sono disponibili per l'utente pagante, H):
Il Product Code (cioè il servizio DHL) è sbagliato. Contatta il tuo referente DHL per sapere qual è il servizio corretto collegato al tuo codice cliente.
Invalid Credentials // Credenziali non valide:
Controlla sempre se hai inserito le credenziali corrette e assicurati di non aver erroneamente aggiunto uno spazio in più nel nome utente. Puoi controllare le impostazioni da Corrieri > Connessione e, una volta selezionato il Corriere, fare clic su Modifica.
Il valore è più corto della lunghezza minima:
Il numero di partita IVA del mittente o il numero IOSS del destinatario non sono presenti nel tuo profilo.
MyDHL - error 8009: Shipper Billing Country must either be same as Billing Country of Shipment Origin or the Shipper Account must be an Impex Account // MyDHL - errore 8009: il Paese di fatturazione del mittente deve essere uguale al Paese di origine della spedizione di fatturazione o l'account del mittente deve essere un account Impex
Nel caso in cui stiate effettuando spedizioni di ritorno con MyDHL, il problema potrebbe essere legato al fatto che non avete impostato un numero di Return Account nella connessione MyDHL.Per maggiori informazioni su come configurare correttamente il vostro account per le spedizioni di reso, consultate la sezione 🔁 Stampa di etichette di reso di questa guida.
MyDHL - Unedfined Error. Status code: 400
Questo accade soprattutto quando le credenziali API non sono state attivate da DHL: se riscontrate questo errore, ricontrolla nel tuo profilo sul portale sviluppatori di DHL se le credenziali API sono state attivate per la produzione, oppure chiedete assistenza al vostro rappresentante DHL.7121: #/content/exportDeclaration is mandatory when provided product is dutiable, please update and try again.
Selezionare Paperless Trade nella configurazione del corriere sotto Corrieri > Connessione. Ricordarsi inoltre di includere tutte le informazioni relative al CN22 per un corretto passaggio del pacco alla dogana.Da rielaborare: #/content: required key [description] not found
Selezionare "numero ordine Shippypro" nelle preferenze del profilo come descrizione del contenuto stampato sulle etichette.
Verifica che non siano presenti spazi vuoti nella chiamata effettuata.
Unable to send this shipment with the selected rate. Please try again or use a different rate.
Non è possibile correggere l'ordine, è necessario riportare l'ordine in Da Spedire per riprocessarla, oppure ripetere la Ship call.
Se effettua le spedizioni tramite API e ha selezionato ALL SERVICES nel modulo di connessione, è necessario ottenere il CarrierService e il RateID tramite la chiamata GetRates, e poi includere queste informazioni nella chiamata Ship API.
Invece, selezionando un servizio specifico nel modulo di connessione, non è necessario includere RateID nella richiesta di spedizione.
Le mie tariffe DHL non vengono visualizzate nella schermata di checkout di Shopify, perché?
Non preoccuparti, la soluzione può essere molto semplice! Assicurati che il tuo indirizzo di ritorno non sia più lungo di 45 caratteri. Se necessario, puoi dividerlo tra i due campi dedicati all'indirizzo. Se il problema persiste, puoi contattare il nostro team di assistenza per ricevere ulteriore assistenza.
Error 420505: The destination location is invalid. Please check
La destinazione indicata potrebbe non essere servita da DHL, puoi verificare i codici postali e le località accettate da MyDHL a questo link: https://dct.dhl.com/