Rêbeberiya pêşeniker

Navnivîsa API ya rêxistina xwe û têketnaverek bi scope bikar bîne. Bi daxwazeke dixwînê dest pê bike, bersivê çawas bike, û nepûran derveyî kontrolya source û nîşaneyên belgeyan veşîne.

Quire APIyeke govzayî heye: REST li ser HTTPS, bi belgeyeke OpenAPI 3.1 ve şîrokirî, bi webhookên qeydkirî ji bo roodûyan û serverek MCP ji bo alîkeryên AI re. Rêbera API her kotil û roodûyek li lîsteyê dide.

Navnivîş

Her rêxistinek navnivîsa xwe heye, û API di jêrî wê ye:

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

Têketnaver rêxistinê diyare. Kiliteke ji bo rêxistinek ku di navnivîsa din de tê bikaranîn nayê qebûlkirin.

Belgeya OpenAPI di navnivîsa her rêxistinê de di /api/v1/openapi.json de tê berdan, ji ber vê daxwazkerên sernakewtî her dem nûşeya ku tu didê dibînin.

Nasnamekirin

Kilîtên API ji bo skrîpt û yekkêşinên server bo server in. Rêveberek yekê di /admin/integrations/api-keys de çêdike, scopeên wê hilbijêre û carekê wê dibîne. Wê wek bearer token bişîne:

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

Kilît bi qk_live_ an qk_test_ dest pê dikin. Ji bo her yekkêşinê kilîta xwe bide.

OAuth 2.1 ji bo sepanên ku di navenda kesekî ku têketiye re karekî dike. Mirovek di /admin/integrations/oauth-clients de qeyd bike, paş rêya koda destûrê bi PKCE bikar bîne (/oauth/authorize, /oauth/token), an têketnaverên mirov ji bo mirovekî makîn. Dîtin di /.well-known/oauth-authorization-server de. Scope tê deyînî çi ku token dikare bike; her tim nade zêdetir ji kes.

Scope in resource:read, resource:write û resource:delete, mîna courses:read an enrolments:write. Çûar taybet in û di ekrana destûrê de bi hişyariyê tên nîşan: audit:read, roles:write, tenants:write û users:delete.

Daxwaz

• Rêzibeşandin: her lîstek bi cursor tê dabeşkirin. limit bişîne, paş next_cursor ji page wek cursor bişîne gava has_more rast e (nîşanerê jêrîn). Nîşaneyek tune.
• Guhertin ji demekê: updated_since tiştên ku dûpiştî demekî guhertiye dide vegere. Wê bi include_deleted=true re bikar bîne, an /<resource>/deletions dixwîne, ta fasîtkiriyan bibiznî.
• Nîşanerên derve: pir sarveyan external_id ya xwe qebûl dikin, û /<resource>/ext:{external_id} bi wê dixwîne an dike navdar, ji ber vê hevbestandin her tim nîşanerên Quire parastîne pêwîst nake.
• Idempotency: serpeyveke Idempotency-Key di POST, PATCH û DELETE de bişîne. Diceribînek bi heman kilî re yekem dîsa dide vegere bila kar du car ne. Kotilên komevê wê pêwîst dikin.
• Nûşe: nûşeya sereke di reçikê de ye (/v1). Di wê de, her guhertinekî şêxşam revîsyoneke bi dîrok heye, bi serpeyveya Quire-Version ve tê hilbijartin, mîna Quire-Version: 2026-09-20. Bê serpeyvê tu revîsyonekê digirî ku dîmeke ku têketnavera te hatiye danîn.

Rûpelek ji lîsteyê:

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

Çelt

Her çelt belgeyeke pirsgirêkê ya RFC 9457 ye:

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

Li gorî code ve biguhere, ew sabit e; detail ji bo kesan nivîsî ye, xweş e ku wan bîne, û dikare biguherîne. Gava codek nas nakî, bi category ve grup bike:

