nShift Checkout basiert auf einer neuen API. Die Migration von DeliveryCheckout erfordert die Implementierung dieser neuen API. Dieser Artikel bietet einen Überblick über die wichtigsten Unterschiede zwischen den beiden APIs, um Sie bei der Planung und Eingrenzung Ihrer Integrationsarbeit zu unterstützen.
Auf einen Blick
| Bereich | DeliveryCheckout (v1) | nShift Checkout (v2) |
|---|---|---|
| Kunde meldet sich an bei | nShift Delivery | nShift Portal |
| API-Basis-URL | https://api.unifaun.com/rs-extapi/v1 | https://api.nshiftportal.com/checkout |
| Authentifizierungsmodell | API-Schlüssel / Bearer-Token | OAuth 2.0-Token (Client ID + Secret) |
| API-Dokumentation | nShift API Connect | developers.nshiftone.com |
Authentifizierung
nShift Checkout verwendet ein modernes OAuth 2.0-Authentifizierungsmodell. Anstelle eines API-Schlüssels verwenden Sie eine Client ID und ein Client Secret, die in Ihrem nShift Portal-Konto erstellt wurden, um ein Zugriffstoken zu generieren.
- Token-Endpoint: https://account.nshiftportal.com/idp/connect/token
- Tokens sind 1 Stunde gültig.
- Empfohlen: Implementieren Sie exponentielles Backoff, sodass bei einem fehlgeschlagenen Token-Request Wiederholungen mit schrittweise längeren Intervallen erfolgen.
Übersicht der Endpoints
Die folgende Tabelle fasst die wichtigsten Änderungen bei den Endpoints sowie die Gründe dafür zusammen.
| Aktion | DeliveryCheckout (v1) | nShift Checkout (v2) | Grund für die Änderung |
|---|---|---|---|
| Authentifizieren | N/A | POST /idp/connect/token |
Sicherere und standardisierte OAuth 2.0-Authentifizierung. |
| Session erstellen | N/A | POST /v1/sessions/{checkoutConnectionId} |
Sessions verknüpfen Verbraucherinteraktionen und ermöglichen Conversion-Tracking sowie A/B-Tests (Experiments). |
| Versandoptionen abrufen | GET /delivery-checkouts |
POST /v1/shipping-options/{sessionId} |
Ein strukturierter POST-Body ermöglicht umfangreichere Eingaben, besseren Datenschutz und zukünftige Erweiterungen ohne Breaking Changes. |
| Teilversand erstellen | POST /delivery-checkouts |
POST /shipments/v1/shipments |
Einheitlicher Endpoint zur Erstellung von Sendungen, der von verschiedenen nShift APIs gemeinsam genutzt wird; klare Trennung der Verantwortlichkeiten. |
Wichtige Änderungen im Detail
Sessions
nShift Checkout führt das Konzept einer Session ein. Eine Session verknüpft die Interaktionen des Verbrauchers während der gesamten Checkout-Reise und ermöglicht konsistente Erlebnisse sowie präzises Conversion-Tracking. Sessions bilden außerdem die Grundlage für Experiments (A/B-Tests).
- Sessions werden erstellt mit:
POST /v1/sessions/{checkoutConnectionId} - Eine Session ist 4 Stunden gültig und wird bei jeder Interaktion aktualisiert.
- Das Senden eines Bodys ist erforderlich (kann leer sein); Body-Werte werden verwendet, wenn auf eine Group oder ein Experiment mit Segmentation verwiesen wird.
Abrufen von Versandoptionen
Der Aufruf zum Abrufen von Versandoptionen wurde von einer GET-Anfrage mit Query-Parametern zu einer strukturierten POST-Anfrage mit JSON-Body geändert. Dies verbessert den Datenschutz, ermöglicht umfangreichere Eingaben und erleichtert Debugging und Wartung.
Beispiel: Delivery Checkout v1
GET https://api.unifaun.com/delivery-checkouts/123456 ?currency=SEK&language=sv&tocountry=SE&tozipcode=41756&weight=2.3&cartprice=499
Beispiel: nShift Checkout v2
POST /v1/shipping-options/{sessionId}
{
"currencyCode": "SEK",
"languageCode": "sv",
"totalWeightKg": 2.3,
"receiver": {
"postalCode": "41756",
"country": "SE"
},
"packages": [{ "weightKg": 2.3, "volumeCm3": null }],
"variables": { "cartPrice": 499 }
}
Response: wichtige Änderungen bei Feldnamen
Die bekannten Bausteine sind weiterhin in der Response vorhanden, zum Beispiel Options-IDs, Carrier-Service-IDs, Abholpunkte und Add-ons, jedoch wurden einige Parameter umbenannt oder neu strukturiert.
Einige Beispiele unten:
| Konzept | Delivery Checkout (v1) | nShift Checkout (v2) |
|---|---|---|
| Optionskennung | id |
optionId |
| Preis |
priceValue / priceDescription
|
price / priceDescription
|
| Abholpunkte | agents[] |
pickupPoints[] |
Erstellen einer Teilsendung
Sobald eine Bestellung konvertiert wurde, müssen Sie eine Teilsendung mit POST /shipments/v1/shipments erstellen. Dieser Schritt ist verpflichtend und stellt die vollständige Kompatibilität mit allen aktuellen und zukünftigen Funktionen von nShift Checkout sicher, einschließlich der genauen Berechnung von Conversion-Raten für Experiments.
Hinweis:
Wenn Sie die Teilsendung nicht verwenden möchten, um die eigentliche Sendung in Ihrer Versandlösung zu erstellen, können Sie den Query-Parameter send-to-book-and-print=false zur URL /shipments hinzufügen. Dadurch wird der Aufruf für das Conversion-Tracking registriert, ohne eine Teilsendung in der Versandlösung zu erstellen.
Fügen Sie in diesem Fall außerdem extended-result=true hinzu, um eine erweiterte Response von Checkout zu erhalten.
Buchen und Drucken aus der Versandlösung
Die Erstellung der finalen Sendung (Buchung und Labeldruck) aus der Teilsendung erfolgt weiterhin innerhalb Ihrer nShift Versandlösung, und dieser Teil der Integration bleibt unverändert.
- Delivery: Prepared shipments
- Ship: Completing a partial shipment from nShift Checkout
- Transsmart: Create, update and book prepared shipments
Vollständige API-Dokumentation
Verfügbar unter: https://developers.nshiftone.com/checkout/getting-started