Torolalana ho an'ny mpamorona

Ampiasao ny adiresin’ny API an’ny organizasanao ary mombamomba alefa misy fahalalana faritra. Antomboka amin’ny fangatahana famakarana, ajaro ny valiny, ary avelao ny teny miafina ivelany an’ny fanaraha-maso loharano sy ny ohatr’ny torolalana.

Misy API iray mamorona i Quire: REST amin’ny alàlan’ny HTTPS, lazain’ny dokumentin’ny OpenAPI 3.1, misy webhook misy siny ho an’ny zava-mitranga ary seriveri MCP ho an’ny mpanampy AI. Mizara singa sy zava-mitranga tsirairay ny famakafakana API.

Adiresy

Misy adresy manokana ny samy organisasa, ary ao ambany azy no misy ny API:

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

Ny mombamomba alefa no mamaritra ny organisasa. Acomina ny kiteny ho an’ny organisasa iray ampiasaina amin’ny adiresin’ny hafa.

Aseho ny dokumentin’ny OpenAPI eo amin’/api/v1/openapi.json amin’ny adiresin’ny organisasa tsirairay, ka hitan’ny mpamorona client foana ny version antsoinao.

Fanamarinana

Ny kiten’ny API ho an’ny solosaina sy fampifandraisana serivera ho serivera. Mamorona iray ny mpikarakara ao amin’/admin/integrations/api-keys, mifidy ny fahalalany, ary mahita azy indray. Alefa azy ho token manontany:

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

Manomboka amin’qk_live_ na qk_test_ ny kiteny. Omeo kiteny manokana ny fampifandraisana tsirairay.

Ny OAuth 2.1 ho an’ny fampiharana miasa ho olona misoratra anarana. Hiresaka client ao amin’/admin/integrations/oauth-clients, avy eo ampiasao ny drafitry ny kaody fahafahana amin’ny PKCE (/oauth/authorize, /oauth/token), na mombamomba alefan’ny client ho an’ny solosaina. Ao amin’/.well-known/oauth-authorization-server ny fikajiana. Mampihena ny afan’ny token ny fahalalana; tsy mampela azy hanao be kokoa no afan’ny olona.

Ny fahalalana dia resource:read, resource:write sy resource:delete, ohatra courses:read na enrolments:write. Efatra no manana fahefana sy aseho amin’ny fanondroana ao amin’ny pejy fanomezan-dàlana: audit:read, roles:write, tenants:write ary users:delete.

Fangatahana

• Fampindram-pejy: lisitra tsirairay dia mampindra amin’ny cursor. Alefa limit, avy eo ny next_cursor avy any amin’ny page ho cursor raha marina ny has_more (ohatra ambany). Tsy misy offset.
• Fanovana avy amin’ny: updated_since dia manome ny niova avy amin’ny fotoana iray. Ampitahao amin’ny include_deleted=true, na mamaky /<resource>/deletions, hahalalana ny nesorina.
• Mari-pamaritana ivelany: ekena ny external_id manokanao ho an’ny loharano maro, ary /<resource>/ext:{external_id} dia mamaky na manavao aminy, ka tsy mila mitahiry ny mari-pamaritan’ny Quire ny fampifandaharana.
• Fisian’ny tena: alefa rohy Idempotency-Key amin’ny POST, PATCH ary DELETE. Ny fanatarana amin’ny kiteny mitovy dia mamerina ny valiny voalohany fa tsy manao ny asa roa. Ilain’ny singa fampiharana lehibe izany.
• Version: ny version lehibe ao amin’ny laza (/v1). Ao anatiny, isaky ny fanovana manimba dia revision misy daty, alain’ny rohy Quire-Version, ohatra Quire-Version: 2026-09-20. Raha tsy misy rohy dia miditra ny revision nifanaraka amin’ny fotoana namomanana ny mombamomba alefa.

Pejy iray amin’ny lisitra:

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

Diso

Isaky ny diso dia dokumentin-panontaniana 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..."}

Mifidy arakaty ny code, izay tsy miova; ny detail dia natao ho an’ny olona, azo aseho azy, afaka miova. Raha tsy mahay ny code iray, sivao amin’ny category:

Ampitahao request_id rehefa mifandray amin’ny fanampiana.

Webhooks

