Configurare i moduli corriere in PrestaShop: guida passo dopo passo

Ultima revisione giugno 2026, il funzionamento dei moduli corriere descritto qui sotto (oggetto Carrier creato in install(), tariffe esterne tramite getOrderShippingCostExternal, interfaccia per punti di ritiro automatici tramite displayCarrierExtraContent) resta valido da PrestaShop 1.7 fino a 8 e 9; su PS9 la visualizzazione multi-corriere è controllata da un flag di funzionalità, indicato alla fine.

In PrestaShop esistono due cose completamente diverse che vengono entrambe chiamate "configurare un corriere", e confonderle è il punto in cui la maggior parte dei commercianti si blocca. La prima è creare un corriere a mano nel back office, un nome, alcune zone, una griglia prezzi, cioè l’impianto di base che PrestaShop include da sempre. La seconda è installare un modulo corriere: un software che registra uno o più corrieri al posto tuo, comunica con l’API di un corriere reale, stampa etichette, recupera tariffe in tempo reale e inserisce mappe dei punti di ritiro nella procedura d’acquisto. Questa guida riguarda la seconda opzione, che cos’è davvero un modulo corriere, come si collega a PrestaShop, come installarlo e configurarlo senza compromettere la procedura d’acquisto e come distinguere un buon modulo da un rischio operativo. Per creare corrieri manualmente partendo da zone e intervalli, il lavoro è diverso e lo trattiamo nella guida completa alla configurazione delle spedizioni.

Che cos’è davvero un modulo corriere (e perché è diverso da un corriere del back office)

Quando vai in Spedizione → Corrieri e fai clic su "Aggiungi nuovo corriere", crei una riga nella tabella ps_carrier che PrestaShop valuta rispetto al carrello durante la procedura d’acquisto. È statica: il prezzo arriva da una griglia che hai inserito tu, e il corriere non sa nulla del vettore reale oltre a un nome e a un modello di URL di tracciamento. Va benissimo per una "Spedizione standard €5,99" ed è lo strumento giusto per molti negozi.

Un modulo corriere è un’altra cosa. Durante l’installazione crea programmaticamente i propri corrieri: istanzia la classe Carrier nel metodo install(), imposta id_reference, intervalli, zone e gruppi nel codice e salva l’ID del corriere risultante nella propria configurazione, così può gestirlo negli aggiornamenti. Da quel momento il modulo possiede quel corriere. Lo scheletro di questa creazione è questo, nota i tre campi che trasformano un corriere normale in un corriere di modulo:

// Inside the module's install() – create a carrier the module owns.
$carrier = new Carrier();
$carrier->name = 'Pickup Point Delivery';
$carrier->active = true;
$carrier->shipping_handling = false;
$carrier->range_behavior = 0;
$carrier->delay = ['en' => '1-2 business days']; // shown verbatim at checkout
$carrier->shipping_external = true;                // PS asks the module for the price
$carrier->need_range = true;                       // false = pure external rating
$carrier->external_module_name = $this->name;      // links the carrier back to this module
$carrier->is_module = true;
if ($carrier->add()) {
    // Remember the ID so the module can manage/repair this carrier later.
    Configuration::updateValue('MYCARRIER_ID', (int) $carrier->id);
    // Then assign zones/groups and (optionally) a fallback range grid.
}

Poiché external_module_name collega il corriere al modulo, PrestaShop sa che deve chiamare questo modulo per il prezzo e l’interfaccia extra nella procedura d’acquisto di quel corriere: è questo che rende possibili i due comportamenti successivi. Quindi, cosa ottieni in pratica? Comportamenti che la griglia statica non può offrire:

• Tariffe in tempo reale. Invece di un prezzo stimato, il modulo chiama l’API del corriere durante la procedura d’acquisto e restituisce il preventivo reale per peso, dimensioni e destinazione di quel carrello, implementando getOrderShippingCostExternal() su un corriere marcato come corriere di modulo con need_range disattivato, così PrestaShop chiede il prezzo al modulo invece di leggere una griglia di intervalli statica.
• Punti di ritiro. I corrieri con punti relay e armadietti automatici inseriscono una mappa o un menu a tendina nella fase di consegna (tramite l’hook displayCarrierExtraContent, il sostituto in 1.7+ del deprecato displayCarrierList) così il cliente sceglie un punto di ritiro specifico e il modulo salva questa scelta nell’ordine. L’hook viene eseguito solo per il corriere il cui external_module_name punta al modulo.
• Etichette e manifesti. Un pulsante nel back office (o un hook sullo stato dell’ordine) genera il PDF dell’etichetta di spedizione del corriere e scrive il numero di tracciamento direttamente nell’ordine, senza copiare e incollare dati nel portale del corriere.
• Configurazione autoriparante. Poiché il corriere viene creato nel codice, il modulo può ricrearlo o aggiornarlo dopo un upgrade di PrestaShop invece di costringerti a ricostruire a mano una griglia prezzi.

