---
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/mn/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 баримт бичгээр тодорхойлогдсон, үйл явдлуудад зориулсан гарын үсэгтэй вебхүүкүүд, мөн AI туслахуудад зориулсан 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` дээр нэгийг үүсгэж, эрхүүдийг нь сонгоод, нэг удаа хардаг. Үүнийг bearer token болгон илгээнэ үү:

```
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` дээр байна. Эрх нь token-ыг юу хийж болохыг хязгаарладаг; хэзээ ч хүний чаддагаас илүүг үүсгэхгүй.

Эрхүүд нь `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 асуудлын баримт бичиг юм:

```
{"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`-г иш татна уу.

## Вебхүүкүүд <!--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` дэх утгуудтай жинээр (constant time) харьцуулна уу. Нууц солих үед хоёр байж болно; аль нь ч тохирсон байвал зөв.
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 клиент нь `/.well-known/oauth-protected-resource`-аас OAuth серверийг олдог бөгөөд хэрэглэгч ямар ч 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 холболтуудыг татгалзах бөгөөд REST унших үргэлжлэн ажиллаж, өгөгдөл экспортлох боломжтой хэвээр үлдэнэ. Татгалз нь `commerce.plan_entitlement` кодтой, `precondition` ангийн асуудлын баримт бичиг юм.

## Өргөтгөлүүд <!--quire:extensions-->

Quire-н өөрийн үйл ажиллагааны төрлүүд, блокууд, элсэлтийн аргууд, нэвтрэх аргууд, асуултын төрлүүд, тайлан, темплейт болон холболтууд нь өөрийн өргөтгөлийн реестрээр дамжуулан тодорхойлогддог бөгөөд өөрийн сервер суулгалт үүнд нэмэлт хийж болно. Өргөтгөлүүд бүтээгдэхүүнд багтсан байдаг: ажиллагааны үед plugin ачаалагч байдаггүй, мөн хостлагдсон байгууллага нэгийг нь нэмж чадахгүй. Администраторууд байгууллагынхаа хувьд өргөтгөл бүрийг `/admin/extensions` дээр нээх эсвэл хаах ([администраторын гарын авлага](/mn/admin/extensions/) үзэнэ үү).

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

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