---
title: "Иштеп чыгаруучу нускакасы"
description: "Quire REST API, OAuth, вебхуктар, MCP сервери жана кеңейтүүлөр."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/ky/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 документи
менен сүрөттөлгөн, окуялар үчүн кол коюлган вебхуктар жана ЖИ жардамчылары
үчүн MCP сервери менен. [API документациясы](https://docs.quirelms.com/api/) ар бир учурду жана
окуяны тизмелейт.

## Даректер <!--quire:addresses-->

Ар бир уюмун өз дареги бар, жана API анын астында жайгашкан:

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

Купуялык маалыматы уюмду чечет. Бир уюмдун килити башка уюмдун дарегинде
колдонулса, ал четке кагылат.

OpenAPI документи каалаган уюмдун дарегиндеги `/api/v1/openapi.json`
жеринен берилет, ошондуктан клиенттик генераторлор ар дайым сиз чакырып
жаткан версияны көрөт.

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

**API килттери** скрипттер жана серверден серверге болгон интеграциялар
үчүн. Администратор аны `/admin/integrations/api-keys` жеринен түзөт,
чөйрөлөрүн тандайт жана аны бир жолу көрөт. Аны 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`) же
машиналык клиент үчүн клиенттик купуялыктарды колдонуңуз. Ачылуу
`/.well-known/oauth-authorization-server` жеринде. Чөйрө токендин кыла
алганын чектейт; ал эч качан адам кыла алганынан ашык кылбайт.

Чөйрөлөр — `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` суроолоруна жөнөтүңүз. Ал ачкыч менен кайталанган суроо
  биринчи жоопту кайтарат, ишти эки жолу кылбай. Массалык учурлар аны
  талап кылат.
- **Версиялар**: негизги версия жолдо турат (`/v1`). Анын ичинде ар бир
  бузуучу өзгөрүү даталанган ревизия болуп, `Quire-Version` башкы ачкычы
  менен тандалат, мисалы `Quire-Version: 2026-09-20`. Башкы ачкыч болбосо,
  купуялык маалыматыңыз берилген учурдагы ревизияны аласыз.

Тизменин бир бети:

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

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

Ар бир ката — бул RFC 9457 маселе документи:

```
{"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` боюнча бөлүңүз:

| Category | Status | Retry |
| --- | --- | --- |
| `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`'ди цитаталоо кылыңыз.

## Вебхуктар <!--quire:webhooks-->

`/admin/webhooks` жеринен же API аркылуу `/webhook_subscriptions`
жеринен жазылыңыз. Окуяларды аты боюнча (`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. Саатыңыздан беш мүнөттөн ашык убакытты четке кагыңыз.

```
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 клиенттери, вебхуктар жана MCP сервери пландын API
укугуна таандык жана ар бир стандарттык планда камтылган. Анда жок планда
килит, клиент же жазылуу түзүлүшү четке кагылат, REST жазуулары жана MCP
tуташуулары четке кагылат, ал эми REST окуулары иштөөнү улантат, ошондо
маалымат экспорттолгон бойдон калат. Баш тартуу — `commerce.plan_entitlement`
коду бар жана `precondition` категориясындагы маселе документи.

## Кеңейтүүлөр <!--quire:extensions-->

Quire'дин өз иш-аракет түрлөрү, блоктору, каттоо ыкмалары, кирүү
ыкмалары, суроо түрлөрү, отчёттору, темалары жана интеграциялары өз
орнотууга коша ала турган кеңейтүү реестри аркылуу жарыяланат.
Кеңейтүүлөр чогулткандан кирип чыгат: убакыт ичинде жүктөлүүчү плагин
жүктөгүч жок жана хостингдеги уюм аны кошо албайт. Администраторлор
өз уюмдары үчүн ар бир кеңейтүүнү `/admin/extensions` жеринен күйгүзүп же
өчүрөт ([администратор нускакасын](/ky/admin/extensions/) караңыз).

Аны жазуу үчүн `packages/integration/extensions/src/sample.ts` ичиндеги
үлгү блоктон жана темадан баштаңыз. Кеңейтүү чекитин тандаңыз жана анын
келишимин `points.ts` ичинен окуңуз, андан кийин кеңейтүүнү id, версия,
лицензия, эмне берери жана керектөөсү, жана уюм аны өчүрө ала турганы
менен жарыялаңыз. Веб-колдонмо жана жумушчу кургилген жеринен каттатыңыз,
ошондо экөөсү макул болсун. Реестр курулганда жана `register` чакырган сайын
ар бир чекиттин өз эрежелерин текшерет, ар бир ката аталган туура эмес
топтомун четке кагат, жана андай болгондо реестрди өзгөртпөйт. Кеңейтүүнүн
өз тесттери аны үчүн `extensionContractProblems` бош экенин жана аны
өчүрүү таасир эткен нерсени өзгөртөрүн ырасташы керек.

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