request_id rêkê girê de gava bi pêşniyarê têkevî.

Webhook

Di /admin/webhooks de abone bike, an bi rêkî API di /webhook_subscriptions de. Roodûyan bi nav (enrolment.created), bi beş (enrolment.*) an hemû (*) hilbijêre. Quire berê webhook.ping dişîne; abonebûn dûpiştî ku endpointa te wê bersiv bike dest pê dike.

Şandin bişopînin specifikasyona Standard Webhooks:

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

Ji bo çawaskirina şandekek:

1. {webhook-id}.{webhook-timestamp}.{raw body} ji hejmara yek hiştartî, berî parçekirina JSON, biafirîne.
2. Bi nepûra abonebûna xwe li ser wê HMAC-SHA256 hesib û wê base64 bike.
3. Bi her nirxa v1, di webhook-signature de bi demê sabit veñave. Di biguherîna nepûrê de du dikarin bibe; yek ji wan rast e.
4. Damêteke ku ji saetê te zêdetir î panj deqîqe ye rad bike.

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

Bi webhook-id ve pirsgirêkên duplikat rake: şandekek dikare zêdetir careyan were. Badan nîşaner û kurzînekî kurt tê; sarveyê ji bo derengama niha bikişîne. Şandinên ne serket bi backoff heta 72 saetan diceribînin, û ji loga şandinê were nûvekirin.

MCP

Servera MCP ya Quire di navnivîsa rêxistinê de di /mcp ye, bi rêkî streamable HTTP. Daxwazkerek MCP servera OAuth ji /.well-known/oauth-protected-resource dide dîtin, û kes wek bi heman reşî têket û destûr dide wek her daxwazkerek OAuth. Amûr bi navenda wê kesê karekî dike, bi destûran, û amûrên tahribkar daxwazê pejûh dikin. Rêveber di /admin/integrations/mcp de hilbijêdin kî amûr berdest in.

Plan û API

Kilîtên API, daxwazkerên OAuth, webhook û servera MCP di mafeya API ya planê de ne, û her plana standard wê tê de ye. Li planek ku wê tune, çêkirina kilitek, mirovek an abonebûnek nayê qebûlkirin, nivîsandinên REST û girêtiyên MCP tên raqûlikirin, û dixwîninên REST dewam dikin ta datayek hiştartî bimîne. Raqûlik belgeyeke pirsgirêkê ye bi koda commerce.plan_entitlement, di kategoriya precondition de.

Pêvek

Cureyên çalakiyê, blok, geberiyên nûskirin, geberiyên têketinê, cureyên pirs, rapor, tema û yekkêşinên xwe ya Quire di heman reçestera pêvekê de tên derdikirin, ku sazkirinek ji aliyê xwe ve dikare zêde bike. Pêvek tên komkirin di nava: barbereke plugînê di demê ranawayê tune, û rêxistinek hatiye mîhankirin nikare yekê zêde bike. Rêveber di /admin/extensions de her pêvek ji bo rêxistina xwe veke an rake (binêre rêbeberiya rêveber).

Ji bo nivîsariya yek, ji bloka anîmûn û temaya di packages/integration/extensions/src/sample.ts de dest pê bike. Noda pêvekê hilbijêre û peymana wê di points.ts de bixwîne, paş pêvek bi id, nûşe, lesan, tiştên ku pêşkêş dike û daxwaz dike, û ê ya ku rêxistin dikare veke an rake, derdike. Wê di cîgeke ku nivîsbariya web û karmer tên avazkirin de qeyd bike, ta herdu rast bên. Reçester gava tê biafirîne û her car ku tu register titikînî riyên nodê yekê ceribîne, komek nayê qebûlkirin ku nebes e bi her pirsgirêkê bi nav, û reçester biguherîne naqetîne gava ew çêt. Tehtên xwe ya pêvek divê piştrînin ku extensionContractProblems ji bo wê vala ye û ku rake wê tiştên ku wê ser bilind e biguherîne.