Integraatio-ohje
Shopify-integraatio-opas
Shopifyssa ei ole sisäänrakennettua tapaa tarkistaa postinumeroita suomalaisten toimitusalueiden vaatimalla tarkkuudella. Delivery Zone API:a voidaan kutsua Shopifyn mukautetun sovelluksen taustajärjestelmästä tai Shopify Functions -toimitusmuokkauksesta postinumerotason sääntöjen valvomiseksi.
Milloin API:a kutsutaan
Kutsu rajapintaa mukautetun sovelluksesi taustapalvelusta kassan aikana tai Shopify Functions -toimitustoiminnosta. Aina palvelinpäässä — ei koskaan verkkokaupan teematiedostosta.
Tärkeää: pidä API-avaimet palvelimella: Delivery Zone API -avaimesi on pysyttävä palvelimella. Älä koskaan sisällytä sitä Shopify-teematiedostoihin, selaimessa ajettavaan JavaScriptiin tai mihinkään selaimeen päätyvään koodiin.
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äistilauksenBASKET_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
- Käytä Shopifyn mukautettua sovellusta tai Shopify Functionsia — älä teematiedostoja
- Tallenna API-avain ympäristömuuttujiin tai Shopify-sovelluksen salaisuuksiin
- Testaa kehityskaupassa ei-tuotantovyöhykkeellä ennen aktivoimista
- Käsittele API-virheet hallitusti, jotta kassa ei kaadu häiriötilanteissa
- Vahvista vyöhykkeen ulkopuolisten tilausten hylkäystoiminta ennen julkaisua
Valmis ottamaan postinumerotarkistuksen käyttöön?
Ilmainen aloitus. Ei luottokorttia. Aito käyttöönottoapu.