nShift Checkout is gebouwd op een nieuwe API. Migreren van DeliveryCheckout vereist de implementatie van deze nieuwe API. Dit artikel geeft een overzicht van de hoofdlijnen van de belangrijkste verschillen tussen de twee API’s om je te helpen bij het plannen en afbakenen van je integratiewerk.
In één oogopslag
| Onderdeel | DeliveryCheckout (v1) | nShift Checkout (v2) |
|---|---|---|
| Klant logt in op | nShift Delivery | nShift Portal |
| API basis-URL | https://api.unifaun.com/rs-extapi/v1 | https://api.nshiftportal.com/checkout |
| Authenticatiemodel | API-sleutel / bearer token | OAuth 2.0-token (Client ID + Secret) |
| API-documentatie | nShift API Connect | developers.nshiftone.com |
Authenticatie
nShift Checkout gebruikt een modern OAuth 2.0-authenticatiemodel. In plaats van een API-sleutel gebruik je een Client ID en Client Secret die zijn aangemaakt in je nShift Portal-account om een toegangstoken te genereren.
- Token-endpoint: https://account.nshiftportal.com/idp/connect/token
- Tokens zijn 1 uur geldig.
- Aanbevolen: implementeer exponential backoff zodat, als een tokenaanvraag mislukt, er opnieuw wordt geprobeerd met geleidelijk langere intervallen.
Overzicht van endpoints
De onderstaande tabel geeft een samenvatting van de belangrijkste wijzigingen in endpoints en de reden daarvoor.
| Actie | DeliveryCheckout (v1) | nShift Checkout (v2) | Reden voor wijziging |
|---|---|---|---|
| Authenticeren | N/A | POST /idp/connect/token |
Veiligere, gestandaardiseerde OAuth 2.0-authenticatie. |
| Sessie aanmaken | N/A | POST /v1/sessions/{checkoutConnectionId} |
Sessies koppelen interacties van consumenten aan elkaar, wat conversietracking en A/B-testen (Experiments) mogelijk maakt. |
| Leveringsopties ophalen | GET /delivery-checkouts |
POST /v1/shipping-options/{sessionId} |
Een gestructureerde POST-body maakt rijkere input, betere privacy en toekomstige uitbreidingen zonder breaking changes mogelijk. |
| Gedeeltelijke zending aanmaken | POST /delivery-checkouts |
POST /shipments/v1/shipments |
Uniform endpoint voor het aanmaken van zendingen dat wordt gedeeld tussen nShift API’s; duidelijke scheiding van verantwoordelijkheden. |
Belangrijke wijzigingen in detail
Sessies
nShift Checkout introduceert het concept van een sessie. Een sessie koppelt de interacties van de consument tijdens het checkoutproces aan elkaar, wat consistente ervaringen en nauwkeurige conversietracking mogelijk maakt. Sessies vormen ook de basis voor Experiments (A/B-testen).
- Sessies worden aangemaakt met:
POST /v1/sessions/{checkoutConnectionId} - Een sessie is 4 uur geldig en wordt vernieuwd bij elke interactie.
- Het versturen van een body is verplicht (mag leeg zijn); bodywaarden worden gebruikt bij verwijzing naar een Group of Experiment met Segmentation.
Leveringsopties ophalen
De aanroep voor het ophalen van leveringsopties is gewijzigd van een GET-aanvraag met queryparameters naar een gestructureerde POST-aanvraag met een JSON-body. Dit verbetert de privacy, maakt rijkere input mogelijk en is eenvoudiger te debuggen en onderhouden.
Voorbeeld: Delivery Checkout v1
GET https://api.unifaun.com/delivery-checkouts/123456 ?currency=SEK&language=sv&tocountry=SE&tozipcode=41756&weight=2.3&cartprice=499
Voorbeeld: 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: belangrijke wijzigingen in veldnamen
De vertrouwde bouwstenen zijn nog steeds aanwezig in de response, bijvoorbeeld optie-ID’s, carrier service-ID’s, afhaalpunten en add-ons, maar sommige parameters zijn hernoemd of opnieuw gestructureerd.
Enkele voorbeelden hieronder:
| Concept | Delivery Checkout (v1) | nShift Checkout (v2) |
|---|---|---|
| Optie-identificatie | id |
optionId |
| Prijs |
priceValue / priceDescription
|
price / priceDescription
|
| Afhaalpunten | agents[] |
pickupPoints[] |
Een gedeeltelijke zending aanmaken
Zodra een bestelling is geconverteerd, moet je een gedeeltelijke zending aanmaken met POST /shipments/v1/shipments. Deze stap is verplicht en zorgt voor volledige compatibiliteit met alle huidige en toekomstige functies van nShift Checkout, inclusief nauwkeurige berekening van conversieratio’s voor Experiments.
Opmerking:
Als je de gedeeltelijke zending liever niet gebruikt om de daadwerkelijke zending in je verzendoplossing aan te maken, kun je de queryparameter send-to-book-and-print=false toevoegen aan de URL van /shipments. Hiermee wordt de aanroep geregistreerd voor conversietracking zonder een gedeeltelijke zending in de verzendoplossing aan te maken.
Voeg in dat geval ook extended-result=true toe om een uitgebreide response van Checkout te ontvangen.
Boeken en printen vanuit de verzendoplossing
Het aanmaken van de definitieve zending (boeken en label printen) vanuit de gedeeltelijke zending gebeurt nog steeds binnen je nShift-verzendoplossing, en dit deel van de integratie blijft ongewijzigd.
- Delivery: Prepared shipments
- Ship: Completing a partial shipment from nShift Checkout
- Transsmart: Create, update and book prepared shipments
Volledige API-documentatie
Beschikbaar op: https://developers.nshiftone.com/checkout/getting-started