Әзірлеуші нұсқаулығы

Quire REST API, OAuth, webhook-тар, MCP сервері және кеңейтімдер.

Ұйымыңыздың API мекенжайын және шектелген құқықтары бар кілтті пайдаланыңыз. Оқу сұранысынан бастаңыз, жауапты тексеріңіз және құпияларды басқару жүйесі мен құжаттама мысалдарының сыртында ұстаңыз.

Quire-дің бір ғана ашық API-і бар: HTTPS үстіндегі REST, OpenAPI 3.1 құжатымен сипатталған, оқиғаларға арналған қол қойылған webhook-тармен және ЖИ көмекшілеріне арналған MCP серверімен. API анықтамасы әр endpoint пен оқиғаны тізеді.

Мекенжайлар

Әр ұйымның өз мекенжайы бар, ал API соның астында тұрады:

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

Кілт ұйымды шешеді. Бір ұйымның кілті басқа ұйымның мекенжайында қабылданбайды.

OpenAPI құжаты кез келген ұйымның мекенжайындағы /api/v1/openapi.json мекенжайынан қызмет етіледі, сондықтан клиент генераторлары әрқашан шақырып тұрған нұсқаңызды көреді.

Аутентификация

API кілттері скрипттер мен серверден серверге интеграциялар үшін. Әкімші оны /admin/integrations/api-keys бөлімінде жасайды, оның scope-тарын таңдайды және оны бір рет көреді. Оны bearer токені ретінде жіберіңіз:

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

Кілттер qk_live_ немесе qk_test_ деп басталады. әр интеграцияға өз кілтін беріңіз.

OAuth 2.1 кірген адам атынан әрекет ететін қосымшалар үшін. Клиентті /admin/integrations/oauth-clients бөлімінде тіркеп, содан кейін PKCE-мен авторизация кодының ағымын (/oauth/authorize, /oauth/token) немесе машиналық клиент үшін клиент кілттерін пайдаланыңыз. Discovery /.well-known/oauth-authorization-server мекенжайында. Scope токен не істей алатынын тарылтады; ол адам істей алмайтын нәрсені істеуге ешқашан рұқсат етпейді.

Scope-тар: resource:read, resource:write және resource:delete, мысалы courses:read немесе enrolments:write. Төртеуі жеңілдікке ие және келісім экранында ескертумен көрсетіледі: audit:read, roles:write, tenants:write және 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.

Сұраныстар

Беттеу: әр тізім курсор арқылы беттеледі. limit жіберіңіз, содан кейін next_cursor-ті page-тен cursor ретінде has_more шын болғанша жіберіңіз (мысалы төменде). Offset жоқ.
Өзгерістер: updated_since белгілі бір уақыттан кейін не өзгергенін қайтарады. Оны include_deleted=trueмен жұптаңыз, немесе нені жойылғанын білу үшін /<resource>/deletions оқыңыз.
Сыртқы идентификаторлар: көп ресурстар сіздің өз external_id-іңізді қабылдайды, ал /<resource>/ext:{external_id} онымен оқиды немесе жаңартады, сондықтан синхрондауға Quire-дің идентификаторларын сақтау қажет емес.
Идемпотенттілік: Idempotency-Key тақырыбын POST, PATCH және DELETE үшін жіберіңіз. Сол кілтпен қайта жіберу жұмысты екі рет істемей, бірінші жауапты қайтарады. Топтас endpoint-тер оны талап етеді.
Нұсқалар: негізгі нұсқа жолда (/v1) тұрады. Оның ішінде әр бұзатын өзгеріс күні қойылған ревизия, ол Quire-Version тақырыбы арқылы таңдалады, мысалы Quire-Version: 2026-09-20. Тақырып болмаса, кілт берілген сәттегі ағымдағы ревизияны аласыз.

Тізімнің бір беті:

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

Қателер

әр қате — RFC 9457 problem құжаты:

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

Тұрақты code бойынша тармақтаныңыз; detail адамдарға жазылған, оларға көрсетуге қауіпсіз және өзгеруі мүмкін. Кодты танымасаңыз, category бойынша топтаңыз:

Санат	Күй	Қайталау
`validation`	422, `errors` ішінде өріс деректерімен	Жоқ
`authentication`	401	Жоқ
`authorization`	403	Жоқ
`not_found`	404	Жоқ
`conflict`	409	Кейде
`precondition`	412	Жоқ
`quota`	402 жоспар үшін, 413 өлшем үшін	Жоқ
`rate_limit`	429, `Retry-After` бар	Иә
`upstream`	502 немесе 504	Иә
`internal`	500	Иә

