Offentligt API-kontrakt för leveranskontroll
Detta API används av externa system (anpassade backend-system, kassor eller affärssystem) för att kontrollera om ett postnummer kan levereras till baserat på dina konfigurerade leveranszoner och regler.
[!WARNING]
Tillåten användning — endast realtidsvalidering.
API-svar får inte sparas, cachas, samlas in i bulk, exporteras, vidareförsäljas eller användas för att skapa, berika, rekonstruera eller ersätta data gällande postnummer, adresser, avstånd, leveranszoner, geografi eller liknande. Automatiserad skrapning, systematisk numrering eller massfrågor mot API:et är förbjudet. Fullständiga villkor: API-användarvillkor och Policy för acceptabel användning.
[!NOTE]
Finlands postnummerdata hanteras centralt av GN-Projects / Delivery Zone.
Kunder laddar inte upp, exporterar eller laddar ner rå postnummerdata.
API:et returnerar leveransbeslut baserat på denna centrala datamängd och dina specifika zonregler.
>
Postnumrets giltighet kontrolleras mot auktoritativ finländsk referensdata för postnummer.
För radiezoner (avståndsbaserade zoner) använder API:et en representativ plats för postnumret och beräknar fågelvägsavstånd från din konfigurerade basplats — se Ansvarsfriskrivning för postnummerdata för detaljer och kända begränsningar.
Ändpunkt
POST /api/v1/delivery/check
Headers
X-Api-Key: Din offentliga API-nyckel.Content-Type:application/json
Anropskropp
{
"destinationPostcode": "00100",
"basketValueCents": 4500
}Lyckade svar (200 OK)
Statuskod 200 OK returneras för varje giltig kontroll som slutförs, oavsett om leverans är möjlig eller inte.
Kan levereras
{
"canDeliver": true,
"matchedZoneName": "Helsinki Center",
"priceCents": 590,
"currency": "EUR",
"estimatedDeliveryMinutes": 45,
"reasonCode": "DELIVERABLE",
"reasonMessage": "Delivery is available."
}Kan ej levereras
{
"canDeliver": false,
"reasonCode": "NOT_DELIVERABLE",
"reasonMessage": "Delivery is not available for this postcode."
}Kan ej levereras — Minsta ordervärde ej uppnått
{
"canDeliver": false,
"reasonCode": "MINIMUM_ORDER_NOT_MET",
"reasonMessage": "The location is covered, but the minimum order value was not met.",
"requiredBasketValueCents": 5000,
"providedBasketValueCents": 3200,
"shortfallCents": 1800
}[!NOTE]
Alla utfall där leverans inte är möjlig på grund av postnummertäckning eller zonkonfiguration returnerar den generella orsakskoden
NOT_DELIVERABLE. Detta är avsiktligt.
Interna zonidentifierare, exakta avstånd och information om postnummerdatamängden inkluderas aldrig i det publika API-svaret.
Felsvar
400 Bad Request
Anropet var felaktigt formulerat, postnummerformatet var ogiltigt eller varukorgsvärdet var ogiltigt eller saknades när en matchad regel krävde det.
{
"canDeliver": false,
"reasonCode": "INVALID_POSTCODE",
"reasonMessage": "The postcode must be exactly 5 digits."
}Andra 400-orsakskoder: INVALID_BASKET_VALUE (negativt varukorgsvärde) och BASKET_VALUE_REQUIRED (den matchade zonen har en regel för minsta ordervärde eller fri frakt och inget varukorgsvärde angavs — canDeliver är null i detta fall, och svaret inkluderar minimumOrderCents/freeDeliveryFromCents).
401 Unauthorized
{
"error": "A valid API key is required."
}403 Forbidden
API-nyckeln är giltig men har inte behörighet till denna ändpunkt (omfattning, organisation eller prenumerationsstatus).
{
"canDeliver": false,
"reasonCode": "API_ACCESS_DENIED",
"reasonMessage": "The API key is not permitted to access this endpoint."
}405 Method Not Allowed
Returneras för alla andra HTTP-metoder än POST på denna ändpunkt.
413 Payload Too Large
{
"canDeliver": false,
"reasonCode": "PAYLOAD_TOO_LARGE",
"reasonMessage": "Request body exceeds the maximum allowed size."
}429 Too Many Requests
Täcker tre olika gränser, åtskilda med reasonCode. Alla tre bör hanteras med exponentiell back-off och genom att respektera headern Retry-After.
Minutgräns för anrop — temporär; kräver inget planbyte:
{
"canDeliver": false,
"reasonCode": "RATE_LIMITED",
"reasonMessage": "Too many requests. Please try again later."
}Dygnsgräns (per API-nyckel) — återställs nästa UTC-midnatt; skiljer sig från månadskvoten och förbrukar den inte:
{
"canDeliver": false,
"reasonCode": "DAILY_LIMIT_EXCEEDED",
"reasonMessage": "This API key's daily request limit has been reached. Please wait for it to reset or use a different key.",
"limitScope": "daily",
"limit": 10000,
"currentUsage": 10000,
"resetAt": "2026-09-01T00:00:00.000Z"
}Månatlig plankvot — återställs i början av din nästa faktureringsperiod. Försök inte igen automatiskt förrän kvoten återställts eller planen uppgraderats:
{
"canDeliver": false,
"reasonCode": "PLAN_LIMIT_EXCEEDED",
"reasonMessage": "Your plan's monthly API quota has been exhausted. Please upgrade your plan or wait for your quota to reset.",
"limitScope": "monthly",
"limit": 10000,
"currentUsage": 10000,
"resetAt": "2026-09-15T00:00:00.000Z"
}503 Service Unavailable
Systemet kan för närvarande inte behandla förfrågningar (t.ex. ingen aktiv central datamängd).
{
"canDeliver": false,
"reasonCode": "NO_ACTIVE_DATASET",
"reasonMessage": "Service temporarily unavailable."
}Autentisering
Alla anrop kräver en X-Api-Key-header. Hämta din nyckel genom att skapa ett gratiskonto. Nycklar är knutna till organisationen och kan roteras från instrumentpanelen. Det finns ingen separat test-/produktionsmiljö — använd en icke-produktionszon för att testa tryggt med din riktiga API-nyckel.
Anropsgränser
API-nycklar är som standard begränsade till 120 anrop per minut och 10 000 anrop per dygn. Månatliga kvoter beror på din plan — se Priser för exakta gränser; Gratisplanen tillåter 10 kontroller per månad. Om månadskvoten, dygnsgränsen eller minutgränsen överskrids returneras HTTP 429 Too Many Requests, åtskilt med reasonCode (PLAN_LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED eller RATE_LIMITED). Vänta och gör ett nytt försök enligt headern Retry-After; för plan- och dygnsgränser väntar du på återställningen som anges i resetAt eller uppgraderar din plan.