Ntuziaka onye mmepụta

Jiri adreesị API otu gị na nzere nwere oke. Bido na arịrịọ ọgụgụ, lelee nzaghachi, debekwa nzuzo n’èzí njikwa isi mmalite na ihe atụ akwụkwọ.

Quire nwere otu API ọha: REST site na HTTPS, nke akwụkwọ OpenAPI 3.1 kọwara, na webhook e binyere aka maka ihe omume na sava MCP maka ndị enyemaka AI. Ntụaka API na-edepụta endpoint na ihe omume ọ bụla.

Adreesị

Otu ọ bụla nwere adreesị nke ya, API bi n’okpuru ya:

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

Nzere na-ekpebi otu. A jụrụ igodo nke otu e ji na adreesị nke ọzọ.

A na-enye akwụkwọ OpenAPI na /api/v1/openapi.json na adreesị otu ọ bụla, ka ndị na-emepụta client na-ahụ ụdị ị na-akpọ mgbe niile.

Nyocha njirimara

Igodo API bụ maka scripts na njikọta sava na sava. Onye nchịkwa na-emepụta otu na /admin/integrations/api-keys, na-ahọrọ scopes ya, ma na-ahụ ya otu ugboro. Ziga ya dịka token bearer:

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

Igodo na-amalite na qk_live_ ma ọ bụ qk_test_. Nye njikọta ọ bụla igodo nke ya.

OAuth 2.1 bụ maka ngwa na-eme ihe dịka onye banyere. Debanye client na /admin/integrations/oauth-clients, emesịa jiri authorization code flow na PKCE (/oauth/authorize, /oauth/token), ma ọ bụ nzere client maka client igwe. Nchọpụta dị na /.well-known/oauth-authorization-server. Scope na-ebelata ihe token nwere ike ime; ọ dịghị mgbe ọ na-ahapụ ya ime karịa ihe onye ahụ nwere ike.

Scopes bụ resource:read, resource:write na resource:delete, dịka courses:read ma ọ bụ enrolments:write. Anọ nwere ikike pụrụ iche ma na-egosi na ịdọ aka ná ntị na ihuenyo nkwenye: audit:read, roles:write, tenants:write na users:delete.

Arịrịọ

• Pagination: ndepụta ọ bụla bụ cursor paginated. Nyefee limit, emesịa next_cursor site na page dịka cursor mgbe has_more bụ eziokwu (ihe atụ n’okpuru). Enweghị offset.
• Mgbanwe kemgbe: updated_since na-alaghachi ihe gbanwere mgbe oge. Jikọọ ya na include_deleted=true, ma ọ bụ gụọ /<resource>/deletions, ka ịmata ihe e wepụrụ.
• Nchọpụta mpụga: ọtụtụ akụ na-anabata external_id nke gị, na /<resource>/ext:{external_id} na-agụ ma ọ bụ upserts site na ya, ka mmekọrịta ghara ịchọ ịchekwa nchọpụta Quire.
• Idempotency: ziga nkụnye Idempotency-Key na POST, PATCH na DELETE. Mgbalị ọzọ na otu igodo na-alaghachi nzaghachi mbụ kama ịrụ ọrụ ugboro abụọ. Endpoints bulk chọrọ ya.
• Ụdị: ụdị ukwu dị na ụzọ (/v1). N’ime ya, mgbanwe na-emebi ọ bụla bụ revision nwere ụbọchị, a na-ahọrọ na nkụnye Quire-Version, dịka Quire-Version: 2026-09-20. Na-enweghị nkụnye ị na-enweta revision dị ugbu a mgbe e nyere nzere gị.

Peeji nke ndepụta:

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

Njehie

Njehie ọ bụla bụ akwụkwọ nsogbu 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..."}

Alaka na code, nke kwụsiri ike; e dere detail maka mmadụ, ọ dị nchebe igosi ha, ọ nwekwara ike ịgbanwe. Mgbe ị mataghị koodu, tinye na category:

Kwuo request_id mgbe ị kpọtụrụ nkwado.

Webhooks

