Gid pou devlopè

Sèvi ak adrès API òganizasyon w lan ak kalifikatif ki gen scope limite. Kòmanse ak yon demann lekti, verifye repons lan, epi pa mete sekrè nan kontwòl kòd sous ni nan egzanp dokimantasyon.

Quire gen yon sèl API piblik: REST sou HTTPS, ki dokimante nan yon fichye OpenAPI 3.1, ak webhook siyen pou evènman ak sèvè MCP pou asistan IA. Referans API a bay lis tout endpoint ak evènman.

Adrès

Chak òganizasyon gen pwòp adrès li, epi API a anba adrès sa a:

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

Se kalifikatif la ki detèmine òganizasyon an. Yo refize yon kle ki fèt pou yon òganizasyon si yo sèvi avè l sou adrès yon lòt.

Yo bay dokiman OpenAPI a nan /api/v1/openapi.json sou adrès nenpòt òganizasyon, konsa jeneratè client yo toujou wè vèsyon API w ap rele a.

Otantifikasyon

Kle API sèvi pou script ak entegrasyon ant sèvè. Yon administratè kreye youn nan /admin/integrations/api-keys, chwazi scope li epi wè li yon sèl fwa. Voye li kòm bearer token:

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

Kle yo kòmanse ak qk_live_ oswa qk_test_. Bay chak entegrasyon pwòp kle pa li.

OAuth 2.1 sèvi pou aplikasyon ki aji kòm yon moun ki konekte. Anrejistre yon client nan /admin/integrations/oauth-clients, epi sèvi ak koule kòd otorizasyon ak PKCE (/oauth/authorize, /oauth/token), oswa kalifikatif client pou yon client machin. Dekouvèt disponib nan /.well-known/oauth-authorization-server. Yon scope limite sa token an kapab fè; li pa janm ba li plis dwa pase moun nan.

Scope yo se resource:read, resource:write ak resource:delete, pa egzanp courses:read oswa enrolments:write. Gen kat scope privilejye epi yo parèt avèk avètisman sou ekran konsantman an: audit:read, roles:write, tenants:write ak users:delete.

Demann

• Paj: tout lis sèvi ak cursor pou pajinasyon. Pase limit, epi mete next_cursor ki nan page kòm cursor toutotan has_more vre (gade egzanp pi ba). Pa gen offset.
• Chanjman depi: updated_since retounen sa ki chanje apre yon lè. Mete include_deleted=true avè l, oswa li /<resource>/deletions, pou konnen sa yo retire.
• Idantifyan ekstèn: pifò resous aksepte pwòp external_id pa w. /<resource>/ext:{external_id} li oswa kreye/mizajou sou baz ID sa a, konsa senkronizasyon pa bezwen konsève idantifyan Quire yo.
• Idempotency: voye header Idempotency-Key nan POST, PATCH ak DELETE. Lè w repete demann nan ak menm kle a, li retounen premye repons lan olye li fè travay la de fwa. Endpoint an gwo yo egzije li.
• Vèsyon: gwo vèsyon an nan chemen an (/v1). Andedan li, chak chanjman ki kraze konpatibilite se yon revizyon ak dat, yo chwazi ak header Quire-Version, pa egzanp Quire-Version: 2026-09-20. San header la, ou jwenn revizyon ki te aktyèl lè yo te bay kalifikatif ou a.

Men yon paj nan lis:

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

Erè

Chak erè se yon dokiman pwoblèm 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..."}

Baze lojik ou sou code, ki estab; detail ekri pou moun, li san danje pou montre epi li ka chanje. Lè w pa rekonèt yon kòd, klase dapre category:

Lè w kontakte sèvis asistans lan, bay request_id la.

Webhook

Abòne nan /admin/webhooks oswa atravè API a nan /webhook_subscriptions. Chwazi evènman pa non (enrolment.created), pa domèn (enrolment.*) oswa tout evènman (*). Quire voye webhook.ping an premye; abònman an kòmanse lè endpoint pa w la reponn.

Livrezon yo swiv spesifikasyon Standard Webhooks la:

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

Pou verifye livrezon an:

1. Avèk octet egzak ou resevwa yo, anvan analiz JSON, konstwi chèn {webhook-id}.{webhook-timestamp}.{raw body}.
2. Kalkile HMAC-SHA256 sou li ak sekrè abònman w lan epi konvèti l an base64.
3. Konpare li ak chak valè v1, nan webhook-signature, san varyasyon tan. Pandan chanjman sekrè, kapab genyen de; nenpòt nan yo ki koresponn valab.
4. Refize timestamp ki gen plis pase senk minit diferans ak revèy pa w.

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

Evite doublon dapre webhook-id: menm livrezon an ka rive plizyè fwa. Kò a gen idantifyan ak yon ti rezime; chèche resous la pou jwenn eta aktyèl li. Yo rekòmanse livrezon ki echwe yo avèk reta k ap ogmante pandan jiska 72 èdtan; ou kapab voye yo ankò nan jounal livrezon an.

MCP

Sèvè MCP Quire a nan /mcp sou adrès òganizasyon an, sou HTTP ki ka voye done an plizyè pati. Yon client MCP dekouvri sèvè OAuth la nan /.well-known/oauth-protected-resource; moun nan konekte epi bay konsantman menm jan ak pou nenpòt client OAuth. Zouti yo aji kòm moun nan, ak pèmisyon li; zouti ki destriktif mande konfimasyon. Administratè yo chwazi ki zouti ki disponib nan /admin/integrations/mcp.

Plan ak API a

Kle API, client OAuth, webhook ak sèvè MCP antre nan dwa API plan an, epi tout plan estanda gen dwa sa a. Nan yon plan ki pa genyen li, yo refize kreye kle, client oswa abònman; yo refize ekriti REST ak koneksyon MCP, men lekti REST kontinye mache pou done yo ka ekspòte. Refiz la se yon dokiman pwoblèm ak kòd commerce.plan_entitlement, nan kategori precondition.

Ekstansyon

Yo deklare pwòp kalite aktivite, blòk, metòd enskripsyon, metòd koneksyon, kalite kesyon, rapò, tèm ak entegrasyon Quire yo nan menm rejis ekstansyon an kote enstalasyon oto-akomode kapab ajoute. Yo konpile ekstansyon yo nan aplikasyon an: pa gen loader plugin pandan ekzekisyon, epi yon òganizasyon ki sèvi ak sèvis akomode pa kapab ajoute youn. Administratè yo aktive oswa dezaktive chak ekstansyon pou òganizasyon yo nan /admin/extensions (gade gid administratè a).

Pou ekri youn, kòmanse ak blòk ak tèm egzanp nan packages/integration/extensions/src/sample.ts. Chwazi pwen ekstansyon an epi li kontra li nan points.ts; apre sa deklare ekstansyon an ak yon ID, vèsyon, lisans, sa li bay ak sa li bezwen, epi si yon òganizasyon kapab dezaktive li. Anrejistre li kote yo rasanble aplikasyon web la ak worker a pou yo dakò. Rejis la verifye pwòp règ chak pwen lè yo bati li ak chak fwa ou rele register; si yon seri pa valab, li refize li epi bay non chak pwoblèm, san li pa chanje rejis la. Tès ekstansyon an ta dwe verifye extensionContractProblems vid pou li epi dezaktive li chanje sa li afekte.