Treoir an fhorbróra

Úsáid seoladh API d’eagraíochta agus dintiúr a bhfuil scóip theoranta aige. Tosaigh le hiarratas léite, seiceáil an freagra, agus coinnigh rúin amach ón gcód foinseach agus ó shamplaí doiciméadachta.

Tá API poiblí amháin ag Quire: REST thar HTTPS, curtha síos i ndoiciméad OpenAPI 3.1, webhooks sínithe d’imeachtaí agus freastalaí MCP do chúntóirí AI. Liostaíonn an tagairt API gach críochphointe agus imeacht.

Seoltaí

Tá a sheoladh féin ag gach eagraíocht, agus tá an API faoi:

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

Is é an dintiúr a shocraíonn an eagraíocht. Diúltaítear d’eochair eagraíochta amháin má úsáidtear í ag seoladh eagraíochta eile.

Déantar an doiciméad OpenAPI a sheirbheáil ag /api/v1/openapi.json ag seoladh aon eagraíochta, ionas go bhfeiceann gineadóirí cliaint an leagan a bhfuil tú ag glaoch air i gcónaí.

Fíordheimhniú

Is do scripteanna agus comhtháthuithe freastalaí le freastalaí iad eochracha API. Cruthaíonn riarthóir ceann ag /admin/integrations/api-keys, roghnaíonn sé a scóipeanna agus ní fheiceann sé ach uair amháin é. Seol é mar chomhartha iompróra:

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

Tosaíonn eochracha le qk_live_ nó qk_test_. Tabhair eochair ar leith do gach comhtháthú.

Is d’fheidhmchláir a ghníomhaíonn thar ceann duine sínithe isteach é OAuth 2.1. Cláraigh cliant ag /admin/integrations/oauth-clients, agus bain úsáid as sreabhadh cód údaraithe le PKCE (/oauth/authorize, /oauth/token), nó dintiúir chliaint do chliant meaisín. Tá an fionnachtain ag /.well-known/oauth-authorization-server. Cuireann scóip teorainn leis an méid is féidir le comhartha a dhéanamh; ní thugann sé cead dó riamh níos mó a dhéanamh ná mar a d’fhéadfadh an duine féin.

Is iad na scóipeanna resource:read, resource:write agus resource:delete, mar shampla courses:read nó enrolments:write. Tá ceithre scóip phribhléideacha a léirítear le rabhadh ar an scáileán toilithe: audit:read, roles:write, tenants:write agus users:delete.

Iarratais

• Uimhriú leathanaigh: déantar uimhriú le cúrsóir ar gach liosta. Cuir limit ar aghaidh, agus ansin cuir next_cursor ó page ar aghaidh mar cursor fad is atá has_more fíor (féach an sampla thíos). Níl aon fhritháireamh ann.
• Athruithe ó am áirithe: tugann updated_since na hathruithe tar éis ama ar leith ar ais. Úsáid in éineacht le include_deleted=true, nó léigh /<resource>/deletions, chun a fháil amach cad a baineadh.
• Aitheantóirí seachtracha: glacann formhór na n-acmhainní le do external_id féin, agus léann nó nuashonraíonn /<resource>/ext:{external_id} de réir an aitheantóra sin. Ní gá, dá bhrí sin, d’aitheantóirí Quire a stóráil le haghaidh sioncronaithe.
• Idéimpotaíocht: seol ceanntásc Idempotency-Key le POST, PATCH agus DELETE. Tugann iarracht eile leis an eochair chéanna an chéad fhreagra ar ais seachas an obair a dhéanamh faoi dhó. Éilítear é ar chríochphointí ollmhóra.
• Leaganacha: tá an leagan mór sa chonair (/v1). Laistigh de, is athbhreithniú dátaithe é gach athrú briste, roghnaithe leis an gceanntásc Quire-Version, mar Quire-Version: 2026-09-20. Gan an ceanntásc faigheann tú an t-athbhreithniú a bhí i bhfeidhm nuair a eisíodh do dhintiúr.

Sampla de leathanach liosta:

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

Earráidí

Is doiciméad faidhbe RFC 9457 é gach earráid:

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

Bunaigh do láimhseáil ar code, atá seasmhach; scríobhtar detail do dhaoine, tá sé sábháilte a thaispeáint dóibh agus d’fhéadfadh sé athrú. Mura n-aithníonn tú cód, bain úsáid as a category:

