Хөгжүүлэгчийн гарын авлага

Байгууллагынхаа API хаяг болон хүрээгээр хязгаарлагдсан итгэмжлэл ашиглана уу. Эхлээд унших хүсэлтээр эхлээд, хариуг шалгаад, нууц түлхүүрүүдээ эх кодын хяналт болон баримт бичгийн жишээнүүдээс гадна хадгалаарай.

Quire нэгэн нийтлэг API-тай: HTTPS дээрх REST, OpenAPI 3.1 баримт бичгээр тодорхойлогдсон, үйл явдлуудад зориулсан гарын үсэгтэй вебхүүкүүд, мөн AI туслахуудад зориулсан MCP сервер. API-н гарын авлага бүх endpoint болон үйл явдлыг жагсаана.

Хаягууд

Бүр байгууллага өөрийн хаягтай бөгөөд API түүний дор байрлана:

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

Итгэмжлэл байгууллагыг шийднэ. Нэг байгууллагын түлхүүрийг өөр байгууллагын хаяг дээр ашиглавал татгалзана.

OpenAPI баримт бичиг нь аль ч байгууллагын хаяг дээр /api/v1/openapi.json дээр үйлчлүүлэгддэг тул клиент үүсгэгчид таны дуудаж буй хувилбарыг үзэх болно.

Баталгаажуулалт

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.

Хүсэлтүүд

• Хуудаслалт: бүх жагсаалт курсороор хуудаслагдана. 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 асуудлын баримт бичиг юм:

{"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-аар бүлэглэнэ үү:

Тусламж хандаж буйдаа request_id-г иш татна уу.

Вебхүүкүүд

/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 сервер нь байгууллагын хаяг дээрх /mcp дээр байрлана, streamable HTTP дамжуулалтаар. MCP клиент нь /.well-known/oauth-protected-resource-аас OAuth серверийг олдог бөгөөд хэрэглэгч ямар ч OAuth клиенттэй адил нэвтэрч, зөвшөөрөл өгдөг. Хэрэгслүүд тухайн хүний эрхээр, түүний зөвшөөрлөөр ажилладаг бөгөөд устгах хэрэгслүүд баталгаажуулалт асуудаг. Администраторууд /admin/integrations/mcp дээр аль хэрэгслүүд боломжтойг сонгодог.

Төлөвлөгөө болон API

API түлхүүрүүд, OAuth клиентүүд, вебхүүкүүд, MCP сервер нь төлөвлөгөөний API эрхэд хамаарах бөгөөд бүх стандарт төлөвлөгөөд үүнийг агуулдаг. Үүнгүй төлөвлөгөөд түлхүүр, клиент эсвэл захиалга үүсгэхэд татгалзаж, REST бичлэг болон MCP холболтуудыг татгалзах бөгөөд REST унших үргэлжлэн ажиллаж, өгөгдөл экспортлох боломжтой хэвээр үлдэнэ. Татгалз нь commerce.plan_entitlement кодтой, precondition ангийн асуудлын баримт бичиг юм.

Өргөтгөлүүд

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

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