Dokumentation
Dokumentation
Express-Kasse

1Express Checkout Shipping Options Provider API-Integration

Die Express Checkout Shipping Options Provider API ermöglicht es Händlern, während des Express Checkout-Flows dynamische Versandoptionen bereitzustellen. Sobald Kund:innen ihre Lieferadresse ändern oder Versandkosten neu berechnet werden müssen, ruft wallee die Shipping Options Provider API des Händlers auf, um verfügbare Versandarten zu ermitteln.

Important

Diese API ist ausschließlich für den Express Checkout vorgesehen und darf nicht im regulären Checkout-Prozess verwendet werden.

1.1Shipping Options Provider API Callback-URL konfigurieren

Bevor die Shipping Options Provider API implementiert wird, muss die Callback-URL in den Space-Einstellungen hinterlegt werden.

1.1.1Callback-URL hinterlegen

Wechseln Sie zu Settings > General > Space, um die Shipping Options Provider API-URL zu konfigurieren.

Diese URL verifies auf den Shipping Options Provider API-Endpunkt, der Versandoptionen entgegennimmt.

1.2Shipping Options Provider API Callback-Endpunkt

Händler implementieren einen REST-Endpunkt, den wallee mit den Daten der Kund:innen aufruft.

1.2.1Endpoint-Spezifikation

  • Methode: POST

  • URL: Die in den Space-Einstellungen konfigurierte Callback-URL

  • Content-Type: application/json

1.2.2Request-Format

Die Anforderung entspricht dem IExpressCheckoutShippingOptionRequest und liefert die folgenden flachen Felder:

Feld Typ Pflicht? Beschreibung

expressCheckoutId

Long

Ja

ID der Express-Checkout-Session.

spaceId

String

Ja

Space-Identifier für mandantenfähige Händler.

requestId

String

Ja

Korrelations-ID zur Nachverfolgung mehrerer Anfragen.

countryCode

String

Ja

Ländercode gemäß ISO-3166 (z. B. CH).

currency

String

Ja

Währungscode der Transaktion (ISO-4217).

language

String

Ja

Sprachcode für die Lokalisierung (ISO-639).

state

String

Nein

Bundesland/Kanton bzw. Provinz.

street

String

Nein

Straße bzw. Hausanschrift.

city

String

Nein

Ort.

postalCode

String

Nein

Postleitzahl.

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

Wichtige Hinweise:

  • expressCheckoutId, spaceId, requestId, countryCode, currency und language werden immer übertragen.

  • Weitere Bestelldaten werden nicht übermittelt; zusätzliche Informationen müssen bei Bedarf durch den Shop ermittelt werden.

1.2.3Response-Format

Der Endpunkt muss ein vereinheitlichtes JSON-Objekt zurückgeben, das entweder eine Liste von Versandoptionen oder einen Fehler enthält.

1.2.3.1Erfolgsantwort 

{
  "shippingOptions": [
    {
      "id": "standard",
      "label": "Standardversand",
      "description": "Lieferung in 3-5 Werktagen",
      "amount": 9.99,
      "taxAmount": 0.00,
      "currency": "CHF"
    },
    {
      "id": "express",
      "label": "Expressversand",
      "description": "Lieferung in 1-2 Werktagen",
      "amount": 19.99,
      "taxAmount": 0.00,
      "currency": "CHF"
    }
  ],
  "error": null
}

1.2.3.2Fehlerantwort 

{
  "shippingOptions": [],
  "error": {
    "error": "INVALID_ADDRESS",
    "message": "Die angegebene Lieferadresse ist für die Versandberechnung ungültig.",
    "timestamp": "2023-10-10T12:00:00Z"
  }
}

1.2.4Feldbeschreibung

  • shippingOptions: Eine Liste der verfügbaren Versandoptionen. Kann leer sein, wenn keine Optionen verfügbar sind.

  • error: Ein Fehlerobjekt, falls etwas schiefgegangen ist. null bei Erfolg.

Das shippingOptions-Objekt hat die folgenden Felder:

  • id: Eindeutige Kennung der Versandoption (Pflichtfeld)

  • label: Anzeigename der Versandart (Pflichtfeld)

  • description: Optionale Beschreibung

  • amount: Versandkosten exkl. Steuern (Pflichtfeld, BigDecimal)

  • taxAmount: Steuerbetrag für den Versand (Pflichtfeld, BigDecimal)

  • currency: ISO-4217-Währungscode der Versandkosten (Pflichtfeld)