Қолдау қызметіне хабарласқанда request_id-ді келтіріңіз.

Webhook-тар

/admin/webhooks бөлімінде немесе /webhook_subscriptions арқылы API-ге жазылыңыз. Оқиғаларды атауы бойынша (enrolment.created), аймағы бойынша (enrolment.*) немесе барлығы (*) бойынша таңдаңыз. Quire алдымен webhook.ping жібереді; жазылым endpoint-іңіз жауап бергенде басталады.

Жеткізілімдер Standard Webhooks спецификациясын ұстанады:

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

Жеткізілімді тексеру үшін:

JSON өңдеуінен бұрын, дәл алынған байттардан {webhook-id}.{webhook-timestamp}.{raw body} жолын құрастырыңыз.
Оны жазылым құпиясымен үстіне HMAC-SHA256 есептеп, base64-ке салыңыз.
әр v1, мәнін webhook-signature тақырыбында тұрақты уақытта салыстырыңыз. Құпия ауыстырылған кезде екеуі болуы мүмкін; кез келгені сәйкес келсе жарамды.
Сағатыңыздан бес минуттан асатын timestamp-ті қабылдамаңыз.

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

webhook-id бойынша қайталануды алып тастаңыз: бір жеткізілім бірнеше рет келуі мүмкін. Денеде идентификаторлар және қысқа шолу болады; ағымдағы күйі үшін ресурсты алыңыз. Сәтсіз жеткізілімдер 72 сағатқа дейін кейінге қарай қайталанады және жеткізу журналынан қайта ойнатуға болады.

MCP

Quire-дің MCP сервері ұйым мекенжайындағы /mcp мекенжайында, streamable HTTP арқылы тұрады. MCP клиенті OAuth серверін /.well-known/oauth-protected-resource мекенжайынан табады, ал адам кез келген OAuth клиентіндегідей кіріп, келісім береді. Құралдар сол адамның рұқсаттарымен әрекет етеді, ал бұзатын құралдар растау сұрайды. Әкімшілер қай құралдар қолжетімді екенін /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.

Жоспарлар мен API

API кілттері, OAuth клиенттері, webhook-тар және MCP сервері жоспардың API құқығына жатады, және әр стандартты жоспар оны қамтиды. Осы құқық жоқ жоспарда кілт, клиент немесе жазылым жасау қабылданбайды, REST жазулары мен MCP байланыстары қабылданбайды, ал REST оқуы жұмыс істей береді, сондықтан деректер экспортталып тұрады. Бас тарту — commerce.plan_entitlement коды бар, precondition санатындағы problem құжаты.

Кеңейтімдер

Quire-дің өз әрекет түрлері, блоктары, тіркеу әдістері, кіру әдістері, сұрақ түрлері, есептері, тақырыптары және интеграциялары өз орнатылымы қоса алатын сол кеңейтім реестрі арқылы жарияланады. Кеңейтімдер компиляцияланған: уақыт ішінде жүктейтін плагин жоқ, және хостингтегі ұйым оны қоса алмайды. Әкімшілер әр кеңейтімді ұйымы үшін /admin/extensions бөлімінде қосады немесе өшіреді (әкімші нұсқаулығын қараңыз).

Оны жазу үшін packages/integration/extensions/src/sample.ts файлындағы үлгі блок пен тақырыптан бастаңыз. Кеңейтім нүктесін таңдап, оның келісімін points.ts файлынан оқыңыз, содан кейін кеңейтімді id, нұсқа, лицензия, не ұсынатыны мен не қажет ететіні, және ұйым оны өшіре ала ма екенімен жариялаңыз. Веб-қосымша мен жұмысшы құрастырылатын жерге тіркеңіз, сонда екеуі де келіседі. Реестр әр нүктенің өз ережелерін құрылған кезде және register шақырған әр жолда тексереді, әр қатесі аталған жарамсыз болатын жиынтықты қабылдамайды және сондай болса реестрді өзгеріссіз қалдырады. Кеңейтімнің өз тесттері ол үшін extensionContractProblems бос екенін және оны өшіргенде әсер ететін нәрсенің өзгеретінін растауы керек.