---
title: "Даведнік распрацоўшчыка"
description: "REST API Quire, OAuth, вэбхукі, сервер MCP і пашырэнні."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/be/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, з падпісанымі вэбхукамі для падзей і серверам 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-токен:

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

- **Пагінацыя**: усе спісы разбітыя на старонкі з курсорам. Перадайце `limit`, затым — `next_cursor` з `page` як `cursor`, пакуль `has_more` мае значэнне true (прыклад ніжэй). Offset няма.
- **Змены пасля даты**: `updated_since` вяртае змены пасля часу. Дадайце `include_deleted=true` або прачытайце `/<resource>/deletions`, каб даведацца, што выдалена.
- **Знешнія ідэнтыфікатары**: большасць рэсурсаў прымаюць уласны `external_id`, а `/<resource>/ext:{external_id}` дазваляе атрымаць або абнавіць запіс паводле яго, таму сінхранізацыі не трэба захоўваць ідэнтыфікатары 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. Сфармуйце радок `{webhook-id}.{webhook-timestamp}.{raw body}` з дакладных атрыманых байтаў да разбору JSON.
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 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, вэбхукі і сервер MCP патрабуюць API-функцый плана; яна ўключана ва ўсе стандартныя планы. Без яе стварэнне ключа, кліента або падпіскі адхіляецца, REST-запісы і злучэнні MCP забароненыя, а чытанне REST застаецца даступным, каб даныя можна было экспартаваць. Адказ — дакумент праблемы з кодам `commerce.plan_entitlement` і катэгорыяй `precondition`.

## Пашырэнні <!--quire:extensions-->

Уласныя тыпы дзейнасцяў, блокі, спосабы залічэння і ўваходу, тыпы пытанняў, справаздачы, тэмы і інтэграцыі Quire аб'яўляюцца праз той жа рэестр пашырэнняў, які можа дапоўніць самастойнае ўсталяванне. Пашырэнні кампілююцца ў праграму: загрузчыка плагінаў падчас выканання няма, а размешчаная арганізацыя не можа дадаць пашырэнне. Адміністратары ўключаюць і выключаюць пашырэнні арганізацыі на `/admin/extensions` (гл. [даведнік адміністратара](/be/admin/extensions/)).

Каб стварыць пашырэнне, пачніце з прыкладу блока і тэмы ў `packages/integration/extensions/src/sample.ts`. Выберыце кропку пашырэння і прачытайце яе кантракт у `points.ts`, затым аб'явіце пашырэнне з ID, версіяй, ліцэнзіяй, пералікам таго, што яно дае і патрабуе, і магчымасцю выключэння арганізацыяй. Зарэгіструйце яго там, дзе складаюцца вэб-прыкладанне і worker, каб абодва бакі мелі аднолькавую канфігурацыю. Рэестр правярае правілы кожнай кропкі пры зборцы і пры кожным выкліку `register`; калі набор несапраўдны, ён называе ўсе праблемы і не змяняе рэестр. Уласныя тэсты пашырэння павінны правяраць, што `extensionContractProblems` для яго пусты і што выключэнне змяняе звязаныя магчымасці.

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