--- title: "Leiðbeiningar fyrir forritara" description: "Quire REST API, OAuth, vefkrókar, MCP-þjónninn og viðbætur." image: "https://docs.quirelms.com/og.png" --- > Documentation Index > Fetch the complete documentation index at: https://docs.quirelms.com/is/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://docs.quirelms.com/api/) 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`.
The API keys page with one key, the person it acts as, its scopes and its status, and a form to create another.
API keys list who each key acts as and what it may reach.
## 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 `//deletions` til að sjá hvað var fjarlægt. - **Ytri auðkenni**: flest úrræði taka við þínu eigin `external_id`; slóðin `//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`: | Flokkur | Staða | Endurtaka | | --- | --- | --- | | `validation` | 422, með reitaupplýsingum í `errors` | Nei | | `authentication` | 401 | Nei | | `authorization` | 403 | Nei | | `not_found` | 404 | Nei | | `conflict` | 409 | Stundum | | `precondition` | 412 | Nei | | `quota` | 402 fyrir pakkann, 413 fyrir stærð | Nei | | `rate_limit` | 429, með `Retry-After` | Já | | `upstream` | 502 eða 504 | Já | | `internal` | 500 | Já | 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`.
The AI assistants page with the server address to give an assistant and a table of the tools it can use.
AI assistants (MCP): the server address, and the tools an assistant may call.
## 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](/is/admin/extensions/)). 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. Source: https://docs.quirelms.com/is/developer/index.mdx