---
title: "ຄູ່ມານຳນັກພັດທະນາ"
description: "REST API ຂອງ Quire, OAuth, webhooks, ເຊີບເວີ MCP ແລະ ສ່ວງເສີມ."
image: "https://docs.quirelms.com/og.png"
---

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

# ຄູ່ມານຳນັກພັດທະນາ

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

ໃຊ້ທີ່ຢູ່ API ຂອງອົງການຂອງທ່ານ ແລະ ລະຫັດເຂົ້າເຖິງທີ່ມີ scope. ເລີ່ມດ້ວຍຄຳຮ້ອງຂໍ
ການອ່ານ, ກວດສອບການຕອບກັບ, ແລະ ເກັບຄວາມລັບໄວ້ນອກການຄວບຄຸມລະຫັດແຫຼ່ງ
ແລະ ຕົວຢ່າງໃນເອກະສານ.

Quire ມີ API ພາສນອກໜຶ່ງດຽວ: REST ເທິງ HTTPS, ອະທິບາຍໂດຍເອກະສານ OpenAPI 3.1,
ພ້ອມ webhook ທີ່ມີລາຍລານື້ສຳລັບເຫດການ ແລະ ເຊີບເວີ MCP ສຳລັບຜູ້ຊ່ວຍ AI.
[ຄູ່ມາດ API](https://docs.quirelms.com/api/) ລາຍຊື່ທຸກ endpoint ແລະ ເຫດການ.

## ທີ່ຢູ່ <!--quire:addresses-->

ແຕ່ລະອົງການມີທີ່ຢູ່ຂອງຕົນເອງ ແລະ API ຢູ່ພາຍໃຕ້ມັນ:

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

ລະຫັດເຂົ້າເຖິງເປັນຕົວກຳນົດອົງການ. ກະແຈສຳລັບອົງການໜຶ່ງທີ່ຖືກນຳໄຊ້ຢູ່ທີ່ຢູ່
ຂອງອົງການອື່ນຈະຖືກປະຕິເສດ.

ເອກະສານ OpenAPI ຖືກບໍລິການທີ່ `/api/v1/openapi.json` ຢູ່ທີ່ຢູ່ຂອງອົງການໃດກໍ່ໄດ້
ດັ່ງນັ້ນເຄື່ອງສ້າງ client ຈະເຫັນເວີຊັນທີ່ທ່ານເອີ້ນຢູ່ສະເໝີ.

## ການຢືນຢັນຕົວຕະຫຼາດ <!--quire:authentication-->

**ກະແຈ API** ສຳລັບສຄຣິບ ແລະ ການເຊື່ອມຕໍ່ລະຫວ່າງເຊີບເວີກັບເຊີບເວີ. ຜູ້ບໍລິຫານ
ສ້າງກະແຈໜຶ່ງທີ່ `/admin/integrations/api-keys`, ເລືອກ scope ຂອງມັນ ແລະ ເຫັນມັນ
ຄັ້ງດຽວ. ສົ່ງມັນເປັນ bearer token:

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

ກະແຈເລີ່ມດ້ວຍ `qk_live_` ຫຼື `qk_test_`. ມອບກະແຈຂອງຕົນໃຫ້ແຕ່ລະການເຊື່ອມຕໍ່.

**OAuth 2.1** ສຳລັບແອັບທີ່ດຳເນີນການໃນນາມຄົນທີ່ເຂົ້າສູ່ລະບົບ. ລົງທະບຽນ client
ຜ່ານ `/admin/integrations/oauth-clients` ຈາກນັ້ນໃຊ້ຂະບວນການ authorization code
ກັບ PKCE (`/oauth/authorize`, `/oauth/token`) ຫຼື client credentials ສຳລັບ client
ເຄື່ອງຈັກ. ການຄົ້ນພົບຢູ່ທີ່ `/.well-known/oauth-authorization-server`.
Scope ກຳກັດສິ່ງທີ່ token ສາມາດເຮັດໄດ້; ມັນບໍ່ເຄີຍອະນຸຍາດໃຫ້ມັນເຮັດຫຼາຍກວ່າ
ທີ່ຄົນນັ້ນສາມາດເຮັດ.

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-->

- **ການແບ່ງໜ້າ**: ລາຍການທຸກໆລາຍການແບ່ງໜ້າດ້ວຍ cursor. ສົ່ງ `limit` ຈາກນັ້ນສົ່ງ
  `next_cursor` ຈາກ `page` ເປັນ `cursor` ໃນຂະນະທີ່ `has_more` ເປັນ true
  (ຕົວຢ່າງຂ້າງລຸ່ມ). ບໍ່ມີ offset.
- **ການປ່ຽນແປງນັບແຕ່**: `updated_since` ຄືບ້ານສິ່ງທີ່ປ່ຽນແປງຫຼັງຈາກເວລາໜຶ່ງ.
  ນຳມັນຄຽງຄູ່ກັບ `include_deleted=true` ຫຼື ອ່ານ `/<resource>/deletions`
  ເພື່ອຮູ້ວ່າສິ່ງໃດຖືກລຶບອອກ.
- **ຕົວລະບຸພາຍນອກ**: ຊັບພະຍາກອນສ່ວນຫຼາຍຮັບ `external_id` ຂອງທ່ານເອງ
  ແລະ `/<resource>/ext:{external_id}` ຈະອ່ານຫຼື upsert ດ້ວຍມັນ ດັ່ງນັ້ນ
  ການຊິງບໍ່ເຄີຍຈຳເປັນເກັບຕົວລະບຸຂອງ Quire.
- **Idempotency**: ສົ່ງຫົວໜ້າ `Idempotency-Key` ໃສ່ `POST`, `PATCH` ແລະ `DELETE`.
  ການລອງຄືນດ້ວຍກະແຈດຽວກັນຈະຄືບ້ານການຕອບຄັ້ງທຳອິດແທນທີ່ຈະເຮັດງານ
  ສອງຄັ້ງ. Endpoint ແບບກຸ້ມຈຳເປັນຕ້ອງການມັນ.
- **ເວີຊັນ**: ເວີຊັນສ່ວນໃຫຍ່ຢູ່ໃນເສັ້ນທາງ (`/v1`). ພາຍໃນມັນ ການປ່ຽນແປງທີ່ຫັກ
  ກັບມັນແມ່ນ revision ທີ່ມີວັນທີ ເລືອກດ້ວຍຫົວໜ້າ `Quire-Version`,
  ຕົວຢ່າງ `Quire-Version: 2026-09-20`. ບໍ່ມີຫົວໜ້ານັ້ນ ທ່ານຈະໄດ້ revision
  ປະຈຸບັນທີ່ລະຫັດເຂົ້າເຖິງຂອງທ່ານຖືກອອກໃຫ້.

ໜ້າໜຶ່ງຂອງລາຍການ:

```
{"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` ຂຽນສຳລັບຄົນ ປອດໄພທີ່ຈະ
ສະແດງໃຫ້ພວກເຂົາ ແລະ ອາດປ່ຽນແປງ. ເມື່ອທ່ານບໍ່ຮູ້ຈັກ code ໜຶ່ງ ແບ່ງກຸ່ມຕາມ
`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` ເມື່ອທ່ານຕິດຕໍ່ຝ່າຍສະໜັບສະໜູນ.

## Webhooks <!--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. ສ້າງສະຕຣິງ `{webhook-id}.{webhook-timestamp}.{raw body}` ຈາກໄບຕໍທີ່ໄດ້ຮັບ
   ຢ່າງແນ່ນອນ ກ່ອນການວິເຄາະ JSON ໃດໆ.
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-->

ເຊີບເວີ MCP ຂອງ Quire ຢູ່ທີ່ `/mcp` ຢູ່ທີ່ຢູ່ຂອງອົງການ ໂດຍຜ່ານ HTTP ທີ່ສາມາດ
ສົ່ງຕໍ່ສະຕຣີມໄດ້. client MCP ຄົ້ນພົບເຊີບເວີ OAuth ຈາກ `/.well-known/oauth-protected-resource`
ແລະ ຄົນຈະເຂົ້າສູ່ລະບົບ ແລະ ຍອມຮັບເຊັ່ນດຽວກັນກັບ client 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, webhooks ແລະ ເຊີບເວີ MCP ຂຶ້ນກັບສິດໃຊ້ API ຂອງແຜນ
ແລະ ແຜນມາດຕະຖານທຸກແຜນລວມເອົາມັນ. ໃນແຜນທີ່ບໍ່ມີມັນ ການສ້າງກະແຈ, client
ຫຼື ການຈະລົງທະບຽນຈະຖືກປະຕິເສດ, ການຂຽນ REST ແລະ ການເຊື່ອມຕໍ່ MCP
ຈະຖືກປະຕິເສດ ແລະ ການອ່ານ REST ຍັງດຳເນີນຕໍ່ໄປເພື່ອໃຫ້ຂໍ້ມູນຍັງສາມາດ
ສົ່ງອອກໄດ້. ການປະຕິເສດແມ່ນເອກະສານບັນຫາທີ່ມີ code `commerce.plan_entitlement`
ໃນກຸ້ມ `precondition`.

## ສ່ວງເສີມ <!--quire:extensions-->

ປະເພດກິດຈະກຳ, ບລັອກ, ວິທີຮັບເຂົ້າຮຽນ, ວິທີເຂົ້າສູ່ລະບົບ, ປະເພດຄຳຖາມ,
ລາຍງານ, ພື້ນຫຼັງ ແລະ ການເຊື່ອມຕໍ່ຂອງ Quire ເອງຖືກປະກາດຜ່ານຖານລົງທະບຽນ
ສ່ວງເສີມດຽວກັນທີ່ການຕິດຕັ້ງຕິດຕັ້ງເອງສາມາດເພີ່ມເຂົ້າໄດ້. ສ່ວງເສີມຖືກ
ປະມວນຜົນລວມເຂົ້າແລ້ວ: ບໍ່ມີຕົວໂຫຼດ plugin ໃນເວລາຮັບໃຊ້ງານ ແລະ ອົງການ
ທີ່ເປັນເຈົ້າຂອງບໍລິການບໍ່ສາມາດເພີ່ມໜຶ່ງໄດ້. ຜູ້ບໍລິຫານສະຫຼັບສ່ວງເສີມແຕ່ລະອັນ
ເປີດ ຫຼື ປິດສຳລັບອົງການຂອງພວກເຂົາທີ່ `/admin/extensions` (ເບິ່ງ
[ຄູ່ມານຳຜູ້ບໍລິຫານ](/lo/admin/extensions/)).

ເພື່ອຂຽນໜຶ່ງອັນ ເລີ່ມຈາກບລັອກຕົວຢ່າງ ແລະ ພື້ນຫຼັງຕົວຢ່າງໃນ
`packages/integration/extensions/src/sample.ts`. ເລືອກຈຸດສ່ວງເສີມ ແລະ ອ່ານ
ສັນຍາຂອງມັນໃນ `points.ts` ຈາກນັ້ນປະກາດສ່ວງເສີມພ້ອມ id, ເວີຊັນ, ລິເບນສ,
ສິ່ງທີ່ມັນໃຫ້ ແລະ ຕ້ອງການ, ແລະ ວ່າອົງການສາມາດປິດມັນໄດ້ຫຼືບໍ່. ລົງທະບຽນ
ມັນໃນບ່ອນທີ່ແອັບເວັບ ແລະ worker ຖືກປະກອບເຂົ້າກັນ ເພື່ອໃຫ້ທັງສອງຕົກລົງກັນ.
ຖານລົງທະບຽນກວດສອບກົດລະບຽບຂອງແຕ່ລະຈຸດເມື່ອມັນຖືກສ້າງ ແລະ ທຸກໆຄັ້ງທີ່
ທ່ານເອີ້ນ `register`, ປະຕິເສດຊຸດທີ່ຈະບໍ່ຖືກຕ້ອງພ້ອມບັນທຶກບັນຫາທຸກໆອັນ
ແລະ ປ່ອຍຖານລົງທະບຽນໄວ້ບໍ່ປ່ຽນແປງເມື່ອມັນເຮັດດັ່ງນັ້ນ. ການທົດສອບຂອງ
ສ່ວງເສີມເອງຄວນຢືນຢັນວ່າ `extensionContractProblems` ວ່າງເປົ່າສຳລັບມັນ
ແລະ ວ່າການປິດມັນປ່ຽນສິ່ງທີ່ມັນສົ່ງຜົນກະທົບ.

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