Stiùireadh an leasaiche

Cleachd seòladh API na buidhne agad agus teisteanas le raointean cuingichte. Tòisich le iarrtas leughaidh, thoir sùil air an fhreagairt agus cùm dìomhaireachdan taobh a-muigh smachd-tùis agus eisimpleirean sgrìobhainnean.

Tha aon API poblach aig Quire: REST thar HTTPS, air a mhìneachadh ann an sgrìobhainn OpenAPI 3.1, le webhooks soidhnichte airson tachartasan agus frithealaiche MCP do luchd-cuideachaidh AI. Tha an iomradh API a’ liostadh gach puing-crìche agus tachartas.

Seòlaidhean

Tha seòladh fhèin aig gach buidheann agus tha an API fo:

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

Tha an teisteanas a’ dearbhadh na buidhne. Thèid iuchair airson aon bhuidheann a chleachdadh aig seòladh buidhne eile a dhiùltadh.

Tha an sgrìobhainn OpenAPI ri fhaighinn aig /api/v1/openapi.json air seòladh buidheann sam bith; chì gineadairean cliant an tionndadh a tha thu a’ gairm an-còmhnaidh.

Dearbhadh

Tha Iuchraichean API airson sgriobtaichean is amalachadh frithealaiche-gu-frithealaiche. Cruthaichidh rianaire tè aig /admin/integrations/api-keys, taghaidh e na raointean aice agus chì e i aon turas. Cuir mar thòcan giùlain i:

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

Tòisichidh iuchraichean le qk_live_ no qk_test_. Thoir iuchair eadar-dhealaichte do gach amalachadh.

Tha OAuth 2.1 airson aplacaidean a tha ag obair mar neach clàraichte a-steach. Clàraich cliant aig /admin/integrations/oauth-clients, agus an uair sin cleachd sruth còd ceadachaidh le PKCE (/oauth/authorize, /oauth/token), no teisteanasan cliant airson cliant inneil. Tha lorg ri fhaighinn aig /.well-known/oauth-authorization-server. Caolaichidh raon na ghabhas tòcan dèanamh; cha toir e cothrom dha barrachd a dhèanamh na dh’fhaodadh an neach.

Is iad na raointean resource:read, resource:write agus resource:delete, mar courses:read no enrolments:write. Tha ceithir dhiubh fo shochairean agus nochdaidh rabhadh orra air sgrìn a’ cheadachaidh: audit:read, roles:write, tenants:write agus users:delete.

Iarrtasan

• Duilleagachadh: tha gach liosta air a duilleagachadh le cursair. Cuir limit agus an uair sin next_cursor à page mar cursor fhad ’s a tha has_more fìor (faic an eisimpleir gu h-ìosal). Chan eil offset ann.
• Atharrachaidhean o àm: tillidh updated_since na dh’atharraich an dèidh àm. Cuir include_deleted=true ris no leugh /<resource>/deletions gus faighinn a-mach dè chaidh a thoirt air falbh.
• Aithnichearan bhon taobh a-muigh: gabhaidh a’ mhòr-chuid de ghoireasan ris an external_id agad fhèin, agus leughaidh no cuiridh /<resource>/ext:{external_id} suas e leis; cha leig sioncronachadh mar sin leat aithnichearan Quire a stòradh.
• Idempotency: cuir bann-cinn Idempotency-Key air POST, PATCH agus DELETE. Tillidh ath-oidhirp leis an aon iuchair a’ chiad fhreagairt an àite an obair a dhèanamh dà thuras. Feumaidh puingean-crìche mòra seo.
• Tionndaidhean: tha an tionndadh mòr san t-slighe (/v1). Taobh a-staigh dheth, ’s e lèirmheas le ceann-là a th’ ann an gach atharrachadh briste, taghte leis a’ bhann-cinn Quire-Version, mar Quire-Version: 2026-09-20. Gun a’ bhann-cinn, gheibh thu an lèirmheas a bha làithreach nuair a chaidh an teisteanas agad a chur a-mach.

Duilleag de liosta:

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

Mearachdan

Tha gach mearachd na sgrìobhainn duilgheis 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..."}

Stèidhich làimhseachadh air code, a tha seasmhach; tha detail sgrìobhte do dhaoine, sàbhailte ri shealltainn dhaibh agus faodaidh e atharrachadh. Nuair nach aithnich thu còd, cuir e sa bhucaid a rèir category:

Thoir luaidh air request_id nuair a chuireas tu fios gu taic.

Webhooks

