---
title: "ڕێنمایی پەرەپێدەر"
description: "REST APIی Quire، OAuth، webhookەکان، ڕاژەکاری MCP و زیادکراوەکان."
image: "https://docs.quirelms.com/og.png"
---

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

# ڕێنمایی پەرەپێدەر

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

ناونیشانی APIی دامەزراوەکەت و زانیاریی نهێنیی سنووردار بەکاربهێنە. بە داواکارییەکی خوێندنەوە دەست پێ بکە، وەڵامەکە بپشکنە و نهێنییەکان لە سەرچاوەکۆد و نموونەکانی بەڵگەنامە دوور بهێڵەوە.

Quire یەک APIی گشتی هەیە: REST لەسەر HTTPS، کە بە بەڵگەنامەی OpenAPI 3.1 وەسف کراوە؛ لەگەڵ webhookی واژۆکراو بۆ ڕووداوەکان و ڕاژەکاری MCP بۆ یاریدەدەرانی AI. [سەرچاوەی API](https://docs.quirelms.com/api/) هەموو خاڵەکانی کۆتایی و ڕووداوەکان لیست دەکات.

## ناونیشانەکان <!--quire:addresses-->

هەر دامەزراوەیەک ناونیشانی تایبەتی خۆی هەیە، و API لە ژێری کار دەکات:

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

زانیاریی نهێنی دامەزراوەکە دیاری دەکات. کلیلێک بۆ دامەزراوەیەک لە ناونیشانی دامەزراوەیەکی تر بەکاربهێنرێت ڕەت دەکرێتەوە.

بەڵگەنامەی OpenAPI لە هەر ناونیشانی دامەزراوەیەکدا لە `/api/v1/openapi.json` پێشکەش دەکرێت، بۆیە دروستکەرەکانی کڕیار هەمیشە وەشانی ئەو APIیە دەبینن کە پەیوەندییان پێوە کردووە.

## پشتڕاستکردنەوە <!--quire:authentication-->

**کلیلەکانی API** بۆ سکریپت و یەکخستنی ڕاژە بۆ ڕاژەن. بەڕێوەبەر لە `/admin/integrations/api-keys` یەکێک دروست دەکات، سنوورەکانی هەڵدەبژێرێت و تەنها یەک جار دەیبینێت. وەک tokenی 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`ە. سنوورێک دەسەڵاتی token کەم دەکاتەوە؛ هەرگیز نایگەیەنێت بەوەی کەسەکە خۆی نەتوانێت بیکات.

سنوورەکان `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}` بەو ناسێنەرەوە دەیخوێنێتەوە یان نوێی دەکاتەوە، بۆیە هاوکاتکردن پێویستی بە هەڵگرتنی ناسێنەرەکانی Quire نییە.
- **Idempotency**: لە سەرچێی `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` بڵێ.

## Webhookەکان <!--quire:webhooks-->

لە `/admin/webhooks` یان لە ڕێگەی API لە `/webhook_subscriptions` خۆتۆمار بکە. ڕووداوەکان بە ناو هەڵبژێرە (`enrolment.created`)، بە ناوچە (`enrolment.*`) یان هەموویان (`*`). سەرەتا Quire، `webhook.ping` دەنێرێت؛ subscription تەنها کاتێک دەست پێ دەکات کە خاڵی کۆتاییی تۆ وەڵامی بداتەوە.

گواستنەوەکان بەپێی پێوەری 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. بە نهێنیی subscription لەسەری 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 <!--quire:mcp-->

ڕاژەکاری MCPی Quire لە `/mcp` لەسەر ناونیشانی دامەزراوەکە و بە 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، webhookەکان و ڕاژەکاری MCP سەر بە مافی APIی پلانن، و هەر پلانی ئاسایی ئەو مافەی تێدایە. لە پلانێک کە ئەو مافەی نییە، دروستکردنی کلیل، کڕیار یان subscription ڕەت دەکرێتەوە، نووسینەکانی REST و پەیوەندی MCP ڕەت دەکرێنەوە، بەڵام خوێندنەوەکانی REST بەردەوام دەبن بۆ ئەوەی داتا هەناردە بکرێت. ڕەتکردنەوەکە بەڵگەنامەی کێشەیە لەگەڵ کۆدی `commerce.plan_entitlement` لە پۆلی `precondition`.

## زیادکراوەکان <!--quire:extensions-->

جۆرە ناوخۆییەکانی چالاکیی Quire، بلۆک، شێوازی تۆمارکردن، شێوازی چوونەژوورەوە، جۆری پرسیار، ڕاپۆرت، ڕووکار و یەکخستن لە ڕێگەی هەمان تۆماری زیادکراوەکان ڕادەگەیەنرێن کە دامەزراندنی خۆبەڕێوەبەر دەتوانێت بە زیادکراوەی خۆی فراوانی بکات. زیادکراوەکان لە ناو بەرنامەکە کۆمپایل دەکرێن: بارکەری زیادکراوەی کاتی کارکردن نییە و دامەزراوەی میوانداریکراو ناتوانێت یەکێک زیاد بکات. بەڕێوەبەران هەر زیادکراوەیەک بۆ دامەزراوەکەیان لە `/admin/extensions` چالاک یان ناچالاک دەکەن (بڕوانە [ڕێنمایی بەڕێوەبەر](/ckb/admin/extensions/)).

بۆ نووسینی زیادکراوەیەک، لە بلۆکی نموونە و ڕووکاری `packages/integration/extensions/src/sample.ts` دەست پێ بکە. خاڵی زیادکراوەکە هەڵبژێرە و گرێبەستەکەی لە `points.ts` بخوێنەوە، پاشان زیادکراوەکە بە ناسێنەر، وەشان، مۆڵەت، ئەوەی پێشکەشی دەکات و ئەوەی پێویستی پێیەتی، و ئایا دامەزراوەیەک دەتوانێت ناچالاکی بکات ڕابگەیەنە. لە شوێنی پێکهێنانی بەرنامەی وێب و worker تۆماری بکە بۆ ئەوەی هەردووکیان هاوڕا بن. تۆمارەکە ڕێساکانی هەر خاڵێک کاتی دروستکردن و هەرکات `register` بانگ دەکەیت دەپشکنێت، کۆمەڵەیەک کە نادروست دەبێت ڕەت دەکاتەوە و هەموو کێشەکان ناو دەبات، و ئەگەر ئەوە ڕوو بدات تۆمارەکە بەبێ گۆڕانکاری دەمێنێتەوە. تاقیکردنەوەکانی زیادکراوەکە دەبێت پشتڕاست بکەنەوە `extensionContractProblems` بۆی بەتاڵە و ناچالاککردنی کاریگەرییەکەی دەگۆڕێت.

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