Անցնել բովանդակությանը
QuireՓաստաթղթեր
Հայերեն

Ծրագրավորողի ուղեցույց

Quire REST API, OAuth, վեբհուքներ, MCP սերվեր և ընդլայնումներ։

Դիտել որպես Markdown

Օգտագործեք ձեր կազմակերպության API հասցեն և սահմանափակ շրջանակով հավատարմագիր։ Սկսեք կարդալու հարցումով, ստուգեք պատասխանը և գաղտնի տվյալները պահեք սկզբնաղբյուրից ու փաստաթղթերի օրինակներից դուրս։

Quire-ն ունի մեկ հանրային API՝ REST HTTPS-ով, որը նկարագրվում է OpenAPI 3.1 փաստաթղթով, իրադարձությունների համար ստորագրված վեբհուքներով և ԱԲ օգնականների համար MCP սերվերով։ API-ի տեղեկատուն թվարկում է բոլոր վերջնակետերն ու իրադարձությունները։

Հասցեներ

Յուրաքանչյուր կազմակերպություն ունի իր հասցեն, իսկ API-ն հասանելի է դրա տակ․

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

Կազմակերպությունը որոշվում է ըստ հավատարմագրի։ Մեկ կազմակերպության բանալին մյուսի հասցեում օգտագործելու դեպքում հարցումը մերժվում է։

OpenAPI փաստաթուղթը հասանելի է ցանկացած կազմակերպության հասցեում՝ /api/v1/openapi.json ուղով, ուստի հաճախորդի կոդի գեներատորները միշտ տեսնում են այն տարբերակը, որին դիմում եք։

Նույնականացում

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։

Հարցումներ

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

Սխալներ

Յուրաքանչյուր սխալ 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-ը։

Վեբհուքներ

Բաժանորդագրվեք /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 ուղով՝ հոսքային HTTP-ով։ MCP հաճախորդը OAuth սերվերը հայտնաբերում է /.well-known/oauth-protected-resource հասցեով, իսկ անձը մուտք է գործում և համաձայնություն տալիս այնպես, ինչպես ցանկացած OAuth հաճախորդի դեպքում։ Գործիքները գործում են այդ անձի թույլտվություններով, իսկ տվյալներ ջնջող գործիքները հաստատում են պահանջում։ Ադմինիստրատորները ընտրում են հասանելի գործիքները /admin/integrations/mcp էջում։

Պլաններ և API

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

Ընդլայնումներ

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

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

Նավիգացիա

Մուտքագրեք՝ որոնելու համար…

↑↓ նավարկել↵ ընտրելEsc փակել