ဆော့ဖ်ဝဲရေးသားသူလမ်းညွှန်

သင့်အဖွဲ့အစည်း၏ API လိပ်စာနှင့် နယ်ပယ်သတ်မှတ်ထားသောအထောက်အထားကို အသုံးပြုပါ။ ဖတ်ရှုတောင်းဆိုမှုဖြင့် စတင်ပါ၊ တုံ့ပြန်မှုကို စစ်ဆေးပါ၊ လျှို့ဝှက်ချက်များကို ရင်းမြစ်ထိန်းချုပ်မှုနှင့် စာရွက်စာတမ်းနမူနာများအပြင်တွင် ထားပါ။

Quire တွင် အများသုံး API တစ်ခု ရှိသည်– HTTPS ပေါ်မှ REST၊ OpenAPI 3.1 စာရွက်စာတမ်းဖြင့် ဖော်ပြထားသော၊ ဖြစ်ရပ်များအတွက် လက်မှတ်ထိုးထားသော webhook များ၊ AI လက်ထောက်များအတွက် MCP ဆာဗာနှင့်အတူ။ API အကိုးအကား က endpoint တိုင်းနှင့် ဖြစ်ရပ်တိုင်း စာရင်းပြုစုသည်။

လိပ်စာများ

အဖွဲ့အစည်းတစ်ခုစီတွင် ၎င်း၏ကိုယ်ပိုင်လိပ်စာ ရှိသည်၊ API က ၎င်းအောက်တွင် နေသည်–

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

အထောက်အထားက အဖွဲ့အစည်းကို ဆုံးဖြတ်သည်။ အဖွဲ့အစည်းတစ်ခုအတွက် သော့ကို အခြားတစ်ခု၏လိပ်စာတွင် အသုံးပြုပါက ငြင်းပယ်သည်။

OpenAPI စာရွက်စာတမ်းကို အဖွဲ့အစည်းမဆိုလိပ်စာရှိ /api/v1/openapi.json တွင် ဝန်ဆောင်မှုပေးသည်၊ ထို့ကြောင့် client ထုတ်လုပ်သူများ သင်ခေါ်နေသောဗားရှင်းကို အမြဲမြင်သည်။

စစ်မှန်ကြောင်းအတည်ပြုခြင်း

API သော့များ က script များနှင့် ဆာဗာမှဆာဗာသို့ ချိတ်ဆက်မှုများအတွက်ဖြစ်သည်။ စီမံခန့်ခွဲသူတစ်ဦးက /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 တွင် client တစ်ခု မှတ်ပုံတင်ပြီး၊ ထို့နောက် PKCE ပါသော ခွင့်ပြုချက်ကုဒ်စီးဆင်းမှု (/oauth/authorize၊ /oauth/token)၊ သို့မဟုတ် စက်အတွက် client အထောက်အထားများကို အသုံးပြုပါ။ ရှာဖွေတွေ့ရှိမှုက /.well-known/oauth-authorization-server တွင် ရှိသည်။ နယ်ပယ်တစ်ခုက တိုကင်လုပ်နိုင်သည့်အရာကို ကျဉ်းစေသည်။ လူ လုပ်နိုင်သည်ထက် ပို၍ ဘယ်တော့မှ ခွင့်မပြုပါ။

နယ်ပယ်များက 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 မှန်နေသရွေ့ ပေးပါ (အောက်၌ နမူနာ)။ 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 အပေါ် အုပ်စုဖွဲ့ပါ–

အကူအညီထံ ဆက်သွယ်သည့်အခါ request_id ကို ကိုးကားပါ။

Webhook များ

