---
title: "Rêbeberiya pêşeniker"
description: "REST API ya Quire, OAuth, webhook, servera MCP û pêvek."
image: "https://docs.quirelms.com/og.png"
---

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

# Rêbeberiya pêşeniker

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

Navnivîsa API ya rêxistina xwe û têketnaverek bi scope bikar bîne. Bi daxwazeke dixwînê dest pê bike, bersivê çawas bike, û nepûran derveyî kontrolya source û nîşaneyên belgeyan veşîne.

Quire APIyeke govzayî heye: REST li ser HTTPS, bi belgeyeke OpenAPI 3.1 ve şîrokirî, bi webhookên qeydkirî ji bo roodûyan û serverek MCP ji bo alîkeryên AI re. [Rêbera API](https://docs.quirelms.com/api/) her kotil û roodûyek li lîsteyê dide.

## Navnivîş <!--quire:addresses-->

Her rêxistinek navnivîsa xwe heye, û API di jêrî wê ye:

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

Têketnaver rêxistinê diyare. Kiliteke ji bo rêxistinek ku di navnivîsa din de tê bikaranîn nayê qebûlkirin.

Belgeya OpenAPI di navnivîsa her rêxistinê de di `/api/v1/openapi.json` de tê berdan, ji ber vê daxwazkerên sernakewtî her dem nûşeya ku tu didê dibînin.

## Nasnamekirin <!--quire:authentication-->

**Kilîtên API** ji bo skrîpt û yekkêşinên server bo server in. Rêveberek yekê di `/admin/integrations/api-keys` de çêdike, scopeên wê hilbijêre û carekê wê dibîne. Wê wek bearer token bişîne:

```
curl -H "Authorization: Bearer qk_live_..." https://acme.quirelms.com/api/v1/users?limit=50
```

Kilît bi `qk_live_` an `qk_test_` dest pê dikin. Ji bo her yekkêşinê kilîta xwe bide.

**OAuth 2.1** ji bo sepanên ku di navenda kesekî ku têketiye re karekî dike. Mirovek di `/admin/integrations/oauth-clients` de qeyd bike, paş rêya koda destûrê bi PKCE bikar bîne (`/oauth/authorize`, `/oauth/token`), an têketnaverên mirov ji bo mirovekî makîn. Dîtin di `/.well-known/oauth-authorization-server` de. Scope tê deyînî çi ku token dikare bike; her tim nade zêdetir ji kes.

Scope in `resource:read`, `resource:write` û `resource:delete`, mîna `courses:read` an `enrolments:write`. Çûar taybet in û di ekrana destûrê de bi hişyariyê tên nîşan: `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>

## Daxwaz <!--quire:requests-->

- **Rêzibeşandin**: her lîstek bi cursor tê dabeşkirin. `limit` bişîne, paş `next_cursor` ji `page` wek `cursor` bişîne gava `has_more` rast e (nîşanerê jêrîn). Nîşaneyek tune.
- **Guhertin ji demekê**: `updated_since` tiştên ku dûpiştî demekî guhertiye dide vegere. Wê bi `include_deleted=true` re bikar bîne, an `/<resource>/deletions` dixwîne, ta fasîtkiriyan bibiznî.
- **Nîşanerên derve**: pir sarveyan `external_id` ya xwe qebûl dikin, û `/<resource>/ext:{external_id}` bi wê dixwîne an dike navdar, ji ber vê hevbestandin her tim nîşanerên Quire parastîne pêwîst nake.
- **Idempotency**: serpeyveke `Idempotency-Key` di `POST`, `PATCH` û `DELETE` de bişîne. Diceribînek bi heman kilî re yekem dîsa dide vegere bila kar du car ne. Kotilên komevê wê pêwîst dikin.
- **Nûşe**: nûşeya sereke di reçikê de ye (`/v1`). Di wê de, her guhertinekî şêxşam revîsyoneke bi dîrok heye, bi serpeyveya `Quire-Version` ve tê hilbijartin, mîna `Quire-Version: 2026-09-20`. Bê serpeyvê tu revîsyonekê digirî ku dîmeke ku têketnavera te hatiye danîn.

Rûpelek ji lîsteyê:

```
{"data": [...], "page": {"next_cursor": "eyJ2Ijox...", "has_more": true, "limit": 100}}
```

## Çelt <!--quire:errors-->

Her çelt belgeyeke pirsgirêkê ya RFC 9457 ye:

```
{"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..."}
```

Li gorî `code` ve biguhere, ew sabit e; `detail` ji bo kesan nivîsî ye, xweş e ku wan bîne, û dikare biguherîne. Gava codek nas nakî, bi `category` ve grup bike:

| Kategoriya | Derengam | Diceribîne |
| --- | --- | --- |
| `validation` | 422, bi detaya qad di `errors` de | Nê |
| `authentication` | 401 | Nê |
| `authorization` | 403 | Nê |
| `not_found` | 404 | Nê |
| `conflict` | 409 | Hin dem |
| `precondition` | 412 | Nê |
| `quota` | 402 ji bo plan, 413 ji bo mezinahî | Nê |
| `rate_limit` | 429, bi `Retry-After` | Erê |
| `upstream` | 502 an 504 | Erê |
| `internal` | 500 | Erê |

`request_id` rêkê girê de gava bi pêşniyarê têkevî.

## Webhook <!--quire:webhooks-->

Di `/admin/webhooks` de abone bike, an bi rêkî API di `/webhook_subscriptions` de. Roodûyan bi nav (`enrolment.created`), bi beş (`enrolment.*`) an hemû (`*`) hilbijêre. Quire berê `webhook.ping` dişîne; abonebûn dûpiştî ku endpointa te wê bersiv bike dest pê dike.

Şandin bişopînin specifikasyona Standard Webhooks:

```
POST /hooks/quire
webhook-id: 01JB7XQK4Z8FQ2M3N4P5R6S7T8
webhook-timestamp: 1790000000
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
```

Ji bo çawaskirina şandekek:

1. `{webhook-id}.{webhook-timestamp}.{raw body}` ji hejmara yek hiştartî, berî parçekirina JSON, biafirîne.
2. Bi nepûra abonebûna xwe li ser wê HMAC-SHA256 hesib û wê base64 bike.
3. Bi her nirxa `v1,` di `webhook-signature` de bi demê sabit veñave. Di biguherîna nepûrê de du dikarin bibe; yek ji wan rast e.
4. Damêteke ku ji saetê te zêdetir î panj deqîqe ye rad bike.

```
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);
  });
}
```

Bi `webhook-id` ve pirsgirêkên duplikat rake: şandekek dikare zêdetir careyan were. Badan nîşaner û kurzînekî kurt tê; sarveyê ji bo derengama niha bikişîne. Şandinên ne serket bi backoff heta 72 saetan diceribînin, û ji loga şandinê were nûvekirin.

## MCP <!--quire:mcp-->

Servera MCP ya Quire di navnivîsa rêxistinê de di `/mcp` ye, bi rêkî streamable HTTP. Daxwazkerek MCP servera OAuth ji `/.well-known/oauth-protected-resource` dide dîtin, û kes wek bi heman reşî têket û destûr dide wek her daxwazkerek OAuth. Amûr bi navenda wê kesê karekî dike, bi destûran, û amûrên tahribkar daxwazê pejûh dikin. Rêveber di `/admin/integrations/mcp` de hilbijêdin kî amûr berdest in.

<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>

## Plan û API <!--quire:plans-and-the-api-->

Kilîtên API, daxwazkerên OAuth, webhook û servera MCP di mafeya API ya planê de ne, û her plana standard wê tê de ye. Li planek ku wê tune, çêkirina kilitek, mirovek an abonebûnek nayê qebûlkirin, nivîsandinên REST û girêtiyên MCP tên raqûlikirin, û dixwîninên REST dewam dikin ta datayek hiştartî bimîne. Raqûlik belgeyeke pirsgirêkê ye bi koda `commerce.plan_entitlement`, di kategoriya `precondition` de.

## Pêvek <!--quire:extensions-->

Cureyên çalakiyê, blok, geberiyên nûskirin, geberiyên têketinê, cureyên pirs, rapor, tema û yekkêşinên xwe ya Quire di heman reçestera pêvekê de tên derdikirin, ku sazkirinek ji aliyê xwe ve dikare zêde bike. Pêvek tên komkirin di nava: barbereke plugînê di demê ranawayê tune, û rêxistinek hatiye mîhankirin nikare yekê zêde bike. Rêveber di `/admin/extensions` de her pêvek ji bo rêxistina xwe veke an rake (binêre [rêbeberiya rêveber](/ku/admin/extensions/)).

Ji bo nivîsariya yek, ji bloka anîmûn û temaya di `packages/integration/extensions/src/sample.ts` de dest pê bike. Noda pêvekê hilbijêre û peymana wê di `points.ts` de bixwîne, paş pêvek bi id, nûşe, lesan, tiştên ku pêşkêş dike û daxwaz dike, û ê ya ku rêxistin dikare veke an rake, derdike. Wê di cîgeke ku nivîsbariya web û karmer tên avazkirin de qeyd bike, ta herdu rast bên. Reçester gava tê biafirîne û her car ku tu `register` titikînî riyên nodê yekê ceribîne, komek nayê qebûlkirin ku nebes e bi her pirsgirêkê bi nav, û reçester biguherîne naqetîne gava ew çêt. Tehtên xwe ya pêvek divê piştrînin ku `extensionContractProblems` ji bo wê vala ye û ku rake wê tiştên ku wê ser bilind e biguherîne.

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