Gwida tal-iżviluppatur

Uża l-indirizz API tal-organizzazzjoni tiegħek u kredenzjali bi skop limitat. Ibda b’talba ta’ qari, iċċekkja r-risposta, u żomm is-sigrieti barra mill-kontroll tas-sors u l-eżempji tad-dokumentazzjoni.

Quire għandha API pubblika waħda: REST fuq HTTPS, deskritta b’dokument OpenAPI 3.1, b’webhooks iffirmati għall-avvenimenti u server MCP għal assistenti tal-AI. Ir-referenza tal-API telenka kull endpoint u avveniment.

Indirizzi

Kull organizzazzjoni għandha l-indirizz tagħha, u l-API tgħix taħtu:

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

Il-kredenzjali tiddeċiedi l-organizzazzjoni. Ċavetta għal organizzazzjoni waħda użata fl- indirizz ta’ oħra tiġi rifjutata.

Id-dokument OpenAPI jingħata f’/api/v1/openapi.json fuq kwalunkwe indirizz ta’ organizzazzjoni, biex il-ġeneraturi tal-klijenti dejjem jaraw il-verżjoni li inti qed issejjaħ.

Awtentikazzjoni

Ċwievet tal-API huma għal skripts u integrazzjonijiet server-to-server. Amministratur joħloq waħda f’/admin/integrations/api-keys, jagħżel l- iskops tagħha, u jaraha darba. Ibgħatha bħala bearer token:

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

Iċ-ċwievet jibdew qk_live_ jew qk_test_. Agħti lil kull integrazzjoni ċ-ċavetta tagħha.

OAuth 2.1 huwa għal applikazzjonijiet li jaġixxu bħala persuna mdaħħla. Irreġistra klijent f’/admin/integrations/oauth-clients, imbagħad uża l-fluss tal-kodiċi tal-awtorizzazzjoni b’PKCE (/oauth/authorize, /oauth/token), jew kredenzjali tal-klijent għal klijent ta’ magna. L-iskoperta tinsab f’ /.well-known/oauth-authorization-server. Skop jiddejjaq x’token jista’ jagħmel; qatt ma jħallih jagħmel aktar milli setgħet il-persuna.

L-iskops huma resource:read, resource:write u resource:delete, pereżempju courses:read jew enrolments:write. Erbgħa huma privileġġjati u jintwerew bi twissija fuq l-iskrin tal-kunsens: audit:read, roles:write, tenants:write u users:delete.

Talbiet

• Paġinazzjoni: kull lista hija paġinata b’cursor. Għaddi limit, imbagħad il- next_cursor minn page bħala cursor sakemm has_more ikun true (eżempju hawn taħt). M’hemm l-ebda offset.
• Bidliet minn meta: updated_since jirritorna x’inbidel wara ħin. Qabbilha ma’ include_deleted=true, jew aqra /<resource>/deletions, biex titgħallem x’tneħħa.
• Identifikaturi esterni: ħafna riżorsi jaċċettaw l-external_id tiegħek, u /<resource>/ext:{external_id} jaqra jew jagħmel upsert bih, biex sync qatt ma jeħtieġ jaħżen l-identifikaturi ta’ Quire.
• Idempotenza: ibgħat header Idempotency-Key fuq POST, PATCH u DELETE. Retry bl-istess ċavetta jirritorna l-ewwel risposta minflok ma jagħmel ix-xogħol darbtejn. Endpoints bulk jeħtieġuha.
• Verżjonijiet: il-verżjoni maġġuri tinsab fil-mogħdija (/v1). Fiha, kull bidla li tkisser hija reviżjoni datata, magħżula bl-header Quire-Version, pereżempju Quire-Version: 2026-09-20. Mingħajr l-header tieħu ir-reviżjoni attwali meta nħarġet il-kredenzjali tiegħek.

Paġna ta’ lista:

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

Żbalji

Kull żball huwa dokument ta’ problema 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..."}

Fergħa fuq code, li huwa stabbli; detail jinkiteb għan-nies, sigur biex turihom, u jista’ jinbidel. Meta ma tagħrafx kodiċi, iġbor fuq category:

Ikkwota request_id meta tikkuntattja l-appoġġ.

Webhooks

Abbona f’/admin/webhooks, jew permezz tal-API f’ /webhook_subscriptions. Agħżel l-avvenimenti bl-isem (enrolment.created), biż-żona (enrolment.*) jew kollha (*). Quire l-ewwel tibgħat webhook.ping; l- abbonament jibda ladarba l-endpoint tiegħek iwieġeb.

Il-kunsinni jsegwu l-ispeċifikazzjoni Standard Webhooks:

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

Biex tivverifika kunsinna:

1. Ibni s-sekwenza {webhook-id}.{webhook-timestamp}.{raw body} mill- bytes eżatti riċevuti, qabel kwalunkwe parsing JSON.
2. Ikkalkula HMAC-SHA256 fuqha bis-sigriet tal-abbonament tiegħek, u għamilha base64.
3. Qabbel ma’ kull valur v1, f’webhook-signature f’ħin kostanti. Jista’ jkun hemm tnejn waqt rotazzjoni ta’ sigriet; kull tqabbila hija valida.
4. Irretja timestamp aktar minn ħames minuti mill-arloġġ tiegħek.

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

Idduplika fuq webhook-id: kunsinna tista’ tasal aktar minn darba. Il-body iġorr identifikaturi u sommarju qasir; iġbed ir-riżorsa għall-istat attwali tagħha. Kunsinni falluti jerġgħu jiġu ppruvati b’backoff sa 72 siegħa, u jistgħu jerġgħu jintlagħbu mil-log tal-kunsinna.

MCP

Is-server MCP ta’ Quire jinsab f’/mcp fuq l-indirizz tal-organizzazzjoni, fuq HTTP streamabbli. Klijent MCP jiskopri s-server OAuth minn /.well-known/oauth-protected-resource, u l-persuna tidħol u tikkunsenti bħal ma’ kwalunkwe klijent OAuth. L-għodod jaġixxu bħal dik il-persuna, bil-permessi tagħhom, u għodod distruttivi jitolbu konferma. L-amministraturi jagħżlu liema għodod huma disponibbli f’/admin/integrations/mcp.

Pjanijiet u l-API

Ċwievet tal-API, klijenti OAuth, webhooks u s-server MCP huma tal-intitolament API tal-pjan, u kull pjan standard jinkludih. Fuq pjan mingħajru, il-ħolqien ta’ ċavetta, klijent jew abbonament jiġi rifjutat, kitbiet REST u konnessjonijiet MCP huma rifjutati, u qari REST ikompli jaħdem biex id-data tibqa’ esportabbli. Ir-rifjut huwa dokument ta’ problema bil- kodiċi commerce.plan_entitlement, fil-kategorija precondition.

Estensjonijiet

It-tipi ta’ attività ta’ Quire stess, blokki, metodi ta’ reġistrazzjoni, metodi ta’ dħul, tipi ta’ mistoqsijiet, rapporti, temi u integrazzjonijiet huma ddikjarati permezz tal-istess reġistru ta’ estensjonijiet li installazzjoni self-hosted tista’ żżid miegħu. L-estensjonijiet huma kkompilati ġewwa: m’hemm l-ebda loader ta’ plugins f’ħin it-tħaddim, u organizzazzjoni hosted ma tistax iżżid waħda. L-amministraturi jixgħelu jew jitfu kull estensjoni għall-organizzazzjoni tagħhom f’ /admin/extensions (ara l-gwida tal-amministratur).

Biex tikteb waħda, ibda mill-blokka kampjun u t-tema f’ packages/integration/extensions/src/sample.ts. Agħżel il-punt tal-estensjoni u aqra l-kuntratt tiegħu f’points.ts, imbagħad iddikjara l-estensjoni b’id, verżjoni, liċenzja, x’tipprovdi u teħtieġ, u jekk organizzazzjoni tistax titfiha. Irreġistraha fejn l-applikazzjoni web u l-worker huma komposti, biex it-tnejn jaqblu. Ir-reġistru jiċċekkja r-regoli ta’ kull punt meta jinbena u kull meta tissejjaħ register, jirrifjuta sett li jkun invalidu b’kull problema msemmija, u jħalli r-reġistru mhux mibdul meta jagħmel hekk. It-testijiet tal-estensjoni għandhom jasserixxu li extensionContractProblems huwa vojt għaliha u li t-tifi tagħha jbiddel dak li taffettwa.