API

Lue ja kirjoita kanta-asiakastietoja omasta taustapalvelustasi Gibbondin ulkoisella GraphQL-API:lla — rekisteröi jäseniä, myönnä ja lunasta pisteitä sekä synkronoi toimintaa mistä tahansa kanavasta.

Tällä sivulla

⚡

Pro-tilaus vaaditaan. Ulkoinen API on käytettävissä Pro-tilauksella. Ota se käyttöön päivittämällä tilaus Gibbondin hallinnan Tilaukset ja laskutus -sivulla.

🚀

Onko API sinulle uusi? Integrointioppaassa on käytännön esimerkkejä, jotka voit kopioida suoraan käyttöön — kutsut taustapalvelusta, integrointi mobiili- tai verkkosovellukseen ja pisteiden ansaitseminen toisesta myyntikanavasta. Tämä sivu sisältää täydellisen skeemaviitteen.

API:ssa on yksi GraphQL-päätepiste. Lähetä POST-pyyntö, jonka JSON-runko sisältää query-kyselyn (tai mutaation) ja valinnaiset variables-muuttujat:

POST https://app.gibbond.com/api/v1/graphql

Kaikki aikaleimat ovat ISO-8601-merkkijonoja ja kaikki tunnisteet Shopify-GID-tunnisteita (esimerkiksi gid://shopify/Customer/123), ellei toisin mainita. Pisteet ovat kokonaislukuja.

Todentaminen

Jokainen pyyntö sisältää tunnistetiedon Authorization-otsakkeessa. Tunnistetietoja on kahta tyyppiä kahteen eri käyttötarkoitukseen.

API-avaimet (palvelinpuoli)

API-avaimet tunnistavat taustapalvelusi. Luo ne Gibbondin hallinnan API-avaimet-sivulla, jossa kullekin avaimelle annetaan käyttöoikeustaso (READ, WRITE tai ADMIN). Avain näytetään vain kerran luomisen yhteydessä, ja se on muotoa glk_live_…. Lähetä se bearer-tunnisteena:

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx

⚠️

Vain palvelinpuolella. API-avain voi lukea ja muuttaa kaikkien jäsenten tietoja, joten sitä ei saa koskaan paljastaa selaimessa, mobiilisovelluksessa tai asiakasohjelmassa, jota et hallitse. Säilytä se palvelimen ympäristömuuttujassa. Jos avain vuotaa, mitätöi paljastunut avain ja luo uusi hallinnassa.

Asiakastunnisteet (asiakaspuoli)

Kun sinun pitää kutsua API:a asiakkaalle näkyvästä käyttöliittymästä (verkkokaupan widgetistä tai mobiilisovelluksesta), luo asiakastunniste taustapalvelussasi mintCustomerToken-mutaatiolla ja välitä tunniste asiakasohjelmalle. Asiakastunnisteet ovat lyhytikäisiä ja rajattu yhteen asiakkaaseen: tällaisella tunnisteella tehty pyyntö voi lukea tietoja ja tehdä toimintoja vain kyseiselle asiakkaalle. me-kysely palauttaa tunnisteeseen liittyvän asiakkaan, ja redeemReward toimii kyseiselle asiakkaalle ilman kauppiaan avainta — siksi tunnisteen voi turvallisesti välittää selaimeen.

Authorization: Bearer <customer token>

Käyttöoikeustasot

API-avaimen käyttöoikeustaso määrittää, mitä toimintoja sillä voi suorittaa. Käyttöoikeustasot ovat kumulatiivisia.

Käyttöoikeustaso	Sallitut toiminnot
`READ`	Kaikki kyselyt (saldot, historia, palkinnot, tasot ja asetukset).
`WRITE`	Kaikki `READ`-tason toiminnot sekä mutaatiot, jotka rekisteröivät jäseniä, myöntävät positiivisia pisteitä, lunastavat palkintoja, vahvistavat pisteitä ja luovat asiakastunnisteita.
`ADMIN`	Kaikki `WRITE`-tason toiminnot sekä pisteiden takaisinperintä (`clawbackPoints`) ja negatiiviset oikaisut `awardPoints`-mutaatiolla (negatiivinen `points`-arvo).

ℹ️

Käytä pienintä tarvittavaa käyttöoikeustasoa — READ-avainta analytiikkaan ja WRITE-avainta pisteiden ansaitsemiseen ja palkintojen lunastamiseen. Varaa ADMIN hyvityksiin ja oikaisuihin.

Pyyntörajoitukset

Kunkin tunnistetiedon (jokaisen API-avaimen ja asiakastunnisteen) raja on 600 pyyntöä minuutissa. Kun raja ylittyy, API palauttaa HTTP-tilan 429 ja Retry-After-otsakkeen, joka kertoo, kuinka monta sekuntia on odotettava ennen uutta yritystä.

Kyselyt

Kyselyt vaativat avaimen, jolla on vähintään READ-oikeus, tai asiakastunnisteen (jolla voi lukea vain oman asiakkaan tietoja).

Kysely	Argumentit	Paluuarvo / kuvaus
`me`	—	Asiakas, johon asiakaskohtainen tunniste liittyy. Palauttaa virheen, jos kutsussa käytetään kauppiaan API-avainta.
`customer`	`id: ID!`	Yksittäinen asiakas GID-tunnisteen perusteella.
`customers`	`ids: [ID!]!`	Useiden asiakkaiden lukeminen kerralla GID-tunnisteiden perusteella (kauppiaan avain, `READ`).
`customerByEmail`	`email: String!`	Hae asiakas sähköpostiosoitteen perusteella (kauppiaan avain, `READ`).
`rewards`	—	Kaupan lunastettavien palkintojen valikoima.
`tiers`	—	Kaupan VIP-tasot (slug, nimi, kynnysarvo ja kerroin).
`shopConfig`	—	Ohjelman asetukset: nimi, valuutta, pisteet dollaria kohden, vahvistustapa, tasot ja palkinnot.
`pointHistory`	`customerId: ID!`, `limit: Int`	Asiakkaan pistetapahtumat, uusimmat ensin.
`activeCodes`	`customerId: ID!`	Asiakkaan käyttämättömät alennuskoodit (lunastukset ja tasoedut).
`referral`	`customerId: ID!`	Asiakkaan suosittelukoodi sekä kutsuttujen, ehdot täyttäneiden ja palkittujen asiakkaiden määrät.
`totalLiability`	—	Kaupan koko avoin pistevastuu kokonaislukuna (kauppiaan avain, `READ`).

Mutaatiot

Mutaatiot vaativat WRITE-avaimen, ellei toisin mainita. ADMIN-oikeutta vaativat toiminnot on merkitty.

Mutaatio	Argumentit	Paluuarvo / kuvaus
`enrollCustomer`	`customerId: ID!`, `email: String`	Rekisteröi asiakas kanta-asiakasohjelmaan (`WRITE`). Palauttaa `CustomerResult`-tuloksen.
`awardPoints`	`customerId: ID!`, `points: Int!`, `reason: String`, `idempotencyKey: String`	Myönnä tai oikaise pisteitä. Negatiivinen `points`-arvo vaatii `ADMIN`-oikeuden; `idempotencyKey` estää kaksoiskäsittelyn uudelleenyrityksissä. Palauttaa `PointResult`-tuloksen.
`awardPointsForOrder`	`input: OrderInput!`	Ansaitse pisteitä toisessa kanavassa tehdystä tilauksesta; käyttää samaa tasokerrointa, Boosts-toimintoa ja virstanpylväitä. Idempotentti `orderId`-tunnisteen perusteella (`WRITE`). Palauttaa `PointResult`-tuloksen.
`redeemReward`	`customerId: ID!`, `rewardId: ID!`	Lunasta palkinto kertakäyttöiseksi alennuskoodiksi (`WRITE` tai omaa asiakastaan edustava asiakastunniste). Palauttaa `RedeemResult`-tuloksen.
`confirmPoints`	`customerId: ID!`, `orderId: ID`	Vahvista asiakkaan odottavat pisteet, esimerkiksi tilauksen toimittamisen jälkeen (`WRITE`). Palauttaa vahvistettujen pisteiden määrän.
`clawbackPoints`	`customerId: ID!`, `orderId: ID!`, `refundAmount: Float!`, `orderTotal: Float!`, `refundId: ID`	Peru pisteet hyvityksen yhteydessä (`ADMIN`). Palauttaa peruttujen pisteiden määrän.
`mintCustomerToken`	`customerId: ID!`, `ttlSeconds: Int`	Luo lyhytikäinen, asiakaskohtainen tunniste asiakaspuolen käyttöön (`WRITE` / `ADMIN`). Palauttaa `CustomerToken`-tunnisteen ja sen `expiresAt`-arvon.

ℹ️

awardPointsForOrder vastaanottaa OrderInput-syötteen: orderId, customerId, valinnaiset customerEmail ja orderName sekä lineItems-listan. Jokainen tilausrivi sisältää valinnaisen productId-arvon, valinnaiset collectionIds-arvot ja lineTotal-arvon — joten tuote- ja kokoelmakohtaiset Boosts-säännöt ja poissulut pätevät samalla tavalla kuin tavallisiin Shopify-tilauksiin.

Esimerkkipyyntö

Lue asiakkaan saldo ja taso palvelinpuolen API-avaimella:

curl https://app.gibbond.com/api/v1/graphql \
  -X POST \
  -H "Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id: ID!) { customer(id: $id) { email balance pending lifetime tier { name multiplier } } }",
    "variables": { "id": "gid://shopify/Customer/123456789" }
  }'

Virhekoodit

Virheet noudattavat GraphQL-käytäntöä: ylimmän tason errors-taulukon jokainen alkio sisältää code-arvon extensions-kentässä ja vastaavan HTTP-tilan.

Koodi	HTTP	Merkitys
`UNAUTHENTICATED`	401	Tunnistetieto puuttuu, on väärässä muodossa tai vanhentunut.
`FORBIDDEN`	403	Tunnistetieto on kelvollinen, mutta siltä puuttuu toiminnon vaatima käyttöoikeustaso.
`RATE_LIMITED`	429	Pyyntöraja on ylitetty; yritä uudelleen `Retry-After`-otsakkeessa ilmoitetun odotusajan jälkeen.
`BAD_USER_INPUT`	400	Virheelliset argumentit — virheellinen GID, puuttuva pakollinen kenttä tai arvo sallitun alueen ulkopuolella.
`NOT_FOUND`	404	Viitattua asiakasta, palkintoa tai muuta resurssia ei ole olemassa.