Aratohu mō ngā kaiwhanoke

Whakamahia te wāhi API o tō rōpū me tētahi tohu whakamanatanga whakarara. Tīmata mai me tētahi tono pānui, tātaritia te whakautu, ā, tiakina ngā mea tūmataiti i waho o te whakahaere waehere me ngā tauira tuhinga.

He API tūtahi a Quire: te REST i runga i te HTTPS, e whakaaturia ana e tētahi tuhinga OpenAPI 3.1, me ngā webhook e ia ana tō rātou āhua mō ngā take, me tētahi tūmau MCP mō ngā āwhina AI. Ka tuhia ngā tapae me ngā take katoa i te tohutoro API.

Ngā wāhi

He wāhi ake ia rōpū, ā, kei raro i a ia te API:

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

E whakatau ana te tohu whakamanatanga i te rōpū. Ka āraihia tētahi kī mō tētahi rōpū e whakamahia ana i te wāhi o tētahi atu.

Ka tukuna te tuhinga OpenAPI i /api/v1/openapi.json i te wāhi o ia rōpū, nō reira ka kite ai ngā hanga kaihoko i te āhua e karanga ana koe.

Whakamanatanga

Ngā kī API mō ngā pūmanawa me ngā hononga tūmau-ki-tūmau. Ka hanga e tētahi kaiwhakahaere tētahi i te /admin/integrations/api-keys, ka kōwhiria ōna rohe, ā, ka kitehia ia kotahi wā. Tukuna ia hei tohu kaiporta:

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

Ka tīmata ngā kī i qk_live_ rānei qk_test_. Hoatu ia hononga tana ake kī.

OAuth 2.1 mō ngā taupānga e mahi ana i te ingoa o te tāngata hono mai. Rēhitatia tētahi kaihoko i te /admin/integrations/oauth-clients, kātia ka whakamahia te ara kōd whakaae me te PKCE (/oauth/authorize, /oauth/token), rānei ngā tohu whakamanatanga kaihoko mō tētahi kaihoko pūrere. Kei /.well-known/oauth-authorization-server te tūhuratanga. Ka whakarara tētahi rohe i te e āea ana e tētahi tohu; kāore e āiahia ia te mahi i te nui atu i te e āea ana e te tāngata.

He resource:read, resource:write me resource:delete ngā rohe, hei tauira courses:read rānei enrolments:write. He whā ngā rohe motuhake, ā, ka whakaaturia me tētahi tohu tūpato i te papa whakaae: audit:read, roles:write, tenants:write me users:delete.

Ngā tono

• Ngā whārangi: ka whakawhāitia ia rārangi ma te pūni. Tukuna te limit, kātia te next_cursor mai i te page hei cursor i te wā e tū tonu ana te has_more (hei tauira raro). Kāore he toenga.
• Ngā huringa mai i tētahi wā: ka whakahoki te updated_since i te mea kua huri i mua i tētahi wā. Hoatu ia me te include_deleted=true, rānei pānui i te /<resource>/deletions, kia mōhio ai i te mea kua tangohia.
• Ngā tohu ā-waho: ka tuku ia rauemi i tō ake external_id, ā, ka pānui rānei tāpiritia te /<resource>/ext:{external_id} i runga i a ia, nō reira kāore e hiahiatia ana i tētahi whakawhiti raraunga te kohinga i ngā tohu o Quire.
• Te ōrite mahi: tukuna he tohu Idempotency-Key i runga i te POST, PATCH me te DELETE. Ka whakahoki tētahi whakamātau anō me te tohu kotahi i te whakautu tuatahi, ehara i te mahi i te mahi rua. E hiahiatia ana tēnei e ngā tapae rōpū.
• Ngā āhua: kei te ara te āhua matua (/v1). I roto i a ia, ka tuhia ia huringa whakararu hei whakāhutanga i te rā, e kōwhiria ana ma te tohu Quire-Version, hei tauira Quire-Version: 2026-09-20. Mēnā kāore te tohu, ka whiwhi koe i te whakāhutanga e tū ana i te wā i hoatu ai tō tohu whakamanatanga.

He whārangi o tētahi rārangi:

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

Ngā hapa

He tuhinga raruraru RFC 9457 ia hapa:

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

Whakarite i runga i te code, e tū tonu ana; he tuhinga mō te tangata te detail, e āea ana tana whakaaturanga ki a rātou, ā, ka āea ia te huri. Mēnā kāore e mōhio koe i tētahi kōd, kōwhiria te kāwai i runga i te category:

Tukuna tō request_id inā ka whakapā koe ki te tautoko.

Ngā webhook