Hiresaka ao amin’/admin/webhooks, na amin’ny alàlan’ny API ao amin’/webhook_subscriptions. Safidio ny zava-mitranga amin’ny anarana (enrolment.created), amin’ny sehatra (enrolment.*) na ny rehetra (*). Alefan’i Quire voalohany webhook.ping; manomboka ny fampifandraisana rehefa mamaly ny endpoint-nao azy.

Mifanaraka amin’ny fepetran’ny Standard Webhooks ny fandefasana:

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

Hanamarinana fandefasana:

1. Ataovy ny fehezanteny {webhook-id}.{webhook-timestamp}.{raw body} avy amin’ny endrika zanabitsy natao, alohan’ny famakarana JSON.
2. Ataovy HMAC-SHA256 aminy amin’ny teny miafina an’ny fampifandraisanao ary base64 azy.
3. Ampitaho amin’ny v1, tsirairay ao amin’ny webhook-signature amin’ny fotoana mitovy. Afaky roa no mety amin’ny fotoana famerenana teny miafina; iray samy mifanaraka dia mety.
4. Avela raha mihoatra ny dimy minitra nofaritan’ny ontolo ny fotoana.

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

Aseho iray ihany amin’ny webhook-id: afaka tonga maromaro ny fandefasana. Misy mari-pamaritana sy famintinana fohy ao amin’ny votoaty; akario ny loharano ho an’ny toe-javatra ankehitriny. Atapahina amin’ny fihenana ny fandefasana diso hatramin’ny ora 72, ary afaka averina avy amin’ny tantaran’ny fandefasana.

MCP

Ny seriveri MCP an’i Quire dia ao amin’/mcp amin’ny adiresin’ny organizasa, amin’ny alàlan’ny HTTP. Mahita ny seriveri OAuth amin’ny /.well-known/oauth-protected-resource ny client MCP, ary miditra sy manankatoavana ny olona toy ny amin’ny client OAuth tsirairay. Miasa ho olona ireo fitaovana, amin’ny fahalemany misy azy, ary mangataka fanamafisana ny fitaovana manimba. Safidin’ny mpikarakara ny fitaovana azo ampiasaina ao amin’/admin/integrations/mcp.

Lamañana sy ny API

Ny kiteny API, client OAuth, webhook sy seriveri MCP dia ao amin’ny fahafahan’ny API an’ny lama, ary misy ao anatin’ny lama fototra tsirairay izy. Ao amin’ny lama tsy misy azy, acomina ny famoronana kiteny, client na fampifandraisana, acomina ny fanoratana REST sy fifandraisana MCP, ary mbola miasa ny famakarana REST ka mbola azo foanana ny data. Dokumentin-panontaniana ny fanakalana misy ny kaody commerce.plan_entitlement, ao amin’ny karazana precondition.

Fanampiny

Ny karazana asa, tsipiriany, fomba fisoratana anarana, fomba fidirana, karazana fanontaniana, tatitra, endrika sy fampifandraisana manokan’i Quire dia ambarina amin’ny lisitry ny fanampiny mitovy izay afaka ampian’ny fampandrafiana an-tsokajy. Tranokaina ny fanampiny: tsy misy mpakana plug-in amin’ny fotoana fiasa, ary tsy afaka manampy iray ny organisasa fandraisana. Safidin’ny mpikarakara ny fanampiny tsirairay aolo na andalo ho an’ny organizasany amin’/admin/extensions (jereo ny torolalana mpikarakara).

Hanoratra iray, antomboka amin’ny tsipiriany sy endrika ohatra ao amin’packages/integration/extensions/src/sample.ts. Safidio ny toeran’ny fanampiny ary mamaky ny fifanarahany ao amin’points.ts, avy eo ambarao ny fanampiny amin’ny id, version, laisazy, ny omeny sy ilainy, ary raha afaka manesaka azy ny organisasa. Hiresaka amin’ny toerana ifampifandraisan’ny rindrin-pankafody sy ny mpandray asa, ka mifankahazo izy roa. Ny lisitra dia mijery ny fehezan’ny toerana tsirairay amin’ny fotoana fampianatra sy isaky ny alàlanao ny register, manala vondrona tsy mety misy ny olana tsirairay voamarina, ary avela tsy ovolavolaina ny lisitra raha izany. Tokony hanamafy ny fanadinana an’ny fanampiny manokana fa extensionContractProblems foana aminy ary fa ny fanesana azy dia manova ny zavatra afany.