DHL e GLS in Odoo: il modulo OCA, cosa copre e cosa ti mancherà

In Odoo 19 esiste il modulo OCA di DHL Parcel e non esiste il modulo OCA di GLS. delivery_dhl_parcel è pubblicato nel ramo 19.0 di OCA/l10n-spain, versione 19.0.1.0.2. delivery_gls_asm va dalla 12.0 alla 18.0 e non è stato migrato. Se il piano era passare a Odoo 19 e continuare a stampare etichette GLS dal prelievo, questo è il primo dato da guardare.

GLS o DHL: perché non è la stessa decisione

GLS Spagna è corriere espresso per pacchi: colli piccoli e rete di agenzie. L'integrazione si vince o si perde sull'etichetta e sullo stato, e la sua ragion d'essere è il volume: cento etichette al giorno che nessuno vuole digitare.

DHL in Odoo non è un marchio: sono due prodotti con API diverse. Il modulo OCA lo segnala nel suo readme/DESCRIPTION.md: «No es válido para otras integraciones de DHL como el Express, que usan otras APIs». E la documentazione di Odoo 19, nella sua tabella dei connettori, elenca DHL Express e chiude: «Other services from DHL are not supported».

La conseguenza: se il tuo contratto è DHL Express, il modulo OCA non ti serve e il connettore nativo non è incluso in Community: in addons/ del repository pubblico di odoo/odoo, in 17, 18 e 19, l'unico modulo di corriere è delivery_mondialrelay. Se è DHL Parcel Spagna, il modulo OCA è la strada. È una domanda per il tuo commerciale DHL prima che per il tuo integratore.

Quale modulo OCA esiste davvero, e in quale repository

La confusione comincia nel posto sbagliato: cerchi «OCA DHL Odoo» e finisci su OCA/delivery-carrier, il repository di logistica dell'OCA. Lì non c'è: non esiste un modulo DHL in nessun ramo dalla 12.0 alla 19.0, e di GLS resta solo una cartella fantasma nella 16.0 con un file dentro, static/description/index.html. Né manifest né codice.

I due moduli attivi sono in OCA/l10n-spain, ed è bene ridimensionare le aspettative: nel ramo 19.0 di OCA/delivery-carrier l'unico modulo che chiama l'API di un corriere è delivery_correos_express; il resto è infrastruttura. E nella 19.0 di OCA/l10n-spain ci sono tre corrieri: delivery_dhl_parcel, delivery_mrw e delivery_seur_atlas.

Cosa copre ogni modulo, letto nel suo codice

In DHL Parcel tutto parte da un metodo, _prepare_dhl_parcel_shipping: un dizionario piatto che si legge in due minuti.

• Etichetta in PDF, ZPL o EPL allegata al prelievo, con AWB e tracciamento.
• Contrassegno calcolato dal totale dell'ordine, con ripartizione delle spese in base al termine di resa.
• Assicurazione opzionale, resi, chiusura giornaliera tramite procedura guidata e consegna entro le 13:30.
• Tre limiti scritti nel modulo: non quota (il suo ROADMAP dice che le spedizioni «siempre se cotizan a 0»), nome e indirizzo vengono troncati a 40 caratteri, e il peso minimo che viaggia è 1 kg anche se il collo pesa 200 g.

L'equivalente in GLS è _prepare_gls_asm_shipping, più lungo perché l'API richiede mittente e destinatario completi a ogni chiamata:

• Servizio e fascia oraria per metodo di consegna, etichetta PDF ed etichetta di reso.
• Tracciamento con storico completo e prova di consegna allegata al prelievo.
• Ritiri come flusso a sé: dodici codici di servizio contrassegnati come ritiro, con pulsante e stati separati.
• Annullamento con salvaguardia: aggiorna lo stato e annulla solo se la spedizione è ancora in «registrado en el transportista»; altrimenti genera un errore e ti indirizza a gestirlo via e-mail con GLS.
• I suoi limiti: il riferimento non può superare i 15 caratteri (GLS tronca e si creano collisioni), anche qui nessuna quotazione, e il paese del mittente è fissato su Spagna nel codice, con il commento always 34=Spain.

Dogana ed esportazione: i campi che l'OCA lascia vuoti

Il vuoto ha una forma precisa: Odoo porta i campi e i moduli OCA non li usano. Non manca l'informazione: è che non viaggia. Ciò che Odoo 19 ha, in stock_delivery:

• product.template.hs_code, con etichetta «HS Code» e l'aiuto «Standardized code for international shipping and goods declaration». È la voce doganale.
• product.template.country_of_origin, con etichetta «Origin of Goods», relazione con res.country.
• Una classe DeliveryCommodity (docstring letterale: «Commodities information are needed for Commercial invoices with each provider») con prodotto, quantità, valore monetario e paese d'origine, più due metodi che la costruiscono. Se il prodotto non ha paese d'origine, si usa quello del magazzino di spedizione.

Cosa fanno i moduli OCA con tutto questo: niente. Cercare hs_code, customs, aduana, arancel, incoterm o country_of_origin nell'intero modulo GLS restituisce zero risultati. In quello di DHL Parcel compaiono, ed è qui che sta il bello, perché compaiono vuoti:

delivery_dhl_parcel · models/delivery_carrier.py · _prepare_dhl_parcel_shipping

Tre campi previsti dall'API e tutti e tre inviati vuoti: valore dichiarato, valuta e descrizione della merce. Il termine di resa viaggia, ma guarda da dove arriva (da self, del metodo di consegna, non dal prelievo) e nel codice ci sono solo due valori, CPT ed EXW: uno fisso per tutto quel corriere. In GLS l'equivalente è il campo declarado, che esce anch'esso vuoto. E nessuno dei quattro corrieri rimasti nella 19.0 di quei due repository (DHL Parcel, MRW, SEUR e Correos Express) menziona DeliveryCommodity, hs_code né country_of_origin: la tubazione che Odoo ha predisposto non è collegata.

Cosa ti manca il giorno in cui esporti:

• Voce doganale e paese d'origine, per riga. Esistono nel prodotto, non arrivano al corriere.
• Valore dichiarato e relativa valuta. Previsto nell'API di DHL Parcel. Viene inviato vuoto.
• Descrizione della merce. Campo previsto. Viene inviato vuoto.
• Documento commerciale. Una proforma generata dal prelievo e allegata alla spedizione. Non esiste in nessuno dei due.
• Termine di resa per spedizione. Esiste per corriere, e con due valori.

Non è una svista di questi due: è la regola. delivery_schenker invia "customsClearance": False con il commento «Customs Clearance not supported for now as it needs a full customs implementation», e il suo ROADMAP include lo sdoganamento tra ciò che non è supportato; quel modulo arriva alla 18.0 e non è nemmeno nella 19.0. Quando un modulo OCA fa davvero la dogana, non la risolve con un campo: aggiunge un modello proprio con voce doganale e paese d'origine per ogni riga di merce. Questa è la misura reale del lavoro.

Cosa succede quando manca uno di questi campi

Niente, ed è questo il problema. I campi sono opzionali nell'API: il corriere accetta la spedizione, restituisce il tracciamento e l'etichetta esce dalla stampante. In Odoo il prelievo risulta convalidato e in verde. Il guaio arriva dopo, nello sdoganamento a destinazione: il pacco si ferma e qualcuno della tua azienda digita a mano la voce doganale, la descrizione e il valore richiesti dal corriere. Silenzioso in Odoo e rumoroso nell'assistenza clienti.

Conviene essere precisi su quando si applica. Non da Barcellona a Monaco: l'UE è mercato interno e lì non c'è frontiera doganale. Si applica uscendo dal territorio (Regno Unito, Svizzera, Norvegia, Andorra, Turchia) e, senza lasciare la Spagna, alle Canarie, a Ceuta e a Melilla. La Ley 37/1992 sull'IVA lo dice nell'articolo 3: esclude Ceuta e Melilla «en cuanto territorios no comprendidos en la Unión Aduanera» e le Canarie «en cuanto territorios excluidos de la armonización de los impuestos sobre el volumen de negocios».

E non aspettarti nemmeno una soglia sotto la quale l'adempimento sparisce. Sul lato dell'importazione, quello che la norma spagnola dettaglia, il Real Decreto-ley 7/2021 (BOE-A-2021-6872) ha recepito il pacchetto IVA dell'e-commerce con effetto dal 1° luglio 2021: ha soppresso l'esenzione per le importazioni di beni di modesto valore «hasta los 22 euros de valor global de la mercancía», e spiega che fino a 150 euro di valore intrinseco «se aplica la franquicia aduanera por lo que no se exige una declaración completa ante la Aduana en el momento de la importación». Leggilo al contrario: sotto i 150 euro la dichiarazione è più breve, non è zero. E chi deve compilarla continua ad avere bisogno di descrizione, valore e voce doganale: proprio i campi che il modulo invia vuoti.

Quando basta l'OCA e quando serve qualcosa in più

Il modulo OCA è la risposta giusta se spedisci all'interno dell'UE senza attraversare frontiere doganali, se vuoi smettere di digitare indirizzi e non una tariffa esatta nell'ordine, e se sei su Odoo 18 o precedente: oppure su 19 con DHL Parcel.

Serve qualcosa in più se:

• Esporti con regolarità, o spedisci alle Canarie, a Ceuta o a Melilla. Il lavoro non è «installare il modulo»: è popolare hs_code e paese d'origine, estendere il payload e generare il documento commerciale.
• Sei su Odoo 19 con GLS: oggi il modulo non c'è, quindi o si migra delivery_gls_asm o si cambia strada.
• Il tuo contratto è DHL Express, oppure spedisci con GLS dall'estero della Spagna.

Una nota di metodo per chiudere: estendere un modulo OCA è la via economica quando il vuoto è un campo, e smette di esserlo quando il vuoto è un documento. Inserire la voce doganale e il paese d'origine nel payload significa ereditare _prepare_dhl_parcel_shipping e aggiungere venti righe. Generare una proforma che quadri con la contabilità è già un modulo, con template, test e manutenzione su tre versioni.

Domande frequenti

Continua da qui

Cosa facciamo su questo tema