---
title: "Tərtibatçı təlimatı"
description: "Quire REST API, OAuth, vebhuklar, MCP serveri və genişlənmələr."
image: "https://docs.quirelms.com/og.png"
---

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

# Tərtibatçı təlimatı

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

Təşkilatınızın API ünvanından və məhdud scope-lu etimadnamədən istifadə edin. Oxuma sorğusu ilə başlayın, cavabı yoxlayın, secret-ləri isə mənbə nəzarətindən və sənədlərdəki nümunələrdən kənarda saxlayın.

Quire-in bir açıq API-si var: OpenAPI 3.1 sənədi ilə təsvir edilən HTTPS üzərindən REST, hadisələr üçün imzalı vebhuklar və süni intellekt köməkçiləri üçün MCP serveri. [API arayışında](https://docs.quirelms.com/api/) hər endpoint və hadisə sadalanır.

## Ünvanlar <!--quire:addresses-->

Hər təşkilatın öz ünvanı var və API onun altında yerləşir:

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

Təşkilatı etimadnamə müəyyən edir. Bir təşkilatın açarı ilə başqasının ünvanına sorğu rədd edilir.

OpenAPI sənədi istənilən təşkilat ünvanında `/api/v1/openapi.json` yolundan verilir, buna görə client generatorları çağırdığınız versiyanı həmişə görür.

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

**API açarları** skriptlər və serverdən serverə inteqrasiyalar üçündür. Administrator `/admin/integrations/api-keys` ünvanında açar yaradıb scope-ları seçir və onu yalnız bir dəfə görür. Bearer token kimi göndərin:

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

Açarlar `qk_live_` və ya `qk_test_` ilə başlayır. Hər inteqrasiyaya ayrıca açar verin.

**OAuth 2.1** daxil olmuş şəxs adından işləyən tətbiqlər üçündür. `/admin/integrations/oauth-clients` ünvanında client qeydiyyatdan keçirin, sonra PKCE ilə avtorizasiya kodu axınından (`/oauth/authorize`, `/oauth/token`) və ya maşın client-i üçün client credentials-dən istifadə edin. Kəşf ünvanı `/.well-known/oauth-authorization-server`-dir. Scope tokenin edə biləcəklərini məhdudlaşdırır; şəxsə verilən icazədən artıq səlahiyyət vermir.

Scope-lar `resource:read`, `resource:write` və `resource:delete` formatındadır, məsələn, `courses:read` və ya `enrolments:write`. Dördü imtiyazlıdır və razılıq ekranında xəbərdarlıqla göstərilir: `audit:read`, `roles:write`, `tenants:write` və `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>

## Sorğular <!--quire:requests-->

- **Səhifələmə**: hər siyahı cursor ilə səhifələnir. `limit` göndərin, sonra `next_cursor`-ı `page`-dən götürüb `cursor` kimi ötürün, `has_more` true olduqca (aşağıdakı nümunəyə baxın). Offset yoxdur.
- **Bu vaxtdan bəri dəyişikliklər**: `updated_since` vaxtdan sonra dəyişənləri qaytarır. Silinənləri öyrənmək üçün bunu `include_deleted=true` ilə birləşdirin və ya `/<resource>/deletions` oxuyun.
- **Xarici identifikatorlar**: əksər resurslar öz `external_id` dəyərinizi qəbul edir; `/<resource>/ext:{external_id}` həmin dəyərlə oxuyur və ya upsert edir, buna görə sinxronizasiya Quire identifikatorlarını saxlamağı tələb etmir.
- **İdemponentlik**: `Idempotency-Key` başlığını `POST`, `PATCH` və `DELETE` sorğularında göndərin. Eyni açarla təkrar sorğu işi ikinci dəfə görmək əvəzinə ilk cavabı qaytarır. Bulk endpoint-lərdə bu məcburidir.
- **Versiyalar**: əsas versiya yoldadır (`/v1`). Onun daxilində pozucu dəyişikliklərin hər biri tarixli reviziyadır və `Quire-Version` başlığı ilə seçilir, məsələn, `Quire-Version: 2026-09-20`. Başlıq verilməsə, etimadnaməniz yaradılan vaxt qüvvədə olan reviziyanı alırsınız.

Siyahının bir səhifəsi:

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

## Xətalar <!--quire:errors-->

Hər xəta RFC 9457 problem sənədidir:

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

Sabit olan `code`-a əsasən yönləndirin; `detail` insanlar üçün yazılıb, onlara göstərmək təhlükəsizdir və dəyişə bilər. Kodu tanımırsınızsa, `category` üzrə qruplaşdırın:

| Kateqoriya | Status | Təkrar cəhd |
| --- | --- | --- |
| `validation` | 422, `errors` daxilində sahə təfərrüatı ilə | Xeyr |
| `authentication` | 401 | Xeyr |
| `authorization` | 403 | Xeyr |
| `not_found` | 404 | Xeyr |
| `conflict` | 409 | Bəzən |
| `precondition` | 412 | Xeyr |
| `quota` | Plan üçün 402, ölçü üçün 413 | Xeyr |
| `rate_limit` | 429, `Retry-After` ilə | Bəli |
| `upstream` | 502 və ya 504 | Bəli |
| `internal` | 500 | Bəli |

Dəstəyə müraciət edəndə `request_id` dəyərini verin.

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

`/admin/webhooks` ünvanında və ya API vasitəsilə `/webhook_subscriptions` yolunda abunə olun. Hadisələri adla (`enrolment.created`), sahəyə görə (`enrolment.*`) və ya hamısını (`*`) seçin. Quire əvvəlcə `webhook.ping` göndərir; endpoint cavab verdikdən sonra abunəlik başlayır.

Çatdırılmalar Standard Webhooks spesifikasiyasına əməl edir:

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

Çatdırılmanı yoxlamaq üçün:

1. JSON təhlilindən əvvəl alınmış dəqiq baytlarla `{webhook-id}.{webhook-timestamp}.{raw body}` sətrini qurun.
2. Abunəlik secret-i ilə üzərində HMAC-SHA256 hesablayın və Base64-a çevirin.
3. `v1,` dəyərlərinin hər birini `webhook-signature` başlığı ilə sabit vaxtda müqayisə edin. Secret dəyişdirilərkən iki dəyər ola bilər; istənilən uyğunluq etibarlıdır.
4. Saatınızdan beş dəqiqədən artıq fərqlənən timestamp-i rədd edin.

```
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` dəyərinə əsasən dublikatı aradan qaldırın: çatdırılma birdən çox gələ bilər. Gövdədə identifikatorlar və qısa xülasə var; cari vəziyyət üçün resursu əldə edin. Uğursuz çatdırılmalar 72 saata qədər artan intervallarla yenidən göndərilir və çatdırılma jurnalından təkrar oynadıla bilər.

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

Quire MCP serveri təşkilatın ünvanındakı `/mcp` yolunda, axınlı HTTP üzərində işləyir. MCP client OAuth serverini `/.well-known/oauth-protected-resource` ünvanından aşkarlayır; şəxs istənilən OAuth client-də olduğu kimi daxil olub razılıq verir. Alətlər həmin şəxsin icazələri ilə onun adından işləyir, dağıdıcı alətlər isə təsdiq istəyir. Administratorlar əlçatan alətləri `/admin/integrations/mcp` ünvanında seçirlər.

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

## Planlar və API <!--quire:plans-and-the-api-->

API açarları, OAuth client-lər, vebhuklar və MCP serveri planın API hüququna daxildir; hər standart planda bu hüquq var. Daxil etməyən planda açar, client və ya abunəlik yaratmaq, REST yazmaları və MCP bağlantısı rədd edilir; REST oxumaları məlumatın ixrac edilə bilməsi üçün işləyir. Rədd cavabı `commerce.plan_entitlement` kodlu və `precondition` kateqoriyalı problem sənədidir.

## Genişlənmələr <!--quire:extensions-->

Quire-in öz fəaliyyət növləri, blokları, qeydiyyat üsulları, giriş üsulları, sual növləri, hesabatları, mövzuları və inteqrasiyaları öz serverində quraşdırmanın əlavə edə bildiyi eyni genişlənmə reyestrində elan edilir. Genişlənmələr yığıma daxil edilir: işləmə zamanı plagin yükləyicisi yoxdur və hostinq təşkilatı yenisini əlavə edə bilməz. Administratorlar hər genişlənməni təşkilatları üçün `/admin/extensions` ünvanında aktivləşdirir və ya söndürür ([administrator təlimatına](/az/admin/extensions/) baxın).

Genişlənmə yazmaq üçün `packages/integration/extensions/src/sample.ts` nümunə blok və mövzusundan başlayın. Genişlənmə nöqtəsini seçin, `points.ts` daxilində müqaviləsini oxuyun, sonra ID, versiya, lisenziya, təqdim etdiyi və tələb etdiyi imkanlar, eləcə də təşkilatın onu söndürə bilib-bilməməsi ilə elan edin. Veb tətbiq və worker-in tərkib olunduğu yerə qeydiyyatdan keçirin ki, hər ikisi uyğun olsun. Reyestr qurularkən və `register` çağırışında hər nöqtənin öz qaydalarını yoxlayır, bütün problemləri adlandıraraq etibarsız dəsti rədd edir və belə olduqda reyestri dəyişməz saxlayır. Genişlənmənin öz testləri onun üçün `extensionContractProblems` boş olduğunu və söndürməyin təsir etdiyi imkanları dəyişdirdiyini təsdiqləməlidir.

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