Integraatio-ohje

Räätälöity kassa-integraatio

Delivery Zone API toimii minkä tahansa taustajärjestelmäkielen tai -kehyksen kanssa. Lähetä palvelimeltasi POST-pyyntö osoitteeseen /api/v1/delivery/check asiakkaan postinumerolla ja ostoskorin arvolla. Vastaus kertoo, voitko toimittaa tilauksen, mitä vyöhykettä sovelletaan ja mikä toimitushinta veloitetaan.

Hanki ilmainen API-avain Lue API-ohjeet

Milloin API:a kutsutaan

Kutsu rajapintaa palvelinpuolella kassan tarkistusvaiheessa — ennen maksutapojen esittämistä ja ennen minkään veloituksen tekemistä.

Tärkeää: pidä API-avaimet palvelimella: Kutsu rajapintaa aina omalta palvelimeltasi, älä asiakkaan selaimesta. API-avaimesi ei saa koskaan näkyä frontend-koodissa.

Koodiesimerkki

// Server-side only — never expose your API key in browser code
async function checkDelivery(postcode, basketValueCents) {
  const res = await fetch("https://api.deliveryzone.fi/api/v1/delivery/check", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.DZ_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ destinationPostcode: postcode, basketValueCents }),
  });
  return res.json();
}

Virheenkäsittely

Kun canDeliver on false (tai null), vastaus sisältää reasonCode-kentän. Näytä tämä asiakkaalle:

NOT_DELIVERABLE — postinumero on toimitusalueidesi ulkopuolella tai sitä ei tunnisteta (rajapinta käyttää tarkoituksella yhtä yleistä koodia molemmille vyöhykerajojen suojaamiseksi)
MINIMUM_ORDER_NOT_MET — ostoskorin arvo alittaa vyöhykkeen vähimmäistilauksen
BASKET_VALUE_REQUIRED — ostoskorin arvo tarvitaan tämän kohteen vähimmäistilaus- tai ilmaistoimitussäännön arvioimiseksi

Käsittele aina HTTP-virheet (5xx, aikakatkaisu) hallitusti. Jos rajapinta ei ole tavoitettavissa, toimi turvallisesti — hylkää tilaus tai ohjaa se manuaaliseen tarkistukseen.

Käyttöönottolista

Kutsu rajapintaa palvelimeltasi, älä selaimesta
Tallenna API-avain ympäristömuuttujana
Validoi postinumeron muoto (5 numeroa) ennen rajapinnan kutsumista
Käsittele API-virheet hallitusti — älä anna aikakatkaisun estää kassaa
Testaa sekä toimitusalueen sisäiset että ulkoiset postinumerot ennen julkaisua

Valmis ottamaan postinumerotarkistuksen käyttöön?

Ilmainen aloitus. Ei luottokorttia. Aito käyttöönottoapu.

Aloita ilmaiseksi Lue API-ohjeet

Liittyvät aiheet

Kassan tarkistuksen käyttökohde Esimerkki: vyöhykkeen ulkopuolisen tilauksen esto API-dokumentaatio