Denye aha na /admin/webhooks, ma ọ bụ site na API na /webhook_subscriptions. Họrọ ihe omume site n’aha (enrolment.created), site na mpaghara (enrolment.*) ma ọ bụ niile (*). Quire na-eziga webhook.ping nke mbụ; ndenye aha na-amalite ozugbo endpoint gị zara ya.

Nnyefe na-agbaso nkọwa Standard Webhooks:

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

Iji nyochaa nnyefe:

1. Wuo eriri {webhook-id}.{webhook-timestamp}.{raw body} site na bytes kpọmkwem anatara, tupu nyocha JSON ọ bụla.
2. Gbakọọ HMAC-SHA256 n’elu ya na nzuzo ndenye aha gị, mee ya base64.
3. Tụnyere na uru v1, ọ bụla na webhook-signature n’oge na-adịgide. Abụọ nwere ike ịdị n’oge ntụgharị nzuzo; nke ọ bụla dabara dị irè.
4. Jụ timestamp karịrị nkeji ise site na elekere gị.

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

Wepụ oyiri na webhook-id: nnyefe nwere ike ịbịarute karịa otu ugboro. Ahụ na-ebu nchọpụta na nchịkọta mkpụmkpụ; weta akụ maka ọnọdụ ya ugbu a. A na-anwale nnyefe dara ọzọ na backoff ruo awa 72, a pụkwara ịkpọghachi ha site na ndekọ nnyefe.

MCP

Sava MCP Quire dị na /mcp na adreesị otu, site na HTTP a ga-ebugharị. Client MCP na-achọpụta sava OAuth site na /.well-known/oauth-protected-resource, onye ahụ na-abanye ma kweta dịka client OAuth ọ bụla. Ngwa na-eme ihe dịka onye ahụ, na ikike ha, ngwa na-emebi emebi na-arịọ nkwenye. Ndị nchịkwa na-ahọrọ ngwa dị na /admin/integrations/mcp.

Atụmatụ na API

Igodo API, clients OAuth, webhooks na sava MCP bụ nke ikike API atụmatụ, atụmatụ ọkọlọtọ ọ bụla gụnyere ya. Na atụmatụ na-enweghị ya, a jụrụ imepụta igodo, client ma ọ bụ ndenye aha, a jụrụ ederede REST na njikọ MCP, ọgụgụ REST na-aga n’ihu ka data wee nọgide na-ebupụ. Ọjụjụ bụ akwụkwọ nsogbu na koodu commerce.plan_entitlement, na otu precondition.

Extensions

A na-akpọsa ụdị ọrụ Quire, blocks, ụzọ ndebanye aha, ụzọ nbanye, ụdị ajụjụ, akụkọ, themes na njikọta site n’otu ndekọ extension nke nrụnye a na-elekọta n’onwe ya nwere ike itinye na ya. A na-achịkọta Extensions n’ime: enweghị loader plugin runtime, otu a na-elekọta enweghị ike itinye otu. Ndị nchịkwa na-agbanye extension ọ bụla ma ọ bụ gbanyụọ maka otu ha na /admin/extensions (lee ntuziaka onye nchịkwa).

Iji dee otu, bido na block ihe atụ na theme na packages/integration/extensions/src/sample.ts. Họrọ ebe extension wee gụọ contract ya na points.ts, emesịa kpọsaa extension na id, ụdị, licence, ihe ọ na-enye ma chọọ, na ma otu nwere ike ịgbanyụ ya. Debanye ya ebe a na-ahazi ngwa weebụ na worker, ka ha abụọ kwekọrịta. Ndekọ na-enyocha iwu nke ebe ọ bụla mgbe e wuru ya na mgbe ọ bụla ị kpọrọ register, na-ajụ otu na-agaghị adị irè na nsogbu ọ bụla akpọrọ, wee hapụ ndekọ na-agbanweghị mgbe o mere ya. Ule extension kwesịrị ikwenye na extensionContractProblems tọgbọ chakoo maka ya na na ịgbanyụ ya na-agbanwe ihe ọ na-emetụta.