ወደ ይዘቱ ዝለል
Quireሰነዶች
አማርኛ

የገንቢ መመሪያ

የQuire REST API፣ OAuth፣ የድር ማሳወቂያዎች፣ MCP አገልጋይ እና ቅጥያዎች።

እንደ Markdown አሳይ

የድርጅትዎን የAPI አድራሻና በተወሰኑ ፈቃዶች የተገደበ ምስክርነት ይጠቀሙ። በንባብ ጥያቄ ይጀምሩ፣ ምላሹን ያረጋግጡ፣ ሚስጥሮችንም ከምንጭ ቁጥጥርና ከሰነድ ምሳሌዎች ውጭ ያቆዩ።

Quire አንድ ይፋዊ API አለው፦ በHTTPS ላይ REST፣ በOpenAPI 3.1 ሰነድ የተገለጸ፤ ለክስተቶች የተፈረሙ የድር ማሳወቂያዎችና ለAI ረዳቶች MCP አገልጋይ አለው። የAPI ማጣቀሻ እያንዳንዱን መጨረሻ ነጥብና ክስተት ይዘረዝራል።

አድራሻዎች

እያንዳንዱ ድርጅት የራሱ አድራሻ አለው፤ 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 ላይ ነው። ወሰን ቶከን ሊያደርገው የሚችለውን ይገድባል፤ ሰውየው ሊያደርገው ከሚችለው በላይ ፈቃድ ፈጽሞ አይሰጥም።

ወሰኖቹ 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 በመጠቀም ይመድቡት፦

ምድብ ሁኔታ ድጋሚ ሙከራ
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 ይጥቀሱ።

የድር ማሳወቂያዎች

በ/admin/webhooks ወይም በAPI በኩል በ/webhook_subscriptions ይመዝገቡ። ክስተቶችን በስማቸው (enrolment.created)፣ በክፍላቸው (enrolment.*) ወይም ሁሉንም (*) ይምረጡ። Quire መጀመሪያ webhook.ping ይልካል፤ የመጨረሻ ነጥብዎ ምላሽ ከሰጠ በኋላ ደንበኝነቱ ይጀምራል።

መላኪያዎች የ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 የተላከውን በቋሚ ጊዜ ያነጻጽሩ። በሚስጥር ሽግግር ወቅት ሁለት ሊኖሩ ይችላሉ፤ ከአንዱ ጋር ከተዛመደ ትክክል ነው።
  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 ደንበኛ የOAuth አገልጋዩን ከ/.well-known/oauth-protected-resource ያገኛል፤ ሰውየውም እንደማንኛውም OAuth ደንበኛ ይገባና ፈቃድ ይሰጣል። መሣሪያዎቹ በዚያ ሰው ፈቃድ ይሰራሉ፤ አጥፊ ድርጊቶች ማረጋገጫ ይጠይቃሉ። አስተዳዳሪዎች በ/admin/integrations/mcp የሚገኙትን መሣሪያዎች ይመርጣሉ።

ዕቅዶችና API

የAPI ቁልፎች፣ OAuth ደንበኞች፣ የድር ማሳወቂያዎችና MCP አገልጋይ በዕቅዱ API መብት ስር ናቸው፤ መደበኛ ዕቅዶች ሁሉ ይህን ያካትታሉ። መብቱ በሌለበት ዕቅድ ላይ ቁልፍ፣ ደንበኛ ወይም ደንበኝነት መፍጠር፣ REST ላይ መጻፍና MCP መገናኘት ይከለከላሉ፤ ውሂብ ሊወጣ እንዲችል የREST ንባብ ይቀጥላል። ውድቅ ምላሹ commerce.plan_entitlement ኮድ ያለው፣ በprecondition ምድብ የተመደበ የችግር ሰነድ ነው።

ቅጥያዎች

የQuire እንቅስቃሴ አይነቶች፣ ብሎኮች፣ የምዝገባ ዘዴዎች፣ የመግቢያ ዘዴዎች፣ የጥያቄ አይነቶች፣ ሪፖርቶች፣ ገጽታዎችና ውህደቶች በራስዎ በሚያስተናግዱት ጭነት ላይ ሊጨመሩ በሚችሉበት ተመሳሳይ የቅጥያ መዝገብ ይገለጻሉ። ቅጥያዎች በኮድ ውስጥ ተጠናቅቀው ይገኛሉ፤ በሩጫ ጊዜ የሚጫን ተሰኪ ማስጫኛ የለም፣ የሚስተናገድ ድርጅትም ሊጨምር አይችልም። አስተዳዳሪዎች በ/admin/extensions ለድርጅታቸው እያንዳንዱን ቅጥያ ያበሩታል ወይም ያጠፉታል (የአስተዳዳሪ መመሪያን ይመልከቱ)።

ቅጥያ ለመጻፍ በpackages/integration/extensions/src/sample.ts ያለውን የምሳሌ ብሎክና ገጽታ ይጀምሩ። የቅጥያ ነጥቡን ይምረጡ፣ ውሉንም በpoints.ts ያንብቡ፤ ከዚያ መለያ፣ ስሪት፣ ፈቃድ፣ የሚያቀርበውና የሚፈልገውን፣ ድርጅት ሊያጠፋው እንደሚችልም ያውጁ። የድር መተግበሪያውና worker ሲዋቀሩ ሁለቱም እንዲስማሙ ይመዝግቡት። መዝገቡ ሲገነባና register በሚጠሩበት ጊዜ የእያንዳንዱን ነጥብ ህጎች ይፈትሻል፤ የማይሰራ ስብስብ ካገኘ ችግሮቹን በሙሉ በመዘርዘር ይከለክለዋል፣ መዝገቡንም እንዳለ ያቆያል። የቅጥያው ሙከራዎች extensionContractProblems ለእሱ ባዶ መሆኑንና ቅጥያውን ሲያጠፉ የሚነካቸው ነገሮች መቀየራቸውን ማረጋገጥ አለባቸው።

ዳሰሳ

ለመፈለግ ይተይቡ…

↑↓ ዳስስ↵ ምረጥEsc ዝጋ