Il punto pratico è questo: se il tuo corriere offre un modulo ufficiale per PrestaShop, quasi sempre conviene usarlo al posto di un corriere creato a mano: la versione manuale non può stampare etichette né calcolare un prezzo reale. Se il tuo corriere non lo offre, il corriere manuale è il piano B, e la guida alla configurazione citata sopra è il punto da cui partire.

Prima di installare qualunque cosa: tre controlli che evitano procedure d’acquisto bloccate

I moduli corriere toccano la pagina più delicata del tuo negozio, quindi l’ordine delle operazioni conta. La paura principale dei commercianti è un modulo che blocchi la procedura d’acquisto: guadagna quella fiducia verificando prima tre aspetti.

• Compatibilità con la tua versione esatta. Il panorama delle API corriere è cambiato tra PrestaShop 1.6 → 1.7 → 8 → 9; un modulo scritto per 1.6 potrebbe registrare il corriere in un modo che 8.x ignora. Verifica che il modulo indichi la tua versione prima di acquistarlo, non dopo.
• Una copia di prova. Non installare mai per la prima volta un modulo corriere direttamente in produzione. Clona il negozio, installalo lì ed esegui un ordine di test reale per ogni zona. Un corriere che non si registra correttamente si presenta nella procedura d’acquisto con il temuto messaggio "nessun corriere disponibile", e non vuoi scoprirlo con clienti reali.
• Un backup del database. Poiché questi moduli scrivono in ps_carrier, ps_carrier_zone e nelle tabelle degli intervalli durante l’installazione, un punto di ripristino pulito trasforma un’installazione sbagliata in un rollback da cinque minuti invece che in un pomeriggio perso.

La sequenza di installazione e configurazione che funziona davvero

La maggior parte dei moduli corriere ufficiali segue la stessa logica. Conoscere la sequenza ti permette di configurarne uno qualsiasi, DHL, GLS, Colissimo, InPost, senza dover reimparare il flusso ogni volta.

• 1. Installa il modulo. Moduli → Gestione moduli → Carica un modulo, trascina lo ZIP e installa. In questo momento il modulo crea i propri corrieri: vai in Spedizione → Corrieri e li vedrai comparire automaticamente.

• 2. Inserisci le credenziali del tuo account. Apri la configurazione del modulo e incolla la chiave API, il client ID o il numero di contratto che ti ha fornito il corriere. È questo che separa un corriere con tariffe in tempo reale funzionanti da uno inutilizzabile. Molti moduli hanno un pulsante "test connessione": usalo; una spunta verde qui ti risparmia un errore nella procedura d’acquisto più avanti.
• 3. Mappa zone e servizi. Il modulo ha creato un corriere, ma sei ancora tu a decidere dove spedisce e quali servizi del corriere (standard, express, punti di ritiro automatici) rendere disponibili. Assegna il corriere alle tue zone nella sua voce sotto Spedizione → Corrieri, oppure dentro il modulo se gestisce autonomamente le zone.
• 4. Imposta il prezzo di riserva. I moduli con tariffe in tempo reale hanno bisogno di un valore alternativo quando l’API del corriere va in timeout, altrimenti un intoppo dell’API diventa un ordine perso. Imposta una tariffa fissa sensata a cui il modulo possa ricorrere, così la procedura d’acquisto non mostra mai zero corrieri.
• 5. Configura gestione ed etichette. Indirizzo del mittente, peso predefinito del pacco, formato dell’etichetta (A4 o termica) e stato dell’ordine che attiva la generazione dell’etichetta.
• 6. Esegui un ordine di test reale fino al pagamento per ogni zona, verifica che il corriere compaia, che la tariffa sia corretta e, se supportato, che venga generata un’etichetta.

Corriere manuale o modulo corriere: quale usare

Scegliere moduli per corrieri reali: le integrazioni disponibili

Una volta deciso che ti serve un modulo, la domanda diventa quale scegliere, e la risposta dipende dal corriere: ogni integrazione ha le proprie particolarità (numeri di contratto, API dei punti di ritiro automatici, formati etichetta). Invece di comprimerle in un elenco frettoloso, ecco la mappa delle guide corriere per corriere:

