Documentazione
Documentazione
Checkout espresso

1Integrazione Shipping Options Provider API Express Checkout

La Shipping Options Provider API Express Checkout consente ai merchant di offrire opzioni di spedizione dinamiche durante il flusso di Express Checkout. Quando il cliente modifica l’indirizzo di consegna o è necessario ricalcolare i costi di spedizione, wallee chiama la Shipping Options Provider API del merchant per recuperare le opzioni disponibili.

Important

Questa API è pensata esclusivamente per il flusso Express Checkout e non deve essere usata per il checkout tradizionale.

1.1Configurazione dell’URL di callback della Shipping Options Provider API

Prima di implementare la Shipping Options Provider API, configurare l’URL di callback nelle impostazioni dello space.

1.1.1Impostare l’URL

Apri Settings > General > Space e inserisci l’URL del tuo endpoint Shipping Options Provider API.

L’URL punterà all’endpoint REST che restituirà le opzioni di spedizione.

1.2Endpoint di callback Shipping Options Provider API

Il merchant deve esporre un endpoint REST che wallee può chiamare con i dati della sessione.

1.2.1Specifiche dell’endpoint

  • Metodo: POST

  • URL: l’URL configurato nello space

  • Content-Type: application/json

1.2.2Formato della richiesta

La richiesta utilizza il modello IExpressCheckoutShippingOptionRequest ed espone i seguenti campi piatti:

Campo Tipo Obbligatorio? Descrizione

expressCheckoutId

Long

Sì

ID della sessione Express Checkout.

spaceId

String

Sì

Identificativo dello space del merchant.

requestId

String

Sì

ID di correlazione per tracciare le richieste.

countryCode

String

Sì

Codice paese ISO-3166 (es. IT, CH).

currency

String

Sì

Codice valuta ISO-4217 della transazione.

language

String

Sì

Codice lingua per la localizzazione (ISO-639).

state

String

No

Stato / provincia.

street

String

No

Via e numero civico.

city

String

No

Città.

postalCode

String

No

CAP.

 
{
  "expressCheckoutId": 123456,
  "spaceId": "84",
  "requestId": "21a2f7fe-51b7-4ed5-9f88-1fb128292986",
  "countryCode": "CH",
  "currency": "CHF",
  "language": "it",
  "state": "ZH",
  "street": "Via Esempio 5",
  "city": "Winterthur",
  "postalCode": "8400"
}

Note principali:

  • expressCheckoutId, spaceId, requestId, countryCode, currency e language sono sempre presenti.

  • Nessun altro dato dell’ordine viene trasmesso; eventuali informazioni aggiuntive devono essere recuperate dal merchant.

1.2.3Formato della risposta

Restituire un oggetto JSON unificato che contenga un array di opzioni di spedizione oppure un errore.

1.2.3.1Risposta positiva 

{
  "shippingOptions": [
    {
      "id": "standard",
      "label": "Spedizione standard",
      "description": "Consegna in 3-5 giorni lavorativi",
      "amount": 9.99,
      "taxAmount": 0.00,
      "currency": "CHF"
    },
    {
      "id": "express",
      "label": "Spedizione express",
      "description": "Consegna in 1-2 giorni lavorativi",
      "amount": 19.99,
      "taxAmount": 0.00,
      "currency": "CHF"
    }
  ],
  "error": null
}

1.2.3.2Risposta di errore 

{
  "shippingOptions": [],
  "error": {
    "error": "INVALID_ADDRESS",
    "message": "L’indirizzo di spedizione fornito non è valido per il calcolo dei costi.",
    "timestamp": "2023-10-10T12:00:00Z"
  }
}

1.2.4Descrizione dei campi

  • shippingOptions: Un elenco delle opzioni di spedizione disponibili. Può essere vuoto se non sono disponibili opzioni.

  • error: Un oggetto di errore se qualcosa è andato storto. null in caso di successo.

L’oggetto shippingOptions ha i seguenti campi:

  • id: identificativo univoco dell’opzione (obbligatorio)

  • label: etichetta visualizzata (obbligatoria)

  • description: descrizione (facoltativa)

  • amount: costo di spedizione al netto delle imposte (BigDecimal, obbligatorio)

  • taxAmount: importo delle imposte (BigDecimal, obbligatorio)

  • currency: codice valuta ISO-4217 utilizzato per il costo di spedizione (obbligatorio)

