Julkinen toimitustarkistuksen API-sopimus
Tätä rajapintaa käyttävät ulkoiset järjestelmät (kuten mukautetut taustajärjestelmät, verkkokaupan kassat tai ERP-järjestelmät) tarkistamaan, voidaanko annettuun postinumeroon toimittaa määritettyjen toimitusalueidesi ja sääntöjesi perusteella.
[!WARNING]
Sallittu käyttö — vain reaaliaikaiseen tarkistukseen.
API-vastauksia ei saa tallentaa, välimuistiin tallentaa, kerätä massana, viedä, myydä edelleen tai käyttää minkään postinumero-, osoite-, etäisyys-, toimitusalue-, maantieteellisen tai vastaavan tietoaineiston luomiseen, rikastamiseen, uudelleenmuodostamiseen tai korvaamiseen. Automaattinen kaapiminen, järjestelmällinen läpikäynti tai API:n massakyselyt ovat kiellettyjä. Täydet käyttöehdot: API:n käyttöehdot ja Hyväksyttävän käytön käytäntö.
[!NOTE]
Suomen postinumeroaineistoa hallinnoidaan keskitetysti GN-Projects / Delivery Zonen toimesta.
Asiakkaat eivät lataa palveluun tai vie palvelusta raakaa postinumerodataa.
API palauttaa toimituspäätökset tämän keskitetyn aineiston ja omien toimitusvyöhykesääntöjesi perusteella.
>
Postinumeron oikeellisuus tarkistetaan virallisia suomalaisia postinumeroviitetietoja vasten.
Sädeperusteisilla (etäisyyteen perustuvilla) vyöhykkeillä API käyttää postinumeron edustavaa sijaintia ja laskee suoran etäisyyden määritetystä toimipisteestäsi — katso lisätietoja ja tunnetut rajoitukset sivulta Postinumerodatan vastuunrajoitus.
Päätepiste
POST /api/v1/delivery/check
Otsakkeet
X-Api-Key: Julkinen API-avaimesi.Content-Type:application/json
Pyynnön runko
{
"destinationPostcode": "00100",
"basketValueCents": 4500
}Onnistuneet vastaukset (200 OK)
Statuskoodi 200 OK palautetaan kaikille onnistuneesti suoritetuille tarkistuksille riippumatta siitä, onko toimitus mahdollinen.
Toimitettavissa
{
"canDeliver": true,
"matchedZoneName": "Helsinki Center",
"priceCents": 590,
"currency": "EUR",
"estimatedDeliveryMinutes": 45,
"reasonCode": "DELIVERABLE",
"reasonMessage": "Delivery is available."
}Ei toimitettavissa
{
"canDeliver": false,
"reasonCode": "NOT_DELIVERABLE",
"reasonMessage": "Delivery is not available for this postcode."
}Ei toimitettavissa — Vähimmäistilaus ei täyty
{
"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]
Kaikki tilanteet, joissa toimitus ei ole mahdollinen postinumeron kattavuuden tai vyöhykemääritysten vuoksi, palauttavat yleisen
NOT_DELIVERABLE-syykoodin. Tämä on tarkoituksellista.
Sisäisiä vyöhyketunnisteita, tarkkoja raakaetäisyyksiä tai tietoaineiston jäsenyysviestejä ei koskaan paljasteta julkisessa API-vastauksessa.
Virhevastaukset
400 Bad Request
Pyyntö oli virheellinen, postinumeron muoto oli virheellinen tai ostoskorin arvo oli virheellinen tai puuttui, kun sovellettu sääntö vaati sitä.
{
"canDeliver": false,
"reasonCode": "INVALID_POSTCODE",
"reasonMessage": "The postcode must be exactly 5 digits."
}Muut 400-syykoodit: INVALID_BASKET_VALUE (negatiivinen ostoskorin arvo) ja BASKET_VALUE_REQUIRED (vastaavalla vyöhykkeellä on vähimmäistilaus- tai ilmaistoimitussääntö, eikä ostoskorin arvoa annettu — canDeliver on tässä tapauksessa null, ja vastaus sisältää kentät minimumOrderCents/freeDeliveryFromCents).
401 Unauthorized
{
"error": "A valid API key is required."
}403 Forbidden
API-avain on kelvollinen, mutta sillä ei ole oikeutta käyttää tätä päätepistettä (laajuus, organisaatio tai tilauksen tila).
{
"canDeliver": false,
"reasonCode": "API_ACCESS_DENIED",
"reasonMessage": "The API key is not permitted to access this endpoint."
}405 Method Not Allowed
Palautetaan mille tahansa muulle HTTP-metodille kuin POST tässä päätepisteessä.
413 Payload Too Large
{
"canDeliver": false,
"reasonCode": "PAYLOAD_TOO_LARGE",
"reasonMessage": "Request body exceeds the maximum allowed size."
}429 Too Many Requests
Kattaa kolme erillistä rajoitusta, jotka erotellaan reasonCode-koodilla. Kaikki kolme tulisi käsitellä eksponentiaalisella peruutuksella ja noudattamalla Retry-After-otsaketta.
Minuuttikohtainen kutsuraja — väliaikainen; ei vaadi tilauksen muutosta:
{
"canDeliver": false,
"reasonCode": "RATE_LIMITED",
"reasonMessage": "Too many requests. Please try again later."
}Vuorokausiraja (per API-avain) — nollautuu seuraavana UTC-keskiyönä; erillinen kuukausikiintiöstä eikä kuluta sitä:
{
"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"
}Kuukausittainen tilauskiintiö — nollautuu seuraavan laskutuskauden alussa. Älä yritä uudelleen automaattisesti ennen kiintiön nollaantumista tai tilauksen päivittämistä:
{
"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
Järjestelmä ei voi tällä hetkellä käsitellä pyyntöjä (esimerkiksi ei aktiivista keskitettyä aineistoa).
{
"canDeliver": false,
"reasonCode": "NO_ACTIVE_DATASET",
"reasonMessage": "Service temporarily unavailable."
}Autentikointi
Kaikki pyynnöt vaativat X-Api-Key-otsakkeen. Saat avaimesi luomalla ilmaisen tilin. Avaimet ovat organisaatiokohtaisia ja ne voidaan vaihtaa hallintapaneelista. Erillistä testi-/tuotantoympäristöä ei ole — käytä ei-tuotannollista toimitusvyöhykettä testataksesi turvallisesti oikealla API-avaimellasi.
Kutsurajat
API-avaimissa on oletuksena rajoitus 120 pyyntöä minuutissa ja 10 000 pyyntöä vuorokaudessa. Kuukausittaiset kiintiöt riippuvat tilauksestasi — katso tarkat rajat Hinnoittelu-sivulta; Ilmainen paketti sisältää 10 tarkistusta kuukaudessa. Kuukausikiintiön, vuorokausirajan tai minuuttirajan ylittyminen palauttaa HTTP-tilakoodin 429 Too Many Requests, joka eritellään koodilla reasonCode (PLAN_LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED tai RATE_LIMITED). Odota ja yritä uudelleen Retry-After-otsakkeen mukaisesti; paketti- ja vuorokausirajoissa odota kentän resetAt osoittamaa nollausta tai päivitä tilauksesi.