---
title: "የገንቢ መመሪያ"
description: "የQuire REST API፣ OAuth፣ የድር ማሳወቂያዎች፣ MCP አገልጋይ እና ቅጥያዎች።"
image: "https://docs.quirelms.com/og.png"
---

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

# የገንቢ መመሪያ

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

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

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

## አድራሻዎች <!--quire:addresses-->

እያንዳንዱ ድርጅት የራሱ አድራሻ አለው፤ APIውም በዚያ አድራሻ ስር ይገኛል፦

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

ምስክርነቱ ድርጅቱን ይወስናል። የአንድ ድርጅት ቁልፍን በሌላ ድርጅት አድራሻ ላይ ከተጠቀሙ ጥያቄው ይከለከላል።

የOpenAPI ሰነዱ በማንኛውም የድርጅት አድራሻ ላይ `/api/v1/openapi.json` ይገኛል፤ ስለዚህ የደንበኛ ኮድ አመንጪዎች ሁልጊዜ እየጠሩት ያለውን ስሪት ያያሉ።

## ማረጋገጫ <!--quire:authentication-->

**የ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`።

<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` እውነት ሲሆን ይቀጥሉ (ምሳሌውን ከታች ይመልከቱ)። 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}}
```

## ስህተቶች <!--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` ለሰዎች የተጻፈ፣ ለእነሱ ማሳየት ደህና የሆነ ጽሑፍ ሲሆን ሊቀየር ይችላል። ያላወቁት ኮድ ሲያጋጥም `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` ይጥቀሱ።

## የድር ማሳወቂያዎች <!--quire:webhooks-->

በ`/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-->

የQuire MCP አገልጋይ በድርጅቱ አድራሻ ላይ `/mcp` ነው፣ በstreamable HTTP ይሰራል። MCP ደንበኛ የOAuth አገልጋዩን ከ`/.well-known/oauth-protected-resource` ያገኛል፤ ሰውየውም እንደማንኛውም 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 ደንበኞች፣ የድር ማሳወቂያዎችና MCP አገልጋይ በዕቅዱ API መብት ስር ናቸው፤ መደበኛ ዕቅዶች ሁሉ ይህን ያካትታሉ። መብቱ በሌለበት ዕቅድ ላይ ቁልፍ፣ ደንበኛ ወይም ደንበኝነት መፍጠር፣ REST ላይ መጻፍና MCP መገናኘት ይከለከላሉ፤ ውሂብ ሊወጣ እንዲችል የREST ንባብ ይቀጥላል። ውድቅ ምላሹ `commerce.plan_entitlement` ኮድ ያለው፣ በ`precondition` ምድብ የተመደበ የችግር ሰነድ ነው።

## ቅጥያዎች <!--quire:extensions-->

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

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

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