La Shipping Options Provider API Express Checkout permet aux marchands de proposer des options d’expédition dynamiques pendant le flux Express Checkout. Dès qu’un client modifie son adresse de livraison ou qu’un recalcul est nécessaire, wallee appelle la Shipping Options Provider API du marchand pour récupérer les modes d’expédition disponibles.
|
Important
|
Cette API est exclusivement destinée au flux Express Checkout. Elle ne doit pas être utilisée pour un processus de commande classique. |
Avant d’implémenter la Shipping Options Provider API, configurez l’URL de rappel dans les paramètres du space.
Le marchand doit exposer un endpoint REST que wallee peut appeler avec les données de la session.
Méthode : POST
URL : l’URL renseignée dans les paramètres du space
Content-Type : application/json
La requête suit la structure IExpressCheckoutShippingOptionRequest et expose les champs plats suivants :
| Champ | Type | Obligatoire ? | Description |
|---|---|---|---|
|
Long |
Oui |
Identifiant de la session Express Checkout. |
|
String |
Oui |
Identifiant du space marchand (multi-tenant). |
|
String |
Oui |
ID de corrélation pour tracer les requêtes. |
|
String |
Oui |
Code pays ISO-3166 (par ex. |
|
String |
Oui |
Devise de la transaction (ISO-4217). |
|
String |
Oui |
Code langue pour la localisation (ISO-639). |
|
String |
Non |
État / province. |
|
String |
Non |
Rue et numéro. |
|
String |
Non |
Ville. |
|
String |
Non |
Code postal. |
{
"expressCheckoutId": 123456,
"spaceId": "84",
"requestId": "21a2f7fe-51b7-4ed5-9f88-1fb128292986",
"countryCode": "CH",
"currency": "CHF",
"language": "fr",
"state": "ZH",
"street": "Rue Exemple 5",
"city": "Winterthour",
"postalCode": "8400"
}Points importants :
expressCheckoutId, spaceId, requestId, countryCode, currency et language sont toujours transmis.
Aucune autre donnée de commande n’est transmise ; les informations complémentaires doivent être récupérées côté boutique si nécessaire.
Le service doit retourner un objet JSON unifié contenant soit une liste d’options d’expédition, soit une erreur.
{
"shippingOptions": [
{
"id": "standard",
"label": "Livraison standard",
"description": "Livraison en 3 à 5 jours ouvrables",
"amount": 9.99,
"taxAmount": 0.00,
"currency": "CHF"
},
{
"id": "express",
"label": "Livraison express",
"description": "Livraison en 1 à 2 jours ouvrables",
"amount": 19.99,
"taxAmount": 0.00,
"currency": "CHF"
}
],
"error": null
}shippingOptions: Une liste des options d’expédition disponibles. Peut être vide si aucune option n’est disponible.
error: Un objet d’erreur si quelque chose s’est mal passé. null en cas de succès.
L’objet shippingOptions a les champs suivants :
id: identifiant unique de l’option d’expédition (obligatoire)
label: intitulé affiché (obligatoire)
description: description optionnelle
amount: montant hors taxe (BigDecimal, obligatoire)
taxAmount: montant de TVA (BigDecimal, obligatoire)
currency: code devise ISO-4217 appliqué à cette option (obligatoire)
L’objet error a les champs suivants :
error: Une courte chaîne de caractères identifiant le type d’erreur (par exemple, "INVALID_ADDRESS").
message: Un message lisible par l’homme expliquant l’erreur.
timestamp: L’horodatage de l’erreur.
La Shipping Options Provider API doit toujours retourner un code de statut HTTP 200 OK. Les erreurs doivent être communiquées dans le champ error du corps de la réponse.
{
"shippingOptions": [],
"error": {
"error": "INVALID_ADDRESS",
"message": "L’adresse de livraison fournie ne permet pas de calculer les frais d’expédition.",
"timestamp": "2023-10-10T12:00:00Z"
}
}Retournez une liste shippingOptions vide si aucune option n’est disponible :
{
"shippingOptions": [],
"error": null
}Vérifiez la présence des champs nécessaires.
Assurez-vous que l’adresse est desservie par votre service logistique.
Fournissez des messages d’erreur explicites.
Tenez compte :
de la localisation du client,
du poids/volume (dérivés des articles),
de la valeur de la commande,
du niveau de service (standard, express, etc.).
Intégrez taxes et règles spécifiques (seuils de gratuité, suppléments…)
Répondez en moins de 30 secondes pour éviter les timeouts.
Mettez en cache les calculs si possible.
Utilisez des algorithmes efficaces.
Adresse valide avec plusieurs options
Adresse valide avec une seule option
Adresse invalide (champ manquant)
Pays ou région non desservi(e)
Commande sans article
Colis lourd/volumineux nécessitant un traitement particulier
Seuil de livraison gratuite atteint
curl -X POST https://votre-boutique.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"
}'{
"shippingOptions": [
{
"id": "standard",
"label": "Livraison standard",
"description": "Livraison en 3 à 5 jours ouvrables",
"amount": 9.99,
"taxAmount": 0.00,
"currency": "CHF"
},
{
"id": "express",
"label": "Livraison express",
"description": "Livraison en 1 à 2 jours ouvrables",
"amount": 19.99,
"taxAmount": 0.00,
"currency": "CHF"
}
],
"error": null
}Retournez toujours un code de statut HTTP 200 OK.
Fournissez des messages d’erreur clairs dans le champ error de la réponse.
Journalisez les erreurs.
Prévoyez des mécanismes de secours quand le service est indisponible.