Luaigh request_id nuair a théann tú i dteagmháil leis an tacaíocht.

Webhooks

Liostáil ag /admin/webhooks, nó tríd an API ag /webhook_subscriptions. Roghnaigh imeachtaí de réir ainm (enrolment.created), de réir réimse (enrolment.*) nó gach imeacht (*). Seolann Quire webhook.ping ar dtús; cuirtear tús leis an síntiús nuair a fhreagraíonn do chríochphointe dó.

Leanann seachadtaí sonraíocht Standard Webhooks:

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

Chun seachadadh a fhíorú:

1. Tóg an téad {webhook-id}.{webhook-timestamp}.{raw body} ó na bearta cruinne a fuarthas, sula bparsálann tú JSON.
2. Ríomh HMAC-SHA256 uirthi le rún do shíntiúis, agus ionchódaigh an toradh mar base64.
3. Déan comparáid leanúnach ama idir é agus gach luach v1, in webhook-signature. D’fhéadfadh dhá cheann a bheith ann le linn rothlú rúin; tá aon mheaitseáil amháin bailí.
4. Diúltaigh stampa ama atá níos mó ná cúig nóiméad ó d’uaireadóir.

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

Déan dúblaigh a dhí-dhúbailt ar webhook-id: d’fhéadfadh seachadadh teacht níos mó ná uair amháin. Bíonn aitheantóirí agus achoimre ghairid sa chorp; faigh an acmhainn chun a staid reatha a fháil. Déantar iarrachtaí athsheolta ar theipeanna le moill mhéadaithe ar feadh suas le 72 uair, agus is féidir iad a athsheoladh ón loga seachadta.

MCP

Tá freastalaí MCP Quire ag /mcp ar sheoladh na heagraíochta, trí HTTP sruthaithe. Aimsíonn cliant MCP freastalaí OAuth ó /.well-known/oauth-protected-resource; síníonn an duine isteach agus toilíonn sé mar a dhéanfadh sé le haon chliant OAuth. Gníomhaíonn uirlisí thar ceann an duine lena cheadanna, agus iarrann uirlisí millteanacha dearbhú. Roghnaíonn riarthóirí na huirlisí atá ar fáil ag /admin/integrations/mcp.

Pleananna agus an API

Baineann eochracha API, cliaint OAuth, webhooks agus freastalaí MCP le teidlíocht API an phlean; cuimsíonn gach plean caighdeánach í. Mura bhfuil sí i bplean, diúltaítear do chruthú eochrach, cliaint nó síntiúis; diúltaítear d’iarratais scríofa REST agus do naisc MCP; leanann léamh REST ar aghaidh ionas gur féidir na sonraí a easpórtáil. Is doiciméad faidhbe é an diúltú leis an gcód commerce.plan_entitlement, sa chatagóir precondition.

Eisínteachtaí

Dearbhaítear cineálacha gníomhaíochta, bloic, modhanna clárúcháin, modhanna sínithe isteach, cineálacha ceiste, tuarascálacha, téamaí agus comhtháthuithe Quire sa chlárlann chéanna eisínteachtaí ar féidir le suiteáil féinóstáilte cur léi. Tiomsaítear eisínteachtaí isteach: níl lódálaí breiseán le linn rite ann agus ní féidir le heagraíocht óstáilte ceann a chur leis. Casann riarthóirí gach eisínteacht air nó as dá n-eagraíocht ag /admin/extensions (féach treoir an riarthóra).

Chun eisínteacht a scríobh, tosaigh leis an mbloc samplach agus an téama samplach in packages/integration/extensions/src/sample.ts. Roghnaigh an pointe eisínteachta agus léigh a chonradh in points.ts; dearbhaigh an eisínteacht ansin le haitheantas, leagan, ceadúnas, a bhfuil ar fáil agus a bhfuil de dhíth uirthi, agus an féidir le heagraíocht í a mhúchadh. Cláraigh í san áit a gcuirtear an feidhmchlár gréasáin agus an worker le chéile, ionas go n-aontaíonn siad. Seiceálann an chlárlann rialacha gach pointe nuair a thógtar í agus gach uair a ghlaonn tú register; diúltaíonn sí do thacar neamhbhailí agus luann sí gach fadhb, gan an chlárlann a athrú. Ba cheart do thástálacha na heisínteachta a dhearbhú go bhfuil extensionContractProblems folamh di agus go n-athraíonn múchadh na heisínteachta an méid a mbíonn tionchar aici air.