Иштеп чыгаруучу нускакасы

Уюмуңуздун API дарегин жана чөйрөсү бар купуялык маалыматын колдонуңуз. Окуу суроосунан баштаңыз, жоопту текшериңиз, сырыңызды булак кодунан жана документация мисалдарынан тышкары кармаңыз.

Quire’де бир гана ачык API бар: HTTPS үстүндөгү REST, OpenAPI 3.1 документи менен сүрөттөлгөн, окуялар үчүн кол коюлган вебхуктар жана ЖИ жардамчылары үчүн MCP сервери менен. API документациясы ар бир учурду жана окуяны тизмелейт.

Даректер

Ар бир уюмун өз дареги бар, жана API анын астында жайгашкан:

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

Купуялык маалыматы уюмду чечет. Бир уюмдун килити башка уюмдун дарегинде колдонулса, ал четке кагылат.

OpenAPI документи каалаган уюмдун дарегиндеги /api/v1/openapi.json жеринен берилет, ошондуктан клиенттик генераторлор ар дайым сиз чакырып жаткан версияны көрөт.

Аутентификация

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.

Суроолор

• Беттөө: ар бир тизме курсор менен беттелет. limit өткөрүңүз, андан кийин next_cursor’ду pageден cursor катары өткөрүңүз жана has_more чын болгонча улантыңыз (мисалы төмөндө). 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 боюнча бөлүңүз:

Колдоо кызматына кайрылганда request_id’ди цитаталоо кылыңыз.

Вебхуктар

/admin/webhooks жеринен же API аркылуу /webhook_subscriptions жеринен жазылыңыз. Окуяларды аты боюнча (enrolment.created), аймак боюнча (enrolment.*) же баары (*) тандаңыз. Quire биринчи webhook.ping жөнөтөт; жазылуу endpointиңиз жооп бергенден кийин башталат.

Жеткирүүлөр Standard Webhooks спецификасын ээрчитет:

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

Жеткирүүнү текшерүү үчүн:

1. Алынган так байттардан, JSON талдоодон мурун, {webhook-id}.{webhook-timestamp}.{raw body} стрингин куруңуз.
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 жеринде, streamable HTTP үстүндө. MCP клиентти OAuth серверин /.well-known/oauth-protected-resource жеринен ачып, адам кирет жана макулдук берет, кадимки OAuth клиентиндей. Куралдар ошол адамдын уулдары менен аракет кылат, бузуучу куралдар болсо растоону сурайт. Администраторлор /admin/integrations/mcp жеринен кайсы куралдар жеткиликтүү экенин тандашат.

План жана API

API килттери, OAuth клиенттери, вебхуктар жана MCP сервери пландын API укугуна таандык жана ар бир стандарттык планда камтылган. Анда жок планда килит, клиент же жазылуу түзүлүшү четке кагылат, REST жазуулары жана MCP tуташуулары четке кагылат, ал эми REST окуулары иштөөнү улантат, ошондо маалымат экспорттолгон бойдон калат. Баш тартуу — commerce.plan_entitlement коду бар жана precondition категориясындагы маселе документи.

Кеңейтүүлөр

Quire’дин өз иш-аракет түрлөрү, блоктору, каттоо ыкмалары, кирүү ыкмалары, суроо түрлөрү, отчёттору, темалары жана интеграциялары өз орнотууга коша ала турган кеңейтүү реестри аркылуу жарыяланат. Кеңейтүүлөр чогулткандан кирип чыгат: убакыт ичинде жүктөлүүчү плагин жүктөгүч жок жана хостингдеги уюм аны кошо албайт. Администраторлор өз уюмдары үчүн ар бир кеңейтүүнү /admin/extensions жеринен күйгүзүп же өчүрөт (администратор нускакасын караңыз).

Аны жазуу үчүн packages/integration/extensions/src/sample.ts ичиндеги үлгү блоктон жана темадан баштаңыз. Кеңейтүү чекитин тандаңыз жана анын келишимин points.ts ичинен окуңуз, андан кийин кеңейтүүнү id, версия, лицензия, эмне берери жана керектөөсү, жана уюм аны өчүрө ала турганы менен жарыялаңыз. Веб-колдонмо жана жумушчу кургилген жеринен каттатыңыз, ошондо экөөсү макул болсун. Реестр курулганда жана register чакырган сайын ар бир чекиттин өз эрежелерин текшерет, ар бир ката аталган туура эмес топтомун четке кагат, жана андай болгондо реестрди өзгөртпөйт. Кеңейтүүнүн өз тесттери аны үчүн extensionContractProblems бош экенин жана аны өчүрүү таасир эткен нерсени өзгөртөрүн ырасташы керек.