Rēhitatia i te /admin/webhooks, rānei ma te API i te /webhook_subscriptions. Kōwhiria ngā take ma tana ingoa (enrolment.created), ma te wāhanga (enrolment.*) rānei katoa (*). Ka tukuna tuatahi a Quire tētahi webhook.ping; ka tīmata te kōtuinga i te wā ka whakautu tō tapae i a ia.

Ka whai ngā tuku i te whakaritenga Standard Webhooks:

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

Kia tātaritia tētahi tuku:

1. Hangahia te rārangi {webhook-id}.{webhook-timestamp}.{raw body} mai i ngā byte tino tika i whiwhi hia, i mua i te tātari JSON katoa.
2. Tāhau te HMAC-SHA256 i runga i a ia me te kupu tūmataiti o tō kōtuinga, ā, whakawhiti hei base64.
3. Tātaritia me ia uara v1, i te webhook-signature i te wā ōrite. Ka rua i te wā tāhurihuri o te kupu tūmataiti; e tika ana te ōrite kotahi.
4. Whakakorea ia tohu wā e tū pātai atu i te rima meneti i tō matai poto.

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

Whakakotahitia ma te webhook-id: ka taea te tae mai te tuku i ngā wā ruarua. He tohu me tētahi whakatātaki poto kei roto i te tinana; tikina te rauemi mō tana āhua o tēnei wā. Ka whakamātau anō ngā tuku kua rahua me te tatari wā whakanui mō te 72 haora, ā, ka taea te whakahoki i a rātou mai i te rārangi tuku.

MCP

Kei te wāhi o te rōpū te tūmau MCP o Quire i te /mcp, ma te HTTP e āea ana te rere. Ka tūhura e tētahi kaihoko MCP te tūmau OAuth mai i /.well-known/oauth-protected-resource, ā, ka hono mai te tāngata, ā, ka whakaae i te āhua e mahia ana e tētahi kaihoko OAuth. Ka mahi ngā rākau i te āhua o tērā tāngata, me ōna whakaaetanga, ā, ka pātai ngā rākau muku i te whakaaetanga. E kōwhiria e ngā kaiwhakahaere ēhea ngā rākau e wātea ana i te /admin/integrations/mcp.

Ngā pereke me te API

Kei te tika API o te pereke ngā kī API, ngā kaihoko OAuth, ngā webhook me te tūmau MCP, ā, kei roto ia i ia pereke tūmatanui. I tētahi pereke kāore, ka āraihia te hanga i tētahi kī, kaihoko rānei kōtuinga, ka āraihia hoki ngā tuhi REST me ngā hono MCP, engari ka tū tonu ngā pānui REST, kia noho wātea tonu te raraunga mō te whakakawhaki. He tuhinga raruraru te ārai me te kōd commerce.plan_entitlement, i te kāwai precondition.

Ngā tāpiritanga

Ka whakaaturia ngā āhua mahi ōna ake o Quire, ngā papa, ngā ara rēhita, ngā ara hono atu, ngā āhua pātai, ngā pūrongo, ngā kākahu me ngā hononga ma te rārangi tāpiritanga kotahi, e āea ana tētahi whakaturanga e whakahaeretia ana e koe te tāpiritanga i a ia. Ka kōmiri ngā tāpiritanga i roto: kāore he kaiutu pūwāea i te wā mahi, ā, kāore e āea ana tētahi rōpū e noho ana i te ratonga tuku te tāpiritanga i tētahi. Ka whakawāhia e ngā kaiwhakahaere ia tāpiritanga mō tō rātou rōpū i te /admin/extensions (tirohia te aratohu kaiwhakahaere).

Kia tuhituhia tētahi, tīmata mai i te papa tauira me te kākahu tauira i te packages/integration/extensions/src/sample.ts. Kōwhiria te wāhanga tāpiritanga, ā, pānui i tana konoheni i te points.ts, kātia ka tuhia te tāpiritanga me tētahi id, tētahi āhua, tētahi raihana, te e tuku ana me te e hiahiatia ana, me te āea ana tētahi rōpū te whakawāhia i a ia. Rēhitatia ia i te wāhi e hanga ana te taupānga ipurangi me te kai mahi, kia ōrite ai rāua. Ka tātai te rārangi i ā rātou ake ture i te wā e hanga ana ia, ā, ia wā ka karanga koe i te register, ka āraihia tētahi kāpui e kore e tika ana, me te kī i ia raruraru, ā, ka noho kore hurihia te rārangi i te wā e mahia ana tēnei. Me tūtohu ngā whakamātau ōna ake o te tāpiritanga, kia kore rārangi te extensionContractProblems mō a ia, ā, kia huri te whakawāhia i a ia i te e pā ana ia.