Даведнік распрацоўшчыка

Выкарыстоўвайце адрас 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-токен:

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 мае значэнне 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=

Каб праверыць дастаўку:

Сфармуйце радок {webhook-id}.{webhook-timestamp}.{raw body} з дакладных атрыманых байтаў да разбору JSON.
Вылічыце для яго HMAC-SHA256 з сакрэтам падпіскі і пераўтварыце вынік у base64.
Параўнайце ў сталым часе з кожным значэннем v1, у webhook-signature. Падчас змены сакрэту іх можа быць два; дастаткова супадзення аднаго.
Адхіляйце часавую метку, якая адрозніваецца ад вашага гадзінніка больш чым на пяць хвілін.

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

Сервер MCP Quire даступны па адрасе /mcp арганізацыі праз HTTP з патокавай перадачай. Кліент MCP знаходзіць сервер OAuth па адрасе /.well-known/oauth-protected-resource; чалавек уваходзіць і дае згоду, як для любога кліента OAuth. Інструменты дзейнічаюць з дазволамі гэтага чалавека; разбуральныя інструменты патрабуюць пацвярджэння. Адміністратары выбіраюць даступныя інструменты ў /admin/integrations/mcp.

Планы і API

Ключы API, кліенты OAuth, вэбхукі і сервер MCP патрабуюць API-функцый плана; яна ўключана ва ўсе стандартныя планы. Без яе стварэнне ключа, кліента або падпіскі адхіляецца, REST-запісы і злучэнні MCP забароненыя, а чытанне REST застаецца даступным, каб даныя можна было экспартаваць. Адказ — дакумент праблемы з кодам commerce.plan_entitlement і катэгорыяй precondition.

Пашырэнні

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

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