Documentation

1Intégration de la Shipping Options Provider API Express Checkout

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.

1.1Configuration de l’URL de rappel de la Shipping Options Provider API

Avant d’implémenter la Shipping Options Provider API, configurez l’URL de rappel dans les paramètres du space.

1.1.1Définir l’URL

Accédez à Settings > General > Space et renseignez l’URL de votre Shipping Options Provider API.

Cette URL pointe vers l’endpoint REST qui fournira les options d’expédition.

1.2Endpoint de rappel Shipping Options Provider API

Le marchand doit exposer un endpoint REST que wallee peut appeler avec les données de la session.

1.2.1Spécification de l’endpoint

  • Méthode : POST

  • URL : l’URL renseignée dans les paramètres du space

  • Content-Type : application/json

1.2.2Format de la requête

La requête suit la structure IExpressCheckoutShippingOptionRequest et expose les champs plats suivants :

Champ Type Obligatoire ? Description

expressCheckoutId

Long

Oui

Identifiant de la session Express Checkout.

spaceId

String

Oui

Identifiant du space marchand (multi-tenant).

requestId

String

Oui

ID de corrélation pour tracer les requêtes.

countryCode

String

Oui

Code pays ISO-3166 (par ex. FR ou CH).

currency

String

Oui

Devise de la transaction (ISO-4217).

language

String

Oui

Code langue pour la localisation (ISO-639).

state

String

Non

État / province.

street

String

Non

Rue et numéro.

city

String

Non

Ville.

postalCode

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.

1.2.3Format de la réponse

Le service doit retourner un objet JSON unifié contenant soit une liste d’options d’expédition, soit une erreur.

1.2.3.1Réponse réussie

{
  "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
}

1.2.3.2Réponse d’erreur

{
  "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"
  }
}

1.2.4Description des champs

  • 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.

1.3Gestion des erreurs

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.

1.3.1Adresse invalide

{
  "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"
  }
}

1.3.2Aucune option disponible

Retournez une liste shippingOptions vide si aucune option n’est disponible :

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

1.3.3Service indisponible

{
  "shippingOptions": [],
  "error": {
    "error": "SERVICE_UNAVAILABLE",
    "message": "Le service de calcul des frais d’expédition est momentanément indisponible.",
    "timestamp": "2023-10-10T12:00:00Z"
  }
}

1.4Recommandations d’implémentation

1.4.1Validation des adresses

  • 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.

1.4.2Calcul des frais

  • 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…)

1.4.3Performance

  • Répondez en moins de 30 secondes pour éviter les timeouts.

  • Mettez en cache les calculs si possible.

  • Utilisez des algorithmes efficaces.

1.4.4Sécurité

  • Filtrez les requêtes (IP wallee, authentification si nécessaire).

  • Journalisez les appels pour l’audit.

1.5Tests

1.5.1Cas à couvrir

  • 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

1.5.2Exemple de requête

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"
  }'

1.5.3Exemple de réussite

{
  "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
}

1.5.4Exemple d’échec

{
  "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"
  }
}

1.6Bonnes pratiques en cas d’erreur

  • 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.

1.7Support

Pour toute question relative à la Shipping Options Provider API, consultez la documentation marchande wallee ou contactez le support.

Staging 2.189.0