L’oggetto error ha i seguenti campi:

  • error: Una breve stringa che identifica il tipo di errore (ad es. "INVALID_ADDRESS").

  • message: Un messaggio leggibile dall’uomo che spiega l’errore.

  • timestamp: Il timestamp di quando si è verificato l’errore.

1.3Gestione degli errori

La Shipping Options Provider API dovrebbe sempre restituire un codice di stato HTTP 200 OK. Gli errori devono essere comunicati nel campo error del corpo della risposta.

1.3.1Indirizzo non valido 

{
  "shippingOptions": [],
  "error": {
    "error": "INVALID_ADDRESS",
    "message": "L’indirizzo di spedizione fornito non è valido per il calcolo dei costi.",
    "timestamp": "2023-10-10T12:00:00Z"
  }
}

1.3.2Nessuna opzione disponibile

Restituire un array shippingOptions vuoto quando non ci sono opzioni:

{
  "shippingOptions": [],
  "error": null
}

1.3.3Servizio non disponibile 

{
  "shippingOptions": [],
  "error": {
    "error": "SERVICE_UNAVAILABLE",
    "message": "Il servizio di calcolo delle spedizioni è temporaneamente non disponibile.",
    "timestamp": "2023-10-10T12:00:00Z"
  }
}

1.4Linee guida per l’implementazione

1.4.1Validazione degli indirizzi

  • Verificare la presenza dei campi richiesti.

  • Assicurarsi che l’indirizzo sia in un’area servita.

  • Restituire messaggi d’errore chiari per indirizzi non supportati.

1.4.2Calcolo delle spedizioni

  • Considerare:

    • destinazione,

    • peso/volume (derivato dalle line items),

    • valore dell’ordine,

    • livello di servizio (standard, express…).

  • Applicare le imposte e le regole del merchant (soglie di spedizione gratuita, supplementi, ecc.).

1.4.3Performance

  • Rispondere entro 30 secondi per evitare timeout.

  • Usare cache quando opportuno.

  • Scegliere algoritmi efficienti.

1.4.4Sicurezza

  • Validare le richieste (indirizzi IP wallee, eventuale autenticazione).

  • Tracciare le chiamate per audit.

1.5Test

1.5.1Casi consigliati

  • Indirizzo valido con più opzioni

  • Indirizzo valido con una sola opzione

  • Indirizzo incompleto/errato

  • Paese o regione non supportata

  • Ordine privo di articoli

  • Spedizione speciale per pacchi pesanti

  • Raggiungimento della soglia di spedizione gratuita

1.5.2Esempio di richiesta 

curl -X POST https://il-tuo-shop.com/api/shipping-options \
  -H "Content-Type: application/json" \
  -d '{
    "shippingAddress": {
      "givenName": "John",
      "familyName": "Doe",
      "street": "Main St 123",
      "city": "Zurich",
      "postcode": "8000",
      "country": "CH"
    },
    "currency": "CHF"
  }'

1.5.3Esempio di risposta corretta 

{
  "shippingOptions": [
    {
      "id": "standard",
      "label": "Spedizione standard",
      "description": "Consegna in 3-5 giorni lavorativi",
      "amount": 9.99,
      "taxAmount": 0.00
    },
    {
      "id": "express",
      "label": "Spedizione express",
      "description": "Consegna in 1-2 giorni lavorativi",
      "amount": 19.99,
      "taxAmount": 0.00
    }
  ],
  "error": null
}

1.5.4Esempio di errore 

{
  "shippingOptions": [],
  "error": {
    "error": "INVALID_ADDRESS",
    "message": "L’indirizzo di spedizione fornito non è valido per il calcolo dei costi.",
    "timestamp": "2023-10-10T12:00:00Z"
  }
}

1.6Best practice per la gestione degli errori

  • Restituire sempre un codice di stato HTTP 200 OK.

  • Fornire messaggi d’errore chiari nel campo error della risposta.

  • Registrare gli errori per analisi successive.

  • Predisporre fallback quando il servizio non è disponibile.

1.7Supporto

Per ulteriori informazioni sull’implementazione della Shipping Options Provider API, consulta la documentazione merchant di wallee o contatta il supporto.