Leiðbeiningar fyrir forritara

Notaðu API-slóð stofnunarinnar þinnar og auðkenni með afmörkuðum heimildum. Byrjaðu á lesbeiðni, athugaðu svarið og geymdu leyndarmál utan útgáfustýringar og dæma í skjölum.

Quire er með eitt opinbert API: REST yfir HTTPS, lýst í OpenAPI 3.1 skjali, með undirrituðum vefkrókum fyrir atburði og MCP-þjóni fyrir gervigreindaraðstoðarmenn. API-tilvísunin telur upp alla endapunkta og atburði.

Heimilisföng

Hver stofnun hefur eigið heimilisfang og API-ið er undir því:

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

Auðkennið ræður stofnuninni. Beiðni með lykli einnar stofnunar á heimilisfangi annarrar er hafnað.

OpenAPI-skjalinu er þjónað á /api/v1/openapi.json á heimilisfangi sérhverrar stofnunar, svo rafall biðlara sér alltaf þá útgáfu sem þú ert að kalla á.

Auðkenning

API-lyklar eru fyrir forskriftir og samþættingar milli þjóna. Stjórnandi býr til lykil á /admin/integrations/api-keys, velur heimildasvið hans og sér hann aðeins einu sinni. Sendu hann sem bearer token:

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

Lyklar byrja á qk_live_ eða qk_test_. Gefðu hverri samþættingu sinn eigin lykil.

OAuth 2.1 er fyrir forrit sem framkvæma aðgerðir sem innskráður einstaklingur. Skráðu biðlara á /admin/integrations/oauth-clients og notaðu síðan heimildarkóða með PKCE (/oauth/authorize, /oauth/token) eða biðlaraauðkenni fyrir vélbúnað. Uppgötvun er á /.well-known/oauth-authorization-server. Heimildasvið takmarkar það sem auðkenni má gera; það veitir því aldrei meiri heimild en einstaklingurinn hefur sjálfur.

Heimildasvið eru resource:read, resource:write og resource:delete, til dæmis courses:read eða enrolments:write. Fjórum sviðum fylgir viðvörun á samþykkissíðunni því þau veita aukin réttindi: audit:read, roles:write, tenants:write og users:delete.

Beiðnir

• Síðuskipting: allir listar eru blaðsíðuskiptir með bendli. Sendu limit og síðan next_cursor úr page sem cursor á meðan has_more er satt (sjá dæmi hér á eftir). Ekki er hægt að nota færslunúmer.
• Breytingar frá tilteknum tíma: updated_since skilar því sem hefur breyst eftir tímann. Notaðu með include_deleted=true eða lestu /<resource>/deletions til að sjá hvað var fjarlægt.
• Ytri auðkenni: flest úrræði taka við þínu eigin external_id; slóðin /<resource>/ext:{external_id} les eða uppfærir eftir því. Samstilling þarf því aldrei að geyma auðkenni Quire.
• Idempotency: sendu hausinn Idempotency-Key með POST, PATCH og DELETE. Endurtekin beiðni með sama lykli skilar upphaflegu svari í stað þess að vinna verkið aftur. Lotaendapunktar krefjast hans.
• Útgáfur: aðalútgáfan er í slóðinni (/v1). Innan hennar eru ósamhæfar breytingar dagsettar og valdar með hausnum Quire-Version, til dæmis Quire-Version: 2026-09-20. Án hauss færðu þá endurskoðun sem var gild þegar auðkennið þitt var gefið út.

Ein blaðsíða úr lista:

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

Villur

Hver villa er RFC 9457-vandamálaskjal:

{"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..."}

Veldu með code, sem breytist ekki; detail er skrifað fyrir fólk, óhætt að sýna því og getur breyst. Þegar þú þekkir ekki kóða skaltu flokka eftir category:

Vísaðu í request_id þegar þú hefur samband við aðstoð.

Vefkrókar

