រំលងទៅមាតិកា
Quireឯកសារ
ខ្មែរ

មគ្គុទ្ទេសអ្នកអភិវឌ្ឍ

REST API របស់ Quire, OAuth, webhooks, ម៉ាស៊ីនបម្រើ MCP និងផ្នែកបន្ថែម។

មើលជា Markdown

ប្រើអាសយដ្ឋាន API របស់អង្គការអ្នក និងលិខិតសម្គាល់ដែលកំណត់វិស័យ។ ចាប់ផ្តើមជាមួយសំណើអាន ពិនិត្យការឆ្លើយតប ហើយរក្សាគន្លឹះសម្ងាត់នៅក្រៅការត្រួតពិនិត្យប្រព័ន្ធផ្សព្វផ្សាយ និងឧទាហរណ៍ក្នុងឯកសារ។

Quire មាន API សាធារណៈមួយ៖ REST តាម HTTPS ដែលពិពណ៌នាដោយឯកសារ OpenAPI 3.1 ជាមួយ webhooks ដែលមានហត្ថលេខាសម្រាប់ព្រឹត្តិការណ៍ និងម៉ាស៊ីនបម្រើ MCP សម្រាប់ជំនួយការ AI។ ឯកសារយោង API រាយចំណុចបញ្ចប់ និងព្រឹត្តិការណ៍ទាំងអស់។

អាសយដ្ឋាន

អង្គការនីមួយៗមានអាសយដ្ឋានផ្ទាល់ខ្លួន ហើយ API ស្ថិតនៅក្រោមវា៖

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

លិខិតសម្គាល់កំណត់អង្គការ។ សោសម្រាប់អង្គការមួយដែលប្រើនៅអាសយដ្ឋានអង្គការផ្សេងត្រូវបានបដិសេធ។

ឯកសារ OpenAPI ត្រូវបានបម្រើនៅ /api/v1/openapi.json លើអាសយដ្ឋានអង្គការណាមួយ ដូច្នេះឧបករណ៍បង្កើតកូឌូអស់តែងឃើញកំណែដែលអ្នកកំពុងហៅ។

ការផ្ទៀងផ្ទាត់

សោ 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។

The API keys page with one key, the person it acts as, its scopes and its status, and a form to create another.
API keys list who each key acts as and what it may reach.