• I tre grandi internazionali. DHL, DPD e UPS coprono la maggior parte delle spedizioni UE transfrontaliere; configurazione, campi del contratto e flusso delle etichette sono spiegati nella guida all’integrazione di DHL, DPD e UPS.
• GLS in più Paesi. Se spedisci in diversi mercati con un unico contratto GLS, la configurazione multi-paese ha le sue insidie: vedi l’integrazione GLS per spedizioni multi-paese.
• Francia: Colissimo e Mondial Relay. Colissimo è la scelta nazionale predefinita per i negozi francesi (guida alla configurazione di Colissimo); Mondial Relay aggiunge la rete di punti relay che gli acquirenti francesi si aspettano (consegna ai punti relay Mondial Relay).
• Polonia: InPost Paczkomaty. Se vendi in Polonia e non offri la consegna nei punti di ritiro automatici, parti con un vero svantaggio: l’integrazione della mappa dei punti di ritiro è descritta in InPost Paczkomaty per PrestaShop.

Il problema "nessun corriere disponibile": cosa lo causa con i moduli

L’errore più comune dopo l’installazione di un modulo corriere è una procedura d’acquisto che mostra nessuna opzione di spedizione. Con un corriere creato a mano quasi sempre manca l’assegnazione della zona; con un modulo ci sono alcuni sospetti in più, perché il modulo aggiunge un livello:

• Il corriere del modulo non è assegnato alla zona del cliente. Il modulo ha creato il corriere, ma non hai mai collegato i Paesi di destinazione. Correggi in Spedizione → Corrieri → Luoghi e costi di spedizione del corriere.
• Nessun intervallo di prezzo copre questo carrello. Alcuni moduli dipendono ancora da una riga di intervallo peso/prezzo per la disponibilità o come valore di riserva, quindi se l’API non restituisce nulla e nessun intervallo copre il carrello, il corriere può sparire. Un vero corriere a tariffa esterna con need_range disattivato non dipende affatto da una riga di intervallo statica, ma se il modulo ha lasciato attivo un requisito di intervallo, è un sospetto concreto.
• Le credenziali API sono errate o l’API del corriere non risponde. Senza un prezzo di riserva, una chiamata API fallita rimuove silenziosamente il corriere. È esattamente per questo che il punto 4 sopra è importante.
• Restrizione per gruppo o negozio. Il modulo potrebbe assegnare di default il corriere a un solo gruppo clienti o a un solo negozio in una configurazione multinegozio. Controlla Accesso gruppi e Associazione negozio sul corriere.
• Il prodotto non ha peso. I corrieri basati sul peso e quelli con tariffe in tempo reale si appoggiano entrambi a pesi prodotto reali nel catalogo; a seconda del modulo e della configurazione degli intervalli, un peso mancante o pari a 0 kg può rompere il calcolo basato sul peso o via API, oppure finire fuori da ogni intervallo configurato, quindi il corriere calcola male il prezzo o scompare.

Per capire più a fondo come zone, intervalli e corrieri si incastrano, il modello a cui risalgono tutti questi errori, la guida completa alla configurazione delle spedizioni è il riferimento.

I moduli corriere sono metà del lavoro: conta anche la parte visibile al cliente

Un modulo corriere installato perfettamente calcola il prezzo giusto e stampa l’etichetta, ma l’esperienza del cliente intorno alla spedizione è una decisione separata che non dovresti saltare:

• Quale data di consegna vedono? Il campo integrato di PrestaShop per il tempo di transito mostra lo stesso "3–7 giorni lavorativi" a ogni destinazione, indipendentemente dalla zona o dal tuo tempo di preparazione. Mostrare invece una data reale è un tema a parte: vedi come impostare aspettative di consegna realistiche e perché una data concreta riduce l’ansia del cliente. Il nostro modulo Estimated Delivery Date colma questa lacuna: calcola una data di arrivo effettiva per corriere e zona, tenendo conto del tuo tempo di preparazione e dei giorni lavorativi, così un cliente tedesco vede "Consegna: mercoledì" mentre un cliente spagnolo vede "Consegna: venerdì", senza modificare un file del tema.
• Vengono avvisati quando l’ordine parte? Il numero di tracciamento che il modulo ha scritto nell’ordine è utile solo se arriva al cliente: ne parliamo in numeri di tracciamento e notifiche di consegna.
• Quanto fai pagare oltre alla tariffa del corriere? Che tu trasferisca direttamente le tariffe in tempo reale, le trasformi in tariffe fisse o le assorba nella spedizione gratuita, è una decisione di margine: parti da gratuita vs fissa vs calcolata e, se hai un negozio più piccolo, da strategia di spedizione per piccoli negozi.

