Kehittäjän opas

Käytä organisaatiosi API-osoitetta ja rajattua tunnistetietoa. Aloita lukupyynnöllä, tarkista vastaus ja säilytä salaisuudet versionhallinnan ja dokumentaatioesimerkkien ulkopuolella.

Quiressa on yksi julkinen API: HTTPS-yhteydellä käytettävä REST-rajapinta, joka on kuvattu OpenAPI 3.1 -dokumentissa, tapahtumien allekirjoitetut webhookit ja tekoälyavustajien MCP-palvelin. API-viite luettelee kaikki päätepisteet ja tapahtumat.

Osoitteet

Jokaisella organisaatiolla on oma osoite, jonka alla sen API sijaitsee:

https://acme.quirelms.com/api/v1/courses

Tunnistetieto määrittää organisaation. Yhden organisaation avain hylätään toisen organisaation osoitteessa.

OpenAPI-dokumentti tarjoillaan minkä tahansa organisaation osoitteessa /api/v1/openapi.json, joten asiakasohjelmien generaattorit näkevät aina käyttämäsi version.

Todentaminen

API-avaimet sopivat komentojonoille ja palvelinten välisille integraatioille. Ylläpitäjä luo avaimen osoitteessa /admin/integrations/api-keys, valitsee sen käyttöoikeudet ja näkee sen vain kerran. Lähetä avain bearer-tokenina:

curl -H "Authorization: Bearer qk_live_..." https://acme.quirelms.com/api/v1/users?limit=50

Avaimen alku on qk_live_ tai qk_test_. Luo jokaiselle integraatiolle oma avain.

OAuth 2.1 sopii sovelluksille, jotka toimivat kirjautuneen henkilön nimissä. Rekisteröi asiakas osoitteessa /admin/integrations/oauth-clients ja käytä sen jälkeen PKCE-suojattua valtuutuskoodivirtaa (/oauth/authorize, /oauth/token) tai konetilin client credentials -menetelmää. Palvelun määritys löytyy osoitteesta /.well-known/oauth-authorization-server. Käyttöoikeus rajaa tokenin toimintoja; se ei koskaan anna henkilölle kuuluvia oikeuksia laajempia oikeuksia.

Käyttöoikeudet ovat muotoa resource:read, resource:write ja resource:delete, esimerkiksi courses:read tai enrolments:write. Neljä etuoikeutettua oikeutta näytetään suostumusnäkymässä varoituksen kanssa: audit:read, roles:write, tenants:write ja users:delete.

Pyynnöt

• Sivutus: kaikki luettelot käyttävät osoitinkursoria. Anna limit ja välitä sitten next_cursor-arvo page-objektista seuraavan pyynnön parametrina cursor, kun has_more on tosi (esimerkki alla). Offset-sivutusta ei ole.
• Muutokset tietyn ajan jälkeen: updated_since palauttaa sen jälkeen muuttuneet tiedot. Käytä yhdessä sen kanssa asetusta include_deleted=true tai hae osoitteesta /<resource>/deletions, niin näet myös poistetut kohteet.
• Ulkoiset tunnisteet: useimmat resurssit hyväksyvät oman external_id-arvon. /<resource>/ext:{external_id} hakee tai päivittää tiedon sen perusteella, joten synkronointi ei tarvitse Quiren tunnisteiden tallentamista.
• Idempotenssi: lähetä Idempotency-Key-otsake pyynnöissä POST, PATCH ja DELETE. Samalla avaimella tehty uudelleenyritys palauttaa ensimmäisen vastauksen tekemättä toimintoa uudelleen. Joukkopäätepisteet vaativat avaimen.
• Versiot: pääversio on polussa (/v1). Sen sisällä kukin rikkova muutos on päivämäärällä merkitty versio, joka valitaan Quire-Version-otsakkeella, esimerkiksi Quire-Version: 2026-09-20. Ilman otsaketta käytetään tunnistetietosi myöntämisen aikaan voimassa ollutta versiota.

Esimerkki luettelon sivusta:

{"data": [...], "page": {"next_cursor": "eyJ2Ijox...", "has_more": true, "limit": 100}}

Virheet

Kaikki virheet palautetaan RFC 9457 -ongelmadokumentteina:

{"type": "https://quire.com/errors/enrolment.seat_limit_reached",
 "title": "Seat limit reached", "status": 409,
 "code": "enrolment.seat_limit_reached", "category": "conflict",
 "detail": "The course has no seats left, so this enrolment was not created. ...",
 "request_id": "01JB7XQK4Z..."}

Käsittele pysyvän tunnisteen code perusteella. Ihmisille kirjoitettu detail on turvallista näyttää käyttäjille, mutta sen sanamuoto voi muuttua. Jos koodi on tuntematon, luokittele virhe category-arvon perusteella:

Mainitse tukipyynnössä request_id.

Webhookit

Tilaa webhook osoitteessa /admin/webhooks tai API:n kautta osoitteessa /webhook_subscriptions. Valitse tapahtumat nimellä (enrolment.created), aihealueittain (enrolment.*) tai kaikki (*). Quire lähettää ensin webhook.ping-tapahtuman. Tilaus alkaa, kun päätepisteesi vastaa siihen.

Toimitukset noudattavat Standard Webhooks -määritystä:

POST /hooks/quire
webhook-id: 01JB7XQK4Z8FQ2M3N4P5R6S7T8
webhook-timestamp: 1790000000
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

Tarkista toimitus näin:

1. Muodosta vastaanotetuista tarkoista tavuista ennen JSON-jäsennystä merkkijono {webhook-id}.{webhook-timestamp}.{raw body}.
2. Laske merkkijonosta HMAC-SHA256 tilauksen salaisuudella ja koodaa tulos base64-muotoon.
3. Vertaa sitä vakioajassa v1,-arvoihin, jotka ovat webhook-signature-otsakkeessa. Salaisuutta vaihdettaessa arvoja voi olla kaksi; kumpi tahansa kelpaa.
4. Hylkää aikaleima, joka poikkeaa kellostasi yli viidellä minuutilla.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, id, timestamp, rawBody, header) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', Buffer.from(secret.replace(/^whsec_/, ''), 'base64'))
    .update(`${id}.${timestamp}.${rawBody}`).digest();
  return header.split(' ').some((part) => {
    const [version, value] = part.split(',');
    const given = Buffer.from(value ?? '', 'base64');
    return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);
  });
}

Poista kaksoistoimitukset webhook-id-tunnisteen perusteella, sillä toimitus voi tulla useammin kuin kerran. Runko sisältää tunnisteet ja lyhyen yhteenvedon. Hae resurssi, kun tarvitset sen ajantasaisen tilan. Epäonnistunutta toimitusta yritetään uudelleen kasvavilla viiveillä enintään 72 tuntia, ja se voidaan toistaa toimituslokista.

MCP

Quiren MCP-palvelin sijaitsee organisaation osoitteessa /mcp, ja sen kanssa viestitään streamattavalla HTTP-yhteydellä. MCP-asiakas löytää OAuth-palvelimen osoitteesta /.well-known/oauth-protected-resource. Käyttäjä kirjautuu sisään ja antaa suostumuksensa kuten mille tahansa OAuth-asiakkaalle. Työkalut toimivat käyttäjän oikeuksilla, ja tuhoavat toiminnot pyytävät vahvistusta. Ylläpitäjät valitsevat käytettävissä olevat työkalut osoitteessa /admin/integrations/mcp.

Palvelupaketit ja API

API-avaimet, OAuth-asiakkaat, webhookit ja MCP-palvelin kuuluvat paketin API-oikeuteen, joka sisältyy jokaiseen tavalliseen palvelupakettiin. Jos paketti ei sisällä sitä, avaimen, asiakkaan tai tilauksen luonti estetään, REST-kirjoituspyynnöt ja MCP-yhteydet estetään ja REST-lukupyynnöt toimivat edelleen tietojen viemistä varten. Estosta palautetaan ongelmadokumentti, jonka koodi on commerce.plan_entitlement ja luokka precondition.

Laajennukset

Quiren omat toimintotyypit, lohkot, ilmoittautumistavat, kirjautumistavat, kysymystyypit, raportit, teemat ja integraatiot määritellään samassa laajennusrekisterissä, johon itse ylläpidetyssä asennuksessa voi lisätä laajennuksia. Laajennukset käännetään osaksi sovellusta. Käyttöaikaista lisäosien lataajaa ei ole, eikä isännöity organisaatio voi lisätä laajennuksia. Ylläpitäjät ottavat laajennukset käyttöön tai poistavat ne käytöstä osoitteessa /admin/extensions (katso ylläpitäjän opas).

Aloita laajennuksen kirjoittaminen tiedoston packages/integration/extensions/src/sample.ts esimerkkilohkosta ja teemasta. Valitse laajennuspiste ja lue sen sopimus tiedostosta points.ts. Määritä sitten laajennukselle tunniste, versio, lisenssi, sen tarjoamat ja tarvitsemat asiat sekä tieto siitä, saako organisaatio poistaa sen käytöstä. Rekisteröi laajennus kohtaan, jossa verkkosovellus ja työntekijäprosessi kootaan, jotta ne ovat samaa mieltä. Rekisteri tarkistaa kunkin laajennuspisteen säännöt luonnin yhteydessä ja jokaisella register-kutsulla. Se hylkää virheellisen kokonaisuuden ilmoittaen kaikki ongelmat ja jättää rekisterin ennalleen. Laajennuksen omissa testeissä tulee varmistaa, että extensionContractProblems ei ilmoita ongelmia ja että käytöstä poistaminen muuttaa sen vaikutuksia.