Vai al contenuto

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.

Il checkout con i metodi restituiti dal ponte: Economy, Standard, Express, Overnight e Freight accanto al Flat Rate

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

  1. Costruisci l’endpoint che accetta il payload e risponde con methods, anche solo con una tariffa fissa, per verificare il giro completo.
  2. Attiva Debug Mode mentre integri: var/log/shipping_bridge.log mostra richiesta e risposta e toglie di mezzo tutte le ipotesi.
  3. Aggiungi gli attributi prodotto che servono al calcolo, ricordando che più dati si mandano, più lento diventa il servizio.
  4. 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.
  5. 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