Tariffe di spedizione da una API: un ponte invece di un modulo per corriere
Dalla 26.3 ShippingBridge manda carrello e indirizzo a un endpoint JSON e mostra al checkout i metodi che tornano indietro, senza modulo.
Ogni corriere vuole il suo modulo, ogni modulo vuole il suo aggiornamento, e ogni negozio che cambia contratto si trova a installare l’ennesimo pacchetto per calcolare un prezzo. ShippingBridge prende una strada diversa: il calcolo lo fa una API, e Maho si limita a mandarle il carrello con l’indirizzo e a mostrare al checkout i metodi che tornano indietro. Dalla 26.3 il ponte è nel core, quindi non c’è codice da scrivere.
Come funziona
Il flusso è corto. Il cliente apre il checkout, Maho raccoglie le tariffe dai corrieri attivi, e tra questi
c’è il ponte: manda una richiesta POST con Content-Type: application/json all’endpoint configurato,
aspetta la risposta, e i metodi che riceve finiscono nell’elenco accanto agli altri.

Sul lato opposto puoi mettere quello che vuoi: un microservizio, una funzione serverless, il gestionale di magazzino, un aggregatore che interroga tre corrieri in parallelo. Il contratto è sempre lo stesso, quindi cambiare fornitore non significa cambiare negozio.
La configurazione
System > Configuration > Sales > Shipping Methods > Shipping Bridge. I campi che contano:
| Impostazione | Cosa fa | Scope |
|---|---|---|
| Enabled | attiva il corriere | Website |
| Title | nome del gruppo mostrato al checkout | Store View |
| API Endpoint URL | l’indirizzo a cui Maho manda la richiesta | Website |
| Authentication Type | nessuna, token Bearer o header personalizzato | Website |
| Auth Token | il valore del token, cifrato nel database | Website |
| Custom Header Name | nome dell’header quando usi l’autenticazione personalizzata | Website |
| Request Timeout | secondi di attesa, massimo 60 | Website |
| Additional Product Attributes | attributi prodotto da aggiungere al payload | Website |
| Debug Mode | scrive richiesta e risposta in var/log/shipping_bridge.log |
Website |
| Displayed Error Message | messaggio mostrato al cliente quando il metodo non è disponibile | Store View |
Il timeout ha un tetto di sessanta secondi, ed è una scelta sana: un checkout che aspetta un minuto una tariffa è un checkout perso. Se la API è lenta, il problema va risolto dall’altra parte.
Cosa riceve la API
Il payload contiene il carrello con le righe e i totali, l’indirizzo di spedizione, la valuta, lo store e i
dati del cliente. Ogni riga porta sku, name, qty, weight, price e row_total, più gli attributi
aggiuntivi che hai scelto in configurazione.
Per gli attributi a scelta singola o multipla arrivano valore e etichetta, così la funzione che calcola la tariffa non deve tradurre codici:
{
"cart": {
"items": [
{
"sku": "shirt-red-m",
"qty": 2,
"weight": 0.5,
"color": { "value": "25", "label": "Rosso" }
}
],
"totals": { "subtotal": 59.98, "weight": 1.0, "qty": 2 }
},
"shipping_address": { "postcode": "97201", "country_id": "US", "region_code": "OR" },
"currency": "EUR",
"store_id": 1,
"customer": { "group_id": 1, "group_code": "General", "is_guest": false }
}
Per i configurabili il payload porta il nome e il prezzo del prodotto padre, lo SKU della variante scelta, e gli attributi di configurazione sempre risolti dal figlio.
Cosa deve rispondere
Una risposta JSON con un array methods. Ogni metodo richiede code, title e price, e può portare
cost, description e logo.
{
"methods": [
{ "code": "standard", "title": "Standard (5-7 giorni)", "price": 5.99, "cost": 3.5 },
{ "code": "express", "title": "Express (1-2 giorni)", "price": 14.99, "cost": 10.0 }
]
}
Le regole in caso di problemi sono già scritte e vale la pena conoscerle prima di integrare: uno status
diverso da 2xx, un JSON non valido o un array methods mancante producono un errore nel log e nessun
metodo mostrato; un singolo metodo senza i campi obbligatori viene saltato con un avviso, mentre gli altri
restano visibili. Se non ci sono opzioni, si restituisce un array vuoto.
🌉 Nota dal ponte: la differenza fra un errore che ferma tutto e un metodo che sparisce è una scelta di progetto. Meglio un metodo in meno che un checkout che non si apre.
Quando conviene davvero
Il ponte conviene in tre casi. Il primo è la logica che nessun modulo standard sa esprimere: tariffe per zona, scaglioni di peso, sconti per gruppo cliente, regole su categorie di prodotto. Il secondo è l’integrazione con un ERP o un magazzino, dove la tariffa dipende da dove si trova davvero la merce. Il terzo è l’aggregazione: un solo endpoint che interroga più corrieri e restituisce una lista unica.
Non conviene quando basta un corriere con le sue tariffe a tabella, perché in quel caso il ponte aggiunge un servizio da mantenere per un calcolo che il core fa già.
🌉 Nota dal ponte: un ponte in più è un servizio in più da monitorare. Se la funzione serverless si sveglia fredda al primo checkout del mattino, il cliente aspetta, e la colpa sembra del negozio.
L’ordine di lavoro
- Costruisci l’endpoint che accetta il payload e risponde con
methods, anche solo con una tariffa fissa, per verificare il giro completo. - Attiva Debug Mode mentre integri:
var/log/shipping_bridge.logmostra richiesta e risposta e toglie di mezzo tutte le ipotesi. - Aggiungi gli attributi prodotto che servono al calcolo, ricordando che più dati si mandano, più lento diventa il servizio.
- Prova il caso senza opzioni, quello con la API che fallisce e quello con un metodo incompleto: sono i tre modi in cui il checkout si rompe in produzione.
- Spegni il debug prima di andare online: consuma spazio e scrive nei log dati del cliente.
Testo preparato con l'aiuto dell'AI e verificato sulla fonte prima della pubblicazione. Può contenere errori: se ne trovi uno, segnalalo.Leggi il Manifesto
Il tuo negozio vende ancora?
Raccontaci da dove parti: ti rispondiamo con una prima valutazione, senza impegno.
Chiedi l'analisi del negozio