/admin/webhooks တွင် စာရင်းသွင်းပါ၊ သို့မဟုတ် /webhook_subscriptions ရှိ API မှတစ်ဆင့်။ ဖြစ်ရပ်များကို အမည်ဖြင့် (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. လက်ခံရရှိသော byte အတိအကျမှ {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 ဖြင့် ထပ်ပွားမှုဖယ်ပါ– ပို့ဆောင်မှုတစ်ခု တစ်ကြိမ်ထက်ပို ရောက်နိုင်သည်။ ကိုယ်ထည်က အမှတ်အသားများနှင့် အကျဉ်းချုပ်တို သယ်ဆောင်သည်။ ၎င်း၏လက်ရှိအခြေအနေအတွက် အရင်းအမြစ်ကို ရယူပါ။ မအောင်သောပို့ဆောင်မှုများကို ၇၂ နာရီအထိ နောက်ပြန်ဆုတ်ရင်း ထပ်ကြိုးစားပြီး၊ ပို့ဆောင်မှုမှတ်တမ်းမှ ပြန်ဖွင့်နိုင်သည်။

MCP

Quire ၏ MCP ဆာဗာက အဖွဲ့အစည်း၏လိပ်စာရှိ /mcp တွင်၊ streamable HTTP မှတစ်ဆင့် ရှိသည်။ MCP client တစ်ခုက /.well-known/oauth-protected-resource မှ OAuth ဆာဗာကို ရှာဖွေတွေ့ရှိပြီး၊ လူက မည်သည့် OAuth client ကဲ့သို့မဆို လက်မှတ်ထိုးဝင်သဘောတူသည်။ ကိရိယာများက ထိုလူအဖြစ်၊ ၎င်းတို့၏ခွင့်ပြုချက်များဖြင့် လုပ်ဆောင်သည်၊ ဖျက်ဆီးသောကိရိယာများ အတည်ပြုချက် တောင်းသည်။ စီမံခန့်ခွဲသူများက /admin/integrations/mcp တွင် မည်သည့်ကိရိယာများ ရနိုင်သည်ကို ရွေးသည်။

အစီအစဉ်များနှင့် API

API သော့များ၊ OAuth client များ၊ webhook များနှင့် MCP ဆာဗာက အစီအစဉ်၏ API ရပိုင်ခွင့်မှ ဖြစ်သည်၊ စံအစီအစဉ်တိုင်း ၎င်းကို ပါဝင်သည်။ ၎င်းမပါသောအစီအစဉ်တွင် သော့၊ client သို့မဟုတ် စာရင်းသွင်းမှု ဖန်တီးခြင်းကို ငြင်းပယ်သည်၊ REST ရေးမှုများနှင့် MCP ချိတ်ဆက်မှုများကို ငြင်းပယ်သည်၊ REST ဖတ်မှုများ ဆက်အလုပ်လုပ်သောကြောင့် ဒေတာ ထုတ်ယူနိုင်ဆက်ရှိနေသည်။ ငြင်းပယ်မှုက commerce.plan_entitlement ကုဒ်ပါသော ပြဿနာစာရွက်စာတမ်း ဖြစ်သည်၊ precondition အမျိုးအစားတွင်။

တိုးချဲ့မှုများ

Quire ၏ကိုယ်ပိုင်လှုပ်ရှားမှုအမျိုးအစားများ၊ အကွက်များ၊ စာရင်းသွင်းနည်းများ၊ လက်မှတ်ထိုးဝင်နည်းများ၊ မေးခွန်းအမျိုးအစားများ၊ အစီရင်ခံစာများ၊ အပြင်အဆင်များနှင့် ချိတ်ဆက်မှုများကို ကိုယ်တိုင်လက်ခံသောတပ်ဆင်မှု ထပ်ထည့်နိုင်သော တူညီသောတိုးချဲ့မှုမှတ်ပုံတင်ခြင်းမှတစ်ဆင့် ကြေညာသည်။ တိုးချဲ့မှုများကို အတွင်း၌ ကွန်ပိုင်းလုပ်ထားသည်– runtime ပလပ်အင်ထည့်စက် မရှိပါ၊ လက်ခံပေးထားသောအဖွဲ့အစည်းက တစ်ခုကို ထည့်နိုင်၍မရပါ။ စီမံခန့်ခွဲသူများက /admin/extensions တွင် ၎င်းတို့အဖွဲ့အစည်းအတွက် တိုးချဲ့မှုတစ်ခုစီ ဖွင့် သို့မဟုတ် ပိတ်သည် (စီမံခန့်ခွဲသူလမ်းညွှန် ကို ကြည့်ပါ)။

တစ်ခုကို ရေးရန် packages/integration/extensions/src/sample.ts ရှိ နမူနာအကွက်နှင့် အပြင်အဆင်မှ စတင်ပါ။ တိုးချဲ့မှုအမှတ်ကို ရွေးပြီး points.ts တွင် ၎င်း၏စာချုပ် ဖတ်ပါ၊ ထို့နောက် တိုးချဲ့မှုကို id တစ်ခု၊ ဗားရှင်းတစ်ခု၊ လိုင်စင်တစ်ခု၊ ၎င်းပေးသည့်အရာနှင့် လိုအပ်သည့်အရာ၊ အဖွဲ့အစည်းတစ်ခု ၎င်းကို ပိတ်နိုင်သလားနှင့်အတူ ကြေညာပါ။ ဝဘ်အက်ပလီကေးရှင်းနှင့် worker တို့ ဖွဲ့စည်းသည့်နေရာတွင် ၎င်းကို မှတ်ပုံတင်ပါ၊ နှစ်ဖက်စလုံး သဘောတူစေရန်။ မှတ်ပုံတင်ခြင်းက တည်ဆောက်သည့်အခါ အမှတ်တစ်ခုစီ၏ကိုယ်ပိုင်စည်းမျဉ်းများ စစ်ဆေးပြီး register ကို ခေါ်တိုင်း၊ မမှန်ကန်မည့်အစုကို ပြဿနာတိုင်း အမည်ပေး၍ ငြင်းပယ်ပြီး၊ ထိုသို့လုပ်သည့်အခါ မှတ်ပုံတင်ခြင်း မပြောင်းလဲဘဲ ထားသည်။ တိုးချဲ့မှု၏ကိုယ်ပိုင်စမ်းသပ်မှုများက ၎င်းအတွက် extensionContractProblems အလွတ်ဖြစ်သည်နှင့် ၎င်းကို ပိတ်ခြင်းက ၎င်းသက်ရောက်သည့်အရာကို ပြောင်းသည်ဟု အခိုင်အမာဆိုသင့်သည်။