---
title: "Әзірлеуші нұсқаулығы"
description: "Quire REST API, OAuth, webhook-тар, MCP сервері және кеңейтімдер."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/kk/llms.txt
> Use this file to discover all available pages before exploring further.

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

<span id="developer-guide"></span>

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

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

## Мекенжайлар <!--quire:addresses-->

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

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

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

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

## Аутентификация <!--quire:authentication-->

**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`.

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-api-keys.webp" alt="The API keys page with one key, the person it acts as, its scopes and its status, and a form to create another." width="944" height="700" loading="lazy" decoding="async"><figcaption>API keys list who each key acts as and what it may reach.</figcaption></figure>

## Сұраныстар <!--quire:requests-->

- **Беттеу**: әр тізім курсор арқылы беттеледі. `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}}
```

## Қателер <!--quire:errors-->

әр қате — 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-тар <!--quire:webhooks-->

`/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=
```

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

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

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

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-mcp.webp" alt="The AI assistants page with the server address to give an assistant and a table of the tools it can use." width="944" height="700" loading="lazy" decoding="async"><figcaption>AI assistants (MCP): the server address, and the tools an assistant may call.</figcaption></figure>

## Жоспарлар мен API <!--quire:plans-and-the-api-->

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

## Кеңейтімдер <!--quire:extensions-->

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

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

Source: https://docs.quirelms.com/kk/developer/index.mdx