Fo-sgrìobh aig /admin/webhooks, no tron API aig /webhook_subscriptions. Tagh tachartasan a rèir ainm (enrolment.created), a rèir raoin (enrolment.*) no iad uile (*). Cuiridh Quire webhook.ping an toiseach; tòisichidh an fho-sgrìobhadh nuair a fhreagras a’ phuing-crìche agad air.

Tha lìbhrigeadh a’ leantainn sònrachadh Standard Webhooks:

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

Gus lìbhrigeadh a dhearbhadh:

1. Tog an t-sreang {webhook-id}.{webhook-timestamp}.{raw body} às na dearbh bhaitean a fhuaireadh, mus dèanar parsadh JSON sam bith.
2. Obraich a-mach HMAC-SHA256 oirre leis an dìomhaireachd fo-sgrìobhaidh agad agus còdaich i mar base64.
3. Dèan coimeas ann an ùine sheasmhach ris gach luach v1, ann an webhook-signature. Dh’fhaodadh dà luach a bhith ann rè tionndadh dìomhaireachd; tha maids sam bith dligheach.
4. Diùlt stampa-ama a tha còrr is còig mionaidean bhon ghleoc agad.

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

Cuir às do dhùblaidhean a rèir webhook-id: dh’fhaodadh lìbhrigeadh ruigsinn barrachd is aon turas. Tha aithnichearan agus geàrr-chunntas goirid anns a’ chorp; faigh an goireas gus a staid làithreach fhaighinn. Feuchaidh Quire ri lìbhrigeadh a dh’fhàillig a-rithist le dàil mean air mhean airson suas ri 72 uair a thìde; faodar an ath-chluich on log lìbhrigidh.

MCP

Tha frithealaiche MCP Quire aig /mcp air seòladh na buidhne, tro HTTP sruthaichte. Lorgaidh cliant MCP am frithealaiche OAuth bho /.well-known/oauth-protected-resource, agus clàraidh an neach a-steach is bheir e cead dìreach mar le cliant OAuth sam bith. Bidh innealan ag obair mar an neach sin agus leis na ceadan aige; iarraidh innealan millteach dearbhadh. Taghaidh rianairean dè na h-innealan a bhios rim faighinn aig /admin/integrations/mcp.

Planaichean is an API

Tha iuchraichean API, cliantan OAuth, webhooks agus frithealaiche MCP an urra ri còir API a’ phlana, agus tha a’ chòir sin anns gach plana àbhaisteach. Ma tha i a dhìth, thèid cruthachadh iuchrach, cliant no fo-sgrìobhaidh a dhiùltadh, thèid sgrìobhaidhean REST agus ceanglaichean MCP a dhiùltadh, ach leanaidh leughaidhean REST orra gus am bi an dàta às-phortail. ’S e sgrìobhainn duilgheis a th’ anns an diùltadh, leis a’ chòd commerce.plan_entitlement, san roinn precondition.

Leudachain

Tha seòrsaichean gnìomh, blocaichean, dòighean clàraidh, dòighean clàraidh a-steach, seòrsaichean cheistean, aithisgean, cuspairean agus amalachadh Quire fhèin air an cur an cèill tron aon chlàr-leudachaidh ris an urrainn do stàladh fèin-aoigheachd rudan a chur ris. Tha leudachain air an cur ri chèile: chan eil luchdadair plugan rè-ruith ann agus chan urrainn do bhuidheann aoigheachd fear a chur ris. Cuiridh rianairean gach leudachan air no dheth airson na buidhne aca aig /admin/extensions (faic stiùireadh an rianaire).

Gus fear a sgrìobhadh, tòisich leis a’ bhloc agus an cuspair sampall ann an packages/integration/extensions/src/sample.ts. Tagh puing leudachaidh agus leugh a cùmhnant ann an points.ts; an uair sin cuir an leudachan an cèill le ID, tionndadh, ceadachas, na tha e a’ toirt seachad agus ag iarraidh, agus an urrainn do bhuidheann a chur dheth. Clàraich e far a bheil an t-aplacaid-lìn agus am pròiseas obrach air an cur ri chèile gus am bi iad ag aontachadh le chèile. Nì an clàr sgrùdadh air riaghailtean puing fhèin nuair a thèid a thogail agus gach turas a ghairmeas tu register; diùlt e seata neo-dhligheach le ainm gach duilgheis agus fàgaidh e an clàr gun atharrachadh. Bu chòir do dheuchainnean an leudachain dearbhadh gu bheil extensionContractProblems falamh air a shon agus gu bheil cur dheth ag atharrachadh na tha e a’ toirt buaidh air.