La versione breve

"Configurare un modulo corriere" non è la stessa cosa che aggiungere un corriere nel back office: un modulo installa software che possiede il proprio corriere, comunica con il corriere reale e fa cose che una griglia prezzi statica non potrebbe mai fare: tariffe in tempo reale, mappe dei punti di ritiro, etichette con un clic. Installa in un ambiente di prova con un backup, inserisci le credenziali del contratto e testa la connessione, imposta sempre un prezzo di riserva così un problema temporaneo dell’API non può svuotare la procedura d’acquisto, ed esegui un ordine di test reale per ogni zona prima di andare online. Poi scegli l’integrazione corriere giusta per i tuoi mercati e assicurati che la parte visibile al cliente, date di consegna, tracciamento, costi applicati, sia curata quanto l’impianto tecnico che la sostiene. Fai bene questi passaggi e la fase del corriere smette di essere una causa di carrelli abbandonati e diventa un motivo in meno per andarsene.

Domande frequenti

Qual è la differenza tra un modulo corriere e l’aggiunta di un corriere nel back office?

Un corriere del back office è una riga statica in ps_carrier con una griglia prezzi che hai inserito tu: non sa nulla del corriere reale oltre a un nome e a un modello di URL di tracciamento. Un modulo corriere installa software che crea e possiede il proprio corriere nel codice, poi chiama l’API del corriere per le tariffe in tempo reale, inserisce una mappa dei punti di ritiro nella procedura d’acquisto e genera etichette con il numero di tracciamento scritto direttamente nell’ordine. Se il tuo corriere offre un modulo ufficiale, quasi sempre è quello che vuoi; se non lo offre, il corriere creato a mano è l’alternativa di riserva.

Perché la procedura d’acquisto mostra "nessun corriere disponibile" dopo l’installazione di un modulo corriere?

Quasi sempre per uno di cinque motivi: il corriere del modulo non è assegnato alla zona del cliente; nessun intervallo di prezzo copre il carrello (alcuni moduli hanno ancora bisogno di una riga di intervallo di riserva); le credenziali API sono errate o l’API del corriere non risponde e non è impostato alcun prezzo di riserva; una restrizione di gruppo o multinegozio nasconde il corriere; oppure il prodotto non ha peso, quindi un corriere basato sul peso o con tariffe in tempo reale non riesce a calcolarne il prezzo. Verificali in quest’ordine: assegnazione della zona e prezzo di riserva mancante coprono la maggior parte dei casi.

Che cosa controlla davvero need_range su un corriere?

Decide se PrestaShop deve leggere una griglia statica di intervalli peso/prezzo per calcolare il costo del corriere, oppure chiedere al modulo. Con need_range = false su un corriere marcato shipping_external e is_module, PrestaShop chiama il metodo getOrderShippingCostExternal() del modulo per ottenere un preventivo reale e non dipende affatto da una riga di intervallo. Con need_range = true, un intervallo che non copre il carrello può far sparire il corriere: è uno dei sospetti dietro il messaggio "nessun corriere disponibile" citato sopra.

Devo davvero fare prima un test in un ambiente di prova?

Sì: durante l’installazione i moduli corriere scrivono in ps_carrier, ps_carrier_zone e nelle tabelle degli intervalli, e toccano la pagina più fragile del tuo negozio. Un modulo che registra male il proprio corriere si manifesta come "nessun corriere disponibile" nella procedura d’acquisto, e non vuoi scoprirlo con clienti reali. Clona il negozio, fai un backup del database, installa lì ed esegui un ordine di test reale per ogni zona prima di toccare la produzione. Un backup pulito trasforma un’installazione sbagliata in un rollback da cinque minuti.

PrestaShop 9 cambia il funzionamento di più corrieri?

Può farlo, dietro un flag. Storicamente PrestaShop ha applicato la logica un ordine = un corriere. PrestaShop 9.1 introduce un modello Shipments che consente a un ordine di avere più spedizioni con corrieri diversi, disponibile tramite flag di funzionalità: abilita "Improved shipment" in Parametri avanzati → Funzionalità nuove & sperimentali per provarlo. È sperimentale, quindi testalo in un ambiente di prova prima di farci affidamento; con il flag disattivato resta valido il comportamento classico con un solo corriere per ordine descritto nel resto di questa guida.