Garatzailearen gida

Erabili zure erakundearen API helbidea eta irismen mugatuko kredentzial bat. Hasi irakurketa-eskaera batekin, egiaztatu erantzuna eta gorde sekretuak iturburu-kodetik eta dokumentazio-adibideetatik kanpo.

Quire-k API publiko bat du: REST HTTPS bidez, OpenAPI 3.1 dokumentu batean deskribatua, gertaeretarako sinatutako webhookekin eta IA-laguntzaileentzako MCP zerbitzariarekin. APIaren erreferentziak endpoint eta gertaera guztiak zerrendatzen ditu.

Helbideak

Erakunde bakoitzak helbide propioa du, eta APIa haren azpian dago:

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

Kredentzialak zehazten du erakundea. Erakunde bateko gakoa beste baten helbidean erabiltzen bada, eskaera ukatu egiten da.

OpenAPI dokumentua edozein erakunderen helbidean dago eskuragarri /api/v1/openapi.json helbidean; beraz, bezero-sorgailuek deitzen ari zaren bertsioa ikusten dute beti.

Autentifikazioa

API gakoak script eta zerbitzaritik zerbitzarirako integrazioetarako dira. Administratzaile batek /admin/integrations/api-keys helbidean sortzen du, haren irismenak aukeratzen ditu eta behin bakarrik ikusten du. Bidali bearer token gisa:

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

Gakoak qk_live_ edo qk_test_ aurrizkiarekin hasten dira. Eman integrazio bakoitzari gako propioa.

OAuth 2.1 saioa hasita duen pertsona baten moduan jarduten duten aplikazioetarako da. Erregistratu bezero bat /admin/integrations/oauth-clients helbidean; gero, erabili PKCE duen baimen-kodearen fluxua (/oauth/authorize, /oauth/token) edo bezero-kredentzialak makina-bezero baterako. Aurkikuntza /.well-known/oauth-authorization-server helbidean dago. Irismen batek tokenak egin dezakeena mugatzen du; ez dio pertsonak baino gehiago egiten uzten.

Irismenak resource:read, resource:write eta resource:delete dira; esaterako, courses:read edo enrolments:write. Lau pribilegiatuak dira eta abisu batekin erakusten dira baimen-pantailan: audit:read, roles:write, tenants:write eta users:delete.

Eskaerak

• Orrialdekatzea: zerrenda guztiak kurtsoreen bidez orrialdekatzen dira. Bidali limit; hartu next_cursor page-tik eta erabili cursor gisa has_more true den bitartean (beheko adibidea). Ez dago offsetik.
• Aldaketak data batetik aurrera: updated_since aukerak une batetik aurrera aldatutakoak ematen ditu. Erabili include_deleted=true parametroarekin batera edo irakurri /<resource>/deletions, zer kendu den jakiteko.
• Kanpoko identifikatzaileak: baliabide gehienek zure external_id propioa onartzen dute; /<resource>/ext:{external_id} bideak horren bidez irakurtzen edo eguneratzen/sortzen du, sinkronizazioak Quire-ren identifikatzaileak gorde behar izan ez ditzan.
• Idempotentzia: bidali Idempotency-Key goiburua POST, PATCH eta DELETE eskaeretan. Gako bera duen berriro saiakerak lehen erantzuna itzultzen du, lana bi aldiz egin beharrean. Multzoko endpointek derrigor behar dute.
• Bertsioak: bertsio nagusia bidean dago (/v1). Haren barruan, aldaketa bateraezin bakoitzak data duen berrikuspen bat du, Quire-Version goiburuaren bidez hautatzen dena, esaterako Quire-Version: 2026-09-20. Goibururik gabe, kredentziala jaulki zeneko berrikuspena jasotzen duzu.

Zerrenda baten orrialde bat:

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

Erroreak

Errore guztiak RFC 9457 arauko arazo-dokumentuak dira:

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

Erabakia hartzeko, erabili egonkorra den code; detail pertsonentzat idatzita dago, erakusteko segurua da eta alda daiteke. Kodea ezagutzen ez baduzu, sailkatu errorea category-ren arabera:

Jarri request_id laguntzarekin harremanetan jartzean.

Webhooks

Harpidetu /admin/webhooks helbidean edo APIaren bidez, /webhook_subscriptions helbidean. Aukeratu gertaerak izenaren arabera (enrolment.created), eremuaren arabera (enrolment.*) edo guztiak (*). Quire-k lehenik webhook.ping bidaltzen du; zure endpointak erantzuten dionean hasten da harpidetza.

Bidalketek Standard Webhooks zehaztapena jarraitzen dute:

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

Bidalketa egiaztatzeko:

1. Eraiki {webhook-id}.{webhook-timestamp}.{raw body} katea jasotako byte zehatzekin, JSONa aztertu aurretik.
2. Kalkulatu HMAC-SHA256 haren gainean, harpidetzaren sekretua erabiliz, eta kodetu base64 formatuan.
3. Konparatu denbora konstantean v1, balio bakoitza webhook-signature goiburuan. Sekretua biratzen ari bada, bi egon daitezke; bat datorren edozein balio da zuzena.
4. Baztertu zure erlojutik bost minutu baino gehiagora dagoen denbora-zigilua.

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

Saihestu bikoizketak webhook-id erabiliz: bidalketa bat behin baino gehiagotan hel daiteke. Gorputzak identifikatzaileak eta laburpen bat ditu; eskuratu baliabidea haren uneko egoera ikusteko. Huts egindako bidalketak berriz saiatzen dira, gero eta tarte handiagoekin, 72 orduz gehienez; bidalketa-erregistrotik berriro erreproduzi daitezke.

MCP

Quire-ren MCP zerbitzaria /mcp helbidean dago erakundearen helbidean, HTTP streaming bidez. MCP bezero batek OAuth zerbitzaria aurkitzen du /.well-known/oauth-protected-resource helbidean; pertsonak saioa hasi eta baimena ematen du OAuth bezero guztietan bezala. Tresnek pertsona horren baimenekin jarduten dute, eta ekintza suntsitzaileek berrespena eskatzen dute. Administratzaileek /admin/integrations/mcp helbidean aukeratzen dute zer tresna dauden erabilgarri.

Planak eta APIa

API gakoak, OAuth bezeroak, webhooks eta MCP zerbitzaria planaren API-eskubidearen barruan daude, eta plan estandar guztiek dute eskubide hori. Eskubidea barne hartzen ez duen plan batean, gakoa, bezeroa edo harpidetza sortzea ukatzen da; REST idazketak eta MCP konexioak ere ukatzen dira. REST irakurketek funtzionatzen jarraitzen dute datuak esportatu ahal izateko. Uko egitea arazo-dokumentu bat da, commerce.plan_entitlement kodearekin eta precondition kategorian.

Luzapenak

Quire-ren jarduera-motak, blokeak, matrikulazio- eta saio-hasiera metodoak, galdera-motak, txostenak, gaiak eta integrazioak luzapen-erregistro berean deklaratzen dira; autoostatatutako instalazio batek ere gehi ditzake. Luzapenak aplikazioan konpilatzen dira: ez dago exekuzioan pluginak kargatzeko mekanismorik, eta ostatatutako erakunde batek ezin du halakorik gehitu. Administratzaileek luzapen bakoitza erakunderako aktibatu edo desaktibatzen dute /admin/extensions helbidean (ikus administratzailearen gida).

Luzapen bat idazteko, hasi packages/integration/extensions/src/sample.ts-ko bloke eta gai laginekin. Aukeratu luzapen-puntua eta irakurri haren kontratua points.ts fitxategian; gero, deklaratu luzapena ID, bertsio eta lizentzia batekin, zer eskaintzen eta behar duen zehaztuta eta erakunde batek desaktiba dezakeen adierazita. Erregistratu web-aplikazioa eta worker-a elkartzen diren lekuan, biak ados egon daitezen. Erregistroak puntu bakoitzaren arauak egiaztatzen ditu eraikitzean eta register deitzen duzun bakoitzean; baliogabea den multzoa ukatu eta arazo guztiak izendatzen ditu, eta erregistroa aldatu gabe uzten du. Luzapenaren probek egiaztatu behar dute extensionContractProblems hutsik dagoela eta desaktibatzeak eragiten duen gauza aldatzen duela.