សំណើ

  • ការបំបែកទំព័រ៖ បញ្ជីទាំងអស់បំបែកទំព័រដោយ 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-Key លើ POST, PATCH និង DELETE។ ការសាកល្បងឡើងវិញជាមួយសោដដែលត្រឡប់ការឆ្លើយតបដំបូងជំនួសការធ្វើការងារពីរដង។ ចំណុចបញ្ចប់បរិមាណតម្រូវឱ្យមានវា។
  • កំណែ៖ កំណែសំខាន់ស្ថិតក្នុងផ្លូវ (/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៖

ប្រភេទ ស្ថានភាព សាកឡើងវិញ
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 ជាមុនសិន ការចុះឈ្មោះចាប់ផ្តើមនៅពេលចំណុចបញ្ចប់របស់អ្នកឆ្លើយតបវា។

ការផ្ញើធ្វើតាមសេចក្តីជំនួយការ 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. បដិសេធពេលវេលាដែលខុសគ្នាច្រើនជាងប្រាំនាទីពីនាឡិការបស់អ្នក។
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៖ ការផ្ញើមួយអាចមកដល់ច្រើនដង។ ខ្លឹមសារផ្ទុកអត្តសញ្ញាណ និងសេចក្តីសង្ខេបខ្លី ទាញយកធនធានសម្រាប់សភាពបច្ចុប្បន្នរបស់វា។ ការផ្ញើដែលបរាជ័យត្រូវបានសាកឡើងវិញជាមួយ backoff រហូតដល់ 72 ម៉ោង ហើយអាចលេងឡើងវិញបានពីកំណត់ត្រាការផ្ញើ។

MCP

ម៉ាស៊ីនបម្រើ MCP របស់ Quire ស្ថិតនៅ /mcp លើអាសយដ្ឋានអង្គការ តាម HTTP ដែលអាចផ្សាយបាន។ អតិថិជន MCP រកឃើញម៉ាស៊ីនបម្រើ OAuth ពី /.well-known/oauth-protected-resource ហើយមនុស្សនោះចូល និងយល់ព្រមដូចជាជាមួយអតិថិជន OAuth ណាមួយ។ ឧបករណ៍ធ្វើសកម្មភាពជាមនុស្សនោះ ជាមួយសិទ្ធីរបស់ពួកគេ ហើយឧបករណ៍ដែលបំផ្លាញសុំការបញ្ជាក់។ អ្នកគ្រប់គ្រងជ្រើសរើសថាឧបករណ៍ណាដែលអាចប្រើបាននៅ /admin/integrations/mcp។

The AI assistants page with the server address to give an assistant and a table of the tools it can use.
AI assistants (MCP): the server address, and the tools an assistant may call.

ផែនការ និង API

សោ API អតិថិជន OAuth webhooks និងម៉ាស៊ីនបម្រើ MCP ស្ថិតក្នុងសិទ្ធិ API របស់ផែនការ ហើយផែនការស្តង់ដារនីមួយៗរួមបញ្ចូលវា។ លើផែនការដែលគ្មានវា ការបង្កើតសោ អតិថិជន ឬការចុះឈ្មោះត្រូវបានបដិសេធ ការសរសេរ REST និងការតភ្ជាប់ MCP ត្រូវបានបដិសេធ ហើយការអាន REST នៅតែដំណើរការដូច្នេះទិន្នន័យនៅអាចនាំចេញបាន។ ការបដិសេធជាឯកសារបញ្ហាជាមួយកូដ commerce.plan_entitlement ក្នុងប្រភេទ precondition។

ផ្នែកបន្ថែម

ប្រភេទសកម្មភាពផ្ទាល់របស់ Quire ប្លុក វិធីចុះឈ្មោះ វិធីចូល ប្រភេទសំណួរ របាយការណ៍ រចនាបថ និងការរួមបញ្ចូល ត្រូវបានប្រកាសតាមបញ្ជីផ្នែកបន្ថែមដដែលដែលការដំឡើងដោយខ្លួនឯងអាចបន្ថែម។ ផ្នែកបន្ថែមត្រូវបានកូឌូរ៖ គ្មាកម្មវិធីរត់ផ្ទុក plugin ទេ ហើយអង្គការដែល hosting មិនអាចបន្ថែមមួយបានទេ។ អ្នកគ្រប់គ្រងបិត ឬបើកផ្នែកបន្ថែមនីមួយៗសម្រាប់អង្គការរបស់ពួកគេនៅ /admin/extensions (សូមមើលមគ្គុទ្ទេសអ្នកគ្រប់គ្រង)។

ដើម្បីសរសេរមួយ ចាប់ផ្តើមពីប្លុក និងរចនាបថគំរូនៅក្នុង packages/integration/extensions/src/sample.ts។ ជ្រើសរើសចំណុចផ្នែកបន្ថែម ហើយអានកិច្ចសន្យារបស់វានៅ points.ts រួចប្រកាសផ្នែកបន្ថែមជាមួយ id កំណែអាជ្ញាប័ណ្ណ អ្វីដែលវាផ្តល់ និងទាមទារ និងថាតើអង្គការអាចបិតវាបានឬអត់។ ចុះឈ្មោះវានៅកន្លែងដែលកម្មវិធី web និង worker ត្រូវបានបង្កើតឡើង ដូច្នេះទាំងពីរយល់ស្របគ្នា។ បញ្ជីពិនិត្យច្បាប់ផ្ទាល់របស់ចំណុចនីមួយៗនៅពេលវាត្រូវបានសង់ ហើយនៅពេលអ្នកហៅ register បដិសេធបញ្ជីដែលនឹងមិនត្រឹមត្រូវដោយដាក់ឈ្មោះបញ្ហាទាំងអស់ ហើយទុកបញ្ជីមិនផ្លាស់ប្តូរនៅពេលវាធ្វើដូច្នេះ។ ការសាកល្បងផ្ទាល់របស់ផ្នែកបន្ថែមគួរតែអះអាងថា extensionContractProblems ទទេសម្រាប់វា ហើយការបិតវាផ្លាស់ប្តូរអ្វីដែលវាប៉ះពាល់។

ការរុករក

វាយដើម្បីស្វែងរក…

↑↓ រុករក↵ ជ្រើសរើសEsc បិទ