---
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/hy/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 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`։
Շրջանակը սահմանափակում է 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-->

- **Էջավորում**․ ցանկերի բոլոր արդյունքները էջավորվում են կուրսորով։
  Փոխանցեք `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-->

Quire-ի MCP սերվերը հասանելի է կազմակերպության հասցեի `/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-ի իրավասությունը ներառում է API բանալիները, OAuth հաճախորդները,
վեբհուքները և MCP սերվերը, և այն հասանելի է յուրաքանչյուր ստանդարտ պլանում։
Առանց այդ իրավասության պլանում բանալու, հաճախորդի կամ բաժանորդագրության
ստեղծումը մերժվում է, REST գրելու գործողություններն ու MCP կապերը նույնպես
մերժվում են, իսկ REST կարդալու հարցումները շարունակում են գործել, որպեսզի
տվյալները հնարավոր լինի արտահանել։ Մերժումը խնդրի փաստաթուղթ է՝
`commerce.plan_entitlement` կոդով, `precondition` կատեգորիայում։

## Ընդլայնումներ <!--quire:extensions-->

Quire-ի սեփական գործողությունների տեսակները, բովանդակության բլոկները,
գրանցման եղանակները, մուտքի եղանակները, հարցերի տեսակները, հաշվետվությունները,
ձևավորումները և ինտեգրումները հայտարարվում են ընդլայնումների նույն գրանցամատյանում,
որին կարող են ավելացնել ինքնուրույն հոսթավորված տեղադրումները։ Ընդլայնումները
կոմպիլացվում են ծրագրի մեջ․ գործարկման ժամանակ plugin բեռնիչ չկա, և
հոսթավորված կազմակերպությունը չի կարող նոր ընդլայնում ավելացնել։
Ադմինիստրատորները միացնում կամ անջատում են յուրաքանչյուր ընդլայնում իրենց
կազմակերպության համար `/admin/extensions` էջում (տես
[ադմինիստրատորի ուղեցույցը](/hy/admin/extensions/))։

Ընդլայնում գրելու համար սկսեք `packages/integration/extensions/src/sample.ts`
ֆայլի օրինակային բլոկից և ձևավորումից։ Ընտրեք ընդլայնման կետը և կարդացեք դրա
պայմանագիրը `points.ts`-ում, այնուհետև հայտարարեք ընդլայնումը՝ նշելով ID-ն,
տարբերակը, լիցենզիան, տրամադրածն ու պահանջածը և այն՝ արդյոք կազմակերպությունը
կարող է անջատել այն։ Գրանցեք այն այն վայրում, որտեղ համակցվում են վեբ
հավելվածն ու աշխատողը, որպեսզի երկուսն էլ համաձայն լինեն։ Գրանցամատյանը
կառուցելիս և `register` կանչելիս ստուգում է յուրաքանչյուր կետի կանոնները,
մերժում է անվավեր կազմը՝ թվարկելով բոլոր խնդիրները և մերժման դեպքում
գրանցամատյանը թողնում անփոփոխ։ Ընդլայնման սեփական թեստերը պետք է ստուգեն, որ
դրա համար `extensionContractProblems`-ը դատարկ է, և անջատումը փոխում է դրա
ազդեցությունը։

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