Canllaw datblygwr

Defnyddiwch gyfeiriad API eich sefydliad a manylyn dilysu â chwmpas cyfyngedig. Dechreuwch â chais darllen, gwiriwch yr ymateb, a chadwch gyfrinachau y tu allan i reolaeth ffynhonnell ac enghreifftiau dogfennaeth.

Dim ond un API cyhoeddus sydd gan Quire: REST dros HTTPS, a ddisgrifir gan ddogfen OpenAPI 3.1, gyda webhooks wedi’u llofnodi ar gyfer digwyddiadau a gweinydd MCP ar gyfer cynorthwywyr AI. Mae’r cyfeirnod API yn rhestru pob endpoint a digwyddiad.

Cyfeiriadau

Mae gan bob sefydliad ei gyfeiriad ei hun, ac mae’r API oddi tano:

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

Y manylyn dilysu sy’n pennu’r sefydliad. Gwrthodir allwedd ar gyfer un sefydliad a ddefnyddir yng nghyfeiriad un arall.

Mae dogfen OpenAPI yn cael ei gwasanaethu yn /api/v1/openapi.json ar gyfeiriad unrhyw sefydliad, felly mae generaduron cleientiaid bob amser yn gweld y fersiwn rydych yn ei galw.

Dilysu

Mae allweddi API ar gyfer sgriptiau ac integreiddiadau rhwng gweinyddion. Mae gweinyddwr yn creu un yn /admin/integrations/api-keys, yn dewis ei chwmpasau, ac yn ei gweld unwaith. Anfonwch hi fel tocyn bearer:

curl -H "Authorization: Bearer qk_live_..." https://acme.quirelms.com/api/v1/users?limit=50

Mae allweddi’n dechrau ag qk_live_ neu qk_test_. Rhowch allwedd ar wahân i bob integreiddiad.

Mae OAuth 2.1 ar gyfer rhaglenni sy’n gweithredu fel person sydd wedi mewngofnodi. Cofrestrwch gleient yn /admin/integrations/oauth-clients, yna defnyddiwch lif cod awdurdodi gyda PKCE (/oauth/authorize, /oauth/token), neu gymwysterau cleient ar gyfer cleient peiriant. Mae darganfod yn /.well-known/oauth-authorization-server. Mae cwmpas yn cyfyngu’r hyn y gall tocyn ei wneud; nid yw byth yn gadael iddo wneud mwy nag y gallai’r person.

Cwmpasau yw resource:read, resource:write a resource:delete, er enghraifft courses:read neu enrolments:write. Mae pedwar’n freintiedig ac yn cael eu dangos â rhybudd ar y sgrin cydsynio: audit:read, roles:write, tenants:write a users:delete.

Ceisiadau

• Tudaleniad: mae pob rhestr yn defnyddio cyrchwyr. Anfonwch limit, yna’r next_cursor o page fel cursor tra bo has_more yn wir (enghraifft isod). Nid oes offset.
• Newidiadau ers: mae updated_since yn dychwelyd yr hyn a newidiodd ar ôl amser. Pârwch ef â include_deleted=true, neu darllenwch /<resource>/deletions, i wybod beth gafodd ei dynnu.
• Dynodwyr allanol: mae’r rhan fwyaf o adnoddau’n derbyn eich external_id eich hun, ac mae /<resource>/ext:{external_id} yn darllen neu’n uwchlwytho drwy’r ID hwnnw, felly nid oes angen i gydamseriad gadw dynodwyr Quire byth.
• Idempotedd: anfonwch bennawd Idempotency-Key ar POST, PATCH a DELETE. Mae cais arall gyda’r un allwedd yn dychwelyd yr ymateb cyntaf yn hytrach na gwneud y gwaith ddwywaith. Mae endpoints swmp yn ei gwneud yn ofynnol.
• Fersiynau: mae’r brif fersiwn yn y llwybr (/v1). Oddi mewn iddo, mae pob newid sy’n torri cydnawsedd yn adolygiad â dyddiad, wedi’i ddewis gyda’r pennawd Quire-Version, er enghraifft Quire-Version: 2026-09-20. Heb y pennawd, cewch yr adolygiad oedd yn gyfredol pan gyhoeddwyd eich manylyn dilysu.

Tudalen o restr:

{"data": [...], "page": {"next_cursor": "eyJ2Ijox...", "has_more": true, "limit": 100}}

Gwallau

Dogfen broblem RFC 9457 yw pob gwall:

{"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..."}

Dewiswch weithred yn ôl code, sy’n sefydlog; mae detail wedi’i ysgrifennu i bobl, yn ddiogel i’w ddangos iddynt, a gall newid. Pan nad ydych yn adnabod cod, grwpiwch yn ôl category:

Dyfynnwch request_id wrth gysylltu â’r tîm cymorth.

Webhooks

Tanysgrifiwch yn /admin/webhooks, neu drwy’r API yn /webhook_subscriptions. Dewiswch ddigwyddiadau yn ôl enw (enrolment.created), yn ôl ardal (enrolment.*) neu bob un (*). Mae Quire yn anfon webhook.ping yn gyntaf; mae’r tanysgrifiad yn dechrau unwaith y bydd eich endpoint yn ei ateb.

Mae dosbarthiadau’n dilyn manyleb Standard Webhooks:

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

I wirio dosbarthiad:

1. Lluniwch y llinyn {webhook-id}.{webhook-timestamp}.{raw body} o’r union beitiau a dderbyniwyd, cyn dosrannu unrhyw JSON.
2. Cyfrifwch HMAC-SHA256 drosto gyda chyfrinach eich tanysgrifiad, a’i amgodio yn base64.
3. Cymharwch yn gyson o ran amser bob gwerth v1, yn webhook-signature. Gall fod dau yn ystod newid cyfrinach; mae’r naill baru neu’r llall yn ddilys.
4. Gwrthodwch stamp amser sydd fwy na phum munud o’ch cloc.

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);
  });
}

Atal dyblygu drwy webhook-id: gall dosbarthiad gyrraedd fwy nag unwaith. Mae’r corff yn cynnwys dynodwyr a chrynodeb byr; nôl yr adnodd i gael ei gyflwr cyfredol. Ail-geisir dosbarthiadau a fethodd gydag oedi cynyddol am hyd at 72 awr, a gellir eu hailchwarae o’r cofnod dosbarthu.

MCP

Mae gweinydd MCP Quire yn /mcp ar gyfeiriad y sefydliad, dros HTTP ffrydiadwy. Mae cleient MCP yn darganfod gweinydd OAuth o /.well-known/oauth-protected-resource, ac mae’r person yn mewngofnodi ac yn cydsynio fel gydag unrhyw gleient OAuth. Mae offer yn gweithredu fel y person hwnnw, gyda’i ganiatadau, ac mae offer dinistriol yn gofyn am gadarnhad. Gweinyddwyr sy’n dewis pa offer sydd ar gael yn /admin/integrations/mcp.

Cynlluniau a’r API

Mae allweddi API, cleientiaid OAuth, webhooks a gweinydd MCP yn perthyn i hawl API y cynllun, a chaiff pob cynllun safonol ei chynnwys. Ar gynllun heb yr hawl honno, gwrthodir creu allwedd, cleient neu danysgrifiad, gwrthodir ysgrifennu REST a chysylltiadau MCP, ac mae darlleniadau REST yn parhau i weithio fel bod modd allforio data. Dogfen broblem yw’r gwrthodiad gyda’r cod commerce.plan_entitlement, yn y categori precondition.

Estyniadau

Datganir mathau gweithgaredd, blociau, dulliau cofrestru, dulliau mewngofnodi, mathau cwestiwn, adroddiadau, themâu ac integreiddiadau Quire ei hun drwy’r un gofrestrfa estyniadau y gall gosodiad hunangynhaliol ychwanegu ati. Caiff estyniadau eu crynhoi i mewn: nid oes llwythwr ategion amser rhedeg, ac ni all sefydliad lletyol ychwanegu un. Mae gweinyddwyr yn troi pob estyniad ymlaen neu i ffwrdd ar gyfer eu sefydliad yn /admin/extensions (gweler y canllaw gweinyddwr).

I ysgrifennu un, dechreuwch o’r bloc a’r thema sampl yn packages/integration/extensions/src/sample.ts. Dewiswch y pwynt estyniad a darllenwch ei gontract yn points.ts, yna datganwch yr estyniad gyda dynodwr, fersiwn, trwydded, yr hyn mae’n ei ddarparu a’i angen, ac a all sefydliad ei ddiffodd. Cofrestrwch ef lle mae’r rhaglen we a’r worker yn cael eu cyfansoddi, fel bod y ddau’n cytuno. Mae’r gofrestrfa’n gwirio rheolau pob pwynt wrth ei hadeiladu a phob tro y byddwch yn galw register, yn gwrthod set a fyddai’n annilys gan enwi pob problem, ac yn gadael y gofrestrfa heb ei newid pan fydd hynny’n digwydd. Dylai profion yr estyniad ei hun gadarnhau bod extensionContractProblems yn wag ar ei gyfer a bod ei ddiffodd yn newid yr hyn mae’n effeithio arno.