Das error-Objekt hat die folgenden Felder:

  • error: Eine kurze Zeichenfolge, die den Fehlertyp identifiziert (z.B. "INVALID_ADDRESS").

  • message: Eine für Menschen lesbare Nachricht, die den Fehler erklärt.

  • timestamp: Der Zeitstempel, wann der Fehler aufgetreten ist.

1.3Fehlerbehandlung

Die Shipping Options Provider API sollte immer einen HTTP 200 OK-Statuscode zurückgeben. Fehler sollten im error-Feld des Antwortkörpers übermittelt werden.

1.3.1Ungültige Adresse 

{
  "shippingOptions": [],
  "error": {
    "error": "INVALID_ADDRESS",
    "message": "Die angegebene Lieferadresse ist für die Versandberechnung ungültig.",
    "timestamp": "2023-10-10T12:00:00Z"
  }
}

1.3.2Keine Versandoptionen verfügbar

Wenn keine Versandarten für die Adresse verfügbar sind, senden Sie eine leere shippingOptions-Liste:

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

1.3.3Dienst derzeit nicht verfügbar 

{
  "shippingOptions": [],
  "error": {
    "error": "SERVICE_UNAVAILABLE",
    "message": "Der Versandkostenservice ist vorübergehend nicht verfügbar.",
    "timestamp": "2023-10-10T12:00:00Z"
  }
}

1.4Implementierungshinweise

1.4.1Adressvalidierung

  • Prüfen Sie, ob alle für die Berechnung benötigten Felder vorhanden sind.

  • Stellen Sie sicher, dass die Adresse in Ihrem Liefergebiet liegt.

  • Geben Sie aussagekräftige Fehlermeldungen für ungültige oder nicht unterstützte Adressen zurück.

1.4.2Versandberechnung

  • Berücksichtigen Sie:

    • Lieferort

    • Gewicht/Volumen (aus den Line Items)

    • Warenwert

    • Liefergeschwindigkeit / Service-Level

  • Kalkulieren Sie Steuern und individuelle Regeln (Freigrenzen, Zuschläge etc.).

1.4.3Performance

  • Antworten Sie innerhalb von 30 Sekunden, um Timeouts zu vermeiden.

  • Nutzen Sie Caching, wenn möglich.

  • Implementieren Sie effiziente Algorithmen zur Versandkostenberechnung.

1.4.4Sicherheit

  • Validieren Sie eingehende Anfragen (z. B. IP-Whitelist, Authentifizierung).

  • Protokollieren Sie Aufrufe zur Nachverfolgung.

1.5Tests

1.5.1Empfohlene Testfälle

  • Gültige Adresse mit mehreren Versandoptionen

  • Gültige Adresse mit nur einer Option

  • Ungültige Adresse (fehlende Pflichtfelder)

  • Nicht unterstützte Länder/Regionen

  • Bestellung ohne Positionen

  • Schweres/großes Paket mit Spezialversand

  • Kostenfreie Lieferung (Schwellenwert erreicht)

1.5.2Beispielanfrage 

curl -X POST https://ihr-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.3Beispiel-Erfolg 

{
  "shippingOptions": [
    {
      "id": "standard",
      "label": "Standardversand",
      "description": "Lieferung in 3-5 Werktagen",
      "amount": 9.99,
      "taxAmount": 0.00,
      "currency": "CHF"
    },
    {
      "id": "express",
      "label": "Expressversand",
      "description": "Lieferung in 1-2 Werktagen",
      "amount": 19.99,
      "taxAmount": 0.00,
      "currency": "CHF"
    }
  ],
  "error": null
}

1.5.4Beispiel-Fehler 

{
  "shippingOptions": [],
  "error": {
    "error": "INVALID_ADDRESS",
    "message": "Die angegebene Lieferadresse ist für die Versandberechnung ungültig.",
    "timestamp": "2023-10-10T12:00:00Z"
  }
}

1.6Fehlermanagement – Best Practices

  • Geben Sie immer einen HTTP 200 OK-Statuscode zurück.

  • Stellen Sie aussagekräftige Fehlermeldungen im error-Feld der Antwort bereit.

  • Protokollieren Sie Fehler zur Fehleranalyse.

  • Implementieren Sie Fallbacks für Ausfälle.

1.7Support

Bei Fragen zur Implementierung der Shipping Options Provider API steht die wallee Merchant-Dokumentation oder der Support zur Verfügung.