Ductor programmatoris

Utere addressa API collegii tui et signo ambitu instructo. Incipe a petitione legendi, responsum inspice, et arcana extra custodiam codicis et exemplaria documentationis serva.

Quire unam API publicam habet: REST super HTTPS, descriptam documento OpenAPI 3.1, cum retibus textoriis signatis pro eventibus et servitio MCP pro adiutoribus AA. Referentia API omne punctum terminale et omne eventum enumerat.

Addressa

Quodque collegium propriam addressam habet, et API sub ea vivit:

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

Signum collegium decidit. Clavis pro uno collegio in addressa alterius usa refuitur.

Documento OpenAPI in /api/v1/openapi.json in addressa cuiusque collegii praebetur, ita ut generatores clientium semper eam versionem videant quam vocas.

Authenticatio

Claves API pro scriptis et integrationibus inter ministratores sunt. Una administrator in /admin/integrations/api-keys creat, ambitus eius eligit, et eam semel videt. Eam ut signum ferentem mitte:

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

Claves qk_live_ aut qk_test_ incipiunt. Quaeri integrationi tuam propriam clavem da.

OAuth 2.1 pro applicationibus est quae ut persona consessa agunt. Clientem in /admin/integrations/oauth-clients inscribe, deinde fluxum codicis auctorizationis cum PKCE (/oauth/authorize, /oauth/token) utere, aut indicium clientis pro cliente machinali. Inquisitio in /.well-known/oauth-authorization-server est. Ambitus id angustat quod signum facere possit; numquam plus facere sinit quam persona posset.

Ambitus sunt resource:read, resource:write et resource:delete, verbi causa courses:read aut enrolments:write. Quattuor privilegiati sunt et cum monitione in facie consensus monstrantur: audit:read, roles:write, tenants:write et users:delete.

Petitiones

• Paginatio: quaelibet lista paginatur in indice cursoris. Trahe limit, deinde next_cursor ex page ut cursor dum has_more verum est (exemplum infra). Nulla offset est.
• Mutationes ex: updated_since reddit id quod post tempus mutatum est. Ei include_deleted=true iunge, aut /<resource>/deletions lege, ut scias quid remotum sit.
• Identificatores externi: pleraque rerum tuum proprium external_id accipiunt, et /<resource>/ext:{external_id} eo legit aut inserit, ita ut sync numquam identificatores Quire servare egeat.
• Idempotentia: mitte caput Idempotency-Key in POST, PATCH et DELETE. Iteratio cum eadem clave primum responsum reddit potius quam opus bis faciat. Puncta terminalia massa id requirunt.
• Versiones: versio maior in via est (/v1). Intra eam quaeque mutatio frangens revisio data instruitur, cum capite Quire-Version electa, verbi causa Quire-Version: 2026-09-20. Sine capite eam versionem quae cum signum tuum datur vigebat accipis.

Pagina listae:

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

Errores

Quisque error documentum problematis RFC 9457 est:

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

In code divide, quod stabile est; detail hominibus scriptum est, iis monstrare tutum, et mutari potest. Cum codicem non agnoveris, in category divide:

request_id cita cum auxilium petis.

Retia textoria

In /admin/webhooks subscripto, aut per API in /webhook_subscriptions. Elige eventus nomine (enrolment.created), per locum (enrolment.*) aut omnes (*). Quire primum webhook.ping mittit; subscriptio incipit cum punctum terminale tuum ei respondet.

Traditiones specificationem Standard Webhooks sequuntur:

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

Ut traditionem probes:

1. Stringe {webhook-id}.{webhook-timestamp}.{raw body} ex iis ipsis bytis acceptis, ante quamquam analysim JSON.
2. HMAC-SHA256 super eo cum arcano subscriptionis tuae computa, et id in base64 verte.
3. Cum quoque valore v1, in webhook-signature tempore constante compara. Duo esse possunt durante rotatione arcana; utrumque conveniens est.
4. Tempus signi plus quinque minutis a tuo horologio recusare.

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

In webhook-id deduplicare: traditio saepius venire potest. Corpus identificatores et breve summarium portat; rem pro statu eius nunc pete. Traditiones fractae cum retardatione usque ad 72 horas iterantur, et ex libro traditionis repeti possunt.

MCP

Servitium MCP Quire in /mcp in addressa collegii est, super HTTP fluens. Client MCP servitium OAuth in /.well-known/oauth-protected-resource invenit, et persona consentit ut in quovis cliente OAuth. Instrumenta ut ea persona agunt, cum eis potestatibus, et instrumenta destructiva confirmationem poscunt. Administratores quae instrumenta praesto sint in /admin/integrations/mcp eligunt.

Consilia et API

Claves API, clientes OAuth, retia textoria et servitium MCP ad ius API consilii pertinent, et omne consilium standard id continet. In consilio sine eo, creatio clavis, clientis aut subscriptionis refuitur, scripturae REST et coniunctiones MCP refuuntur, et lectiones REST pergiunt ut data exportari possint. Refutatio est documentum problematis cum code commerce.plan_entitlement, in categoria precondition.

Extensiones

Genera actuum ipsius Quire, lateres, modi inscriptionis, modi introitus, genera quaestionum, commentaria, themata et integrationes per eundem registrum extensionum declarantur cui institutio apud se hospitata addere potest. Extensiones compilantur: nullus est onerator extensorum in cursu rei, et collegium hospitatum addere non potest. Administratores quamque extensionem pro collegio suo in /admin/extensions aperit aut claudit (vide ductionem administratoris).

Ut unam scribas, incipe a lateri et themate exemplari in packages/integration/extensions/src/sample.ts. Punctum extensionis elige et eius pactum in points.ts lege, deinde extensionem cum id, versione, licentia, eo quod praebet et requirit, et utrum collegium eam claudere liceat declara. Eam ubi applicatio textoria et operarius componuntur inscribe, ita ut uterque consentiat. Registrum quaeque regulae puncti ipsius inspicit cum aedificatur et quotiens register vocas, set refuit quae invalida esset cum omne problema nominatum, et registrum mutatum relinquit cum id facit. Testus ipsius extensionis debent adserere extensionContractProblems pro ea vacuum esse et eius clausuram id mutare quod afficiat.