Gerðu áskrift á /admin/webhooks eða með API á /webhook_subscriptions. Veldu atburði eftir heiti (enrolment.created), svæði (enrolment.*) eða alla atburði (*). Quire sendir fyrst webhook.ping; áskriftin hefst þegar endapunkturinn þinn svarar honum.

Sendingar fylgja Standard Webhooks-staðlinum:

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

Til að sannreyna sendingu:

1. Settu saman strenginn {webhook-id}.{webhook-timestamp}.{raw body} úr nákvæmlega mótteknum bætum áður en JSON er þátta.
2. Reiknaðu HMAC-SHA256 yfir strenginn með leyndarmáli áskriftarinnar og breyttu niðurstöðunni í base64.
3. Berðu saman við hvert v1,-gildi í webhook-signature með tímajafnri samanburðaraðferð. Tvö gildi geta verið meðan lykli er skipt út; annað hvort má passa.
4. Hafnaðu tímastimpli sem er meira en fimm mínútur frá klukkunni þinni.

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);
  });
}

Forðastu tvítekningar með webhook-id: sending getur borist oftar en einu sinni. Meginmálið inniheldur auðkenni og stutta samantekt; sæktu úrræðið til að fá núverandi stöðu þess. Sendingar sem mistakast eru endurteknar með vaxandi bið í allt að 72 klukkustundir og hægt er að endurspila þær úr afhendingarskránni.

MCP

MCP-þjónn Quire er á /mcp á heimilisfangi stofnunarinnar yfir streamable HTTP. MCP-biðlari finnur OAuth-þjóninn í /.well-known/oauth-protected-resource og einstaklingurinn skráir sig inn og samþykkir aðgang eins og með öðrum OAuth-biðlara. Verkfæri framkvæma aðgerðir sem viðkomandi með hans heimildum og eyðandi aðgerðir krefjast staðfestingar. Stjórnendur velja tiltæk verkfæri á /admin/integrations/mcp.

Pakkar og API

API-lyklar, OAuth-biðlarar, vefkrókar og MCP-þjónninn heyra undir API-heimild pakkans og allir staðlaðir pakkar innihalda hana. Í pakka án hennar er ekki hægt að stofna lykil, biðlara eða áskrift, REST-skrifum og MCP-tengingum er hafnað en REST-lesaðgangur helst opinn svo hægt sé að flytja gögnin út. Höfnunin er vandamálaskjal með kóðanum commerce.plan_entitlement í flokknum precondition.

Viðbætur

Eigin verkefnategundir, blokkir, skráningaraðferðir, innskráningaraðferðir, spurningategundir, skýrslur, þemu og samþættingar Quire eru skilgreind með sömu viðbótaskrá og sjálfhýst uppsetning getur bætt við. Viðbætur eru innbyggðar við smíði: engin viðbótahleðsla er á keyrslutíma og stofnun á hýstri þjónustu getur ekki bætt við viðbót. Stjórnendur kveikja og slökkva á hverri viðbót fyrir sína stofnun á /admin/extensions (sjá leiðbeiningar stjórnenda).

Til að skrifa viðbót skaltu byrja á sýniblokk og þema í packages/integration/extensions/src/sample.ts. Veldu viðbótarpunkt og lestu samning hans í points.ts; lýstu svo viðbótinni með auðkenni, útgáfu, leyfi, því sem hún býður og krefst og hvort stofnun megi slökkva á henni. Skráðu hana þar sem vefappið og bakvinnslan eru sett saman svo hvort tveggja sé sammála. Skráin kannar reglur hvers punkts við smíði og í hvert sinn sem register er kallað. Hún hafnar ógildri samsetningu, nefnir öll vandamál og breytir ekki skránni þegar það gerist. Eigin próf viðbótarinnar ættu að staðfesta að extensionContractProblems sé tómt fyrir hana og að það breyti áhrifum hennar að slökkva á henni.