ຂ້າມໄປຫາເນື້ອຫາ
Quireເອກະສານ
ລາວ

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

REST API ຂອງ Quire, OAuth, webhooks, ເຊີບເວີ MCP ແລະ ສ່ວງເສີມ.

ເບິ່ງໃນຮູບແບບ Markdown

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

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

ທີ່ຢູ່

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

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

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

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

ການຢືນຢັນຕົວຕະຫຼາດ

ກະແຈ 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.

ຄຳຮ້ອງຂໍ

  • ການແບ່ງໜ້າ: ລາຍການທຸກໆລາຍການແບ່ງໜ້າດ້ວຍ 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}}

ຂໍ້ຜິດພາດ

ຂໍ້ຜິດພາດທຸກໆອັນແມ່ນເອກະສານບັນຫາ 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

ຈະລົງທະບຽນທີ່ /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

ເຊີບເວີ MCP ຂອງ Quire ຢູ່ທີ່ /mcp ຢູ່ທີ່ຢູ່ຂອງອົງການ ໂດຍຜ່ານ HTTP ທີ່ສາມາດ ສົ່ງຕໍ່ສະຕຣີມໄດ້. client MCP ຄົ້ນພົບເຊີບເວີ OAuth ຈາກ /.well-known/oauth-protected-resource ແລະ ຄົນຈະເຂົ້າສູ່ລະບົບ ແລະ ຍອມຮັບເຊັ່ນດຽວກັນກັບ client OAuth ໃດກໍ່ໄດ້. ເຄື່ອງມືດຳເນີນການໃນນາມຄົນນັ້ນ ພ້ອມສິດຂອງພວກເຂົາ ແລະ ເຄື່ອງມືທີ່ທຳລາຍ ຂໍການຢືນຢັນ. ຜູ້ບໍລິຫານເລືອກວ່າເຄື່ອງມືໃດມີໃຫ້ໃຊ້ທີ່ /admin/integrations/mcp.

ແຜນການ ແລະ API

ກະແຈ API, ລູກຄ້າ OAuth, webhooks ແລະ ເຊີບເວີ MCP ຂຶ້ນກັບສິດໃຊ້ API ຂອງແຜນ ແລະ ແຜນມາດຕະຖານທຸກແຜນລວມເອົາມັນ. ໃນແຜນທີ່ບໍ່ມີມັນ ການສ້າງກະແຈ, client ຫຼື ການຈະລົງທະບຽນຈະຖືກປະຕິເສດ, ການຂຽນ REST ແລະ ການເຊື່ອມຕໍ່ MCP ຈະຖືກປະຕິເສດ ແລະ ການອ່ານ REST ຍັງດຳເນີນຕໍ່ໄປເພື່ອໃຫ້ຂໍ້ມູນຍັງສາມາດ ສົ່ງອອກໄດ້. ການປະຕິເສດແມ່ນເອກະສານບັນຫາທີ່ມີ code commerce.plan_entitlement ໃນກຸ້ມ precondition.

ສ່ວງເສີມ

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

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

ການນຳທາງ

ພິມເພື່ອຄົ້ນຫາ…

↑↓ ນຳທາງ↵ ເລືອກEsc ປິດ