Fejlesztői útmutató

Használja szervezete API-címét és a megfelelő hatókörű hitelesítő adatot. Először olvasási kéréssel kezdjen, ellenőrizze a választ, és tartsa a titkokat a forráskódon és dokumentációs példákon kívül.

A Quire egy nyilvános API-t kínál: HTTPS-en keresztüli REST-et, amelyet az OpenAPI 3.1 dokumentum ír le, eseményekhez aláírt webhookokkal és MI-asszisztensek számára MCP-kiszolgálóval. Az API-referencia felsorolja az összes végpontot és eseményt.

Címek

Minden szervezetnek saját címe van, az API pedig annak alútvonalán található:

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

A hitelesítő adat határozza meg a szervezetet. Ha az egyik szervezet kulcsát egy másik szervezet címén használja, a kérést elutasítjuk.

Az OpenAPI-dokumentum bármely szervezeti címen elérhető a /api/v1/openapi.json útvonalon, így a kliensgenerátorok mindig az éppen használt verziót látják.

Hitelesítés

Az API-kulcsok szkriptekhez és szerverek közötti integrációkhoz valók. A rendszergazda a /admin/integrations/api-keys oldalon hozza létre, kiválasztja a hatóköröket, és csak egyszer láthatja. Küldje bearer tokenként:

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

A kulcsok qk_live_ vagy qk_test_ előtaggal kezdődnek. Minden integrációnak külön kulcsot adjon.

Az OAuth 2.1 olyan alkalmazásokhoz való, amelyek egy bejelentkezett személy nevében járnak el. Regisztráljon klienst itt: /admin/integrations/oauth-clients, majd használja a PKCE-vel védett authorization code folyamatot (/oauth/authorize, /oauth/token), vagy gépi klienshez a client credentials módot. A szolgáltatás felfedezése itt érhető el: /.well-known/oauth-authorization-server. A hatókör korlátozza a token műveleteit; a személy jogosultságainál többet soha nem engedélyez.

A hatókörök: resource:read, resource:write és resource:delete, például courses:read vagy enrolments:write. Négy kiemelt hatókör figyelmeztetéssel jelenik meg a jóváhagyási oldalon: audit:read, roles:write, tenants:write és users:delete.

Kérések

• Lapozás: minden lista kurzorral lapozható. Adja meg a limit értékét, majd a next_cursor értékét a page objektumból küldje cursor néven, amíg a has_more igaz (példa lent). Nincs offset.
• Változások egy időpont óta: az updated_since visszaadja az adott időpont utáni változásokat. Használja együtt az include_deleted=true értékkel, vagy olvassa a /<resource>/deletions végpontot az eltávolított elemek megismeréséhez.
• Külső azonosítók: a legtöbb erőforrás elfogadja a saját external_id értékét; a /<resource>/ext:{external_id} végpont pedig lekéri vagy frissítve létrehozza az elemet, így a szinkronizálásnak nem kell tárolnia a Quire-azonosítókat.
• Idempotencia: küldjön Idempotency-Key fejlécet POST, PATCH és DELETE kérésekhez. Az azonos kulccsal történő újrapróbálás az első választ adja vissza, nem végzi el ismét a műveletet. A tömeges végpontoknál kötelező.
• Verziók: a fő verzió az útvonalban szerepel (/v1). Ezen belül minden visszafelé nem kompatibilis változás dátummal jelölt felülvizsgálat, amelyet a Quire-Version fejléc választ ki; például Quire-Version: 2026-09-20. A fejléc nélkül a hitelesítő adat kiadásakor aktuális felülvizsgálatot kapja.

Egy listaoldal:

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

Hibák

Minden hiba RFC 9457 problem dokumentum:

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

A stabil code alapján kezelje a hibát; a detail embereknek szól, megmutatható nekik, és változhat. Ismeretlen kód esetén a category alapján sorolja be:

Ügyfélszolgálati megkereséskor adja meg a request_id értékét.

Webhookok

Iratkozzon fel a /admin/webhooks oldalon vagy az API /webhook_subscriptions végpontján. Válassza ki az eseményeket név szerint (enrolment.created), terület szerint (enrolment.*) vagy mindet (*). A Quire először webhook.ping eseményt küld; a feliratkozás akkor indul, amikor a végpont válaszol rá.

A kézbesítés a Standard Webhooks specifikációt követi:

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

Kézbesítés ellenőrzése:

1. Állítsa össze a {webhook-id}.{webhook-timestamp}.{raw body} karakterláncot a kapott bájtokból, a JSON feldolgozása előtt.
2. Számítson HMAC-SHA256 értéket a feliratkozási titokkal, majd kódolja base64 formátumra.
3. Állandó idejű összehasonlítással vesse össze a v1, értékeket a webhook-signature fejlécben. Titokcsere alatt kettő is lehet; bármelyik egyezés érvényes.
4. Utasítsa el az öt percnél régebbi vagy jövőbeli időbélyeget.

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

Az ismétlődések kiszűréséhez használja a webhook-id értékét: egy kézbesítés többször is megérkezhet. A törzs azonosítókat és rövid összefoglalót tartalmaz; kérje le az erőforrást az aktuális állapotért. A sikertelen kézbesítéseket a rendszer növekvő várakozási idővel legfeljebb 72 óráig próbálja újra; a kézbesítési naplóból újra lejátszhatók.

MCP

A Quire MCP-kiszolgálója a szervezeti címen található /mcp útvonalon, streamelhető HTTP-n keresztül. Az MCP-kliens a /.well-known/oauth-protected-resource címen fedezi fel az OAuth-kiszolgálót; a felhasználó bejelentkezik és jóváhagyja a hozzáférést, mint bármely OAuth-kliensnél. Az eszközök a felhasználó nevében, az ő jogosultságaival működnek, a romboló műveletek pedig megerősítést kérnek. A rendszergazdák a /admin/integrations/mcp oldalon választják ki az elérhető eszközöket.

Csomagok és API

Az API-kulcsok, OAuth-kliensek, webhookok és az MCP-kiszolgáló a csomag API-jogosultságához tartoznak, és minden normál csomag tartalmazza. E jogosultság nélküli csomagban kulcs, kliens vagy feliratkozás létrehozását, REST-írást és MCP-kapcsolatot elutasítjuk, de a REST-olvasás tovább működik, így az adatok exportálhatók. Az elutasítás problem dokumentum, commerce.plan_entitlement kóddal és precondition kategóriával.

Bővítmények

A Quire beépített tevékenységtípusai, blokkjai, beiratkozási és bejelentkezési módjai, kérdéstípusai, jelentései, témái és integrációi ugyanazon bővítmény-regiszteren keresztül vannak deklarálva, amelyhez egy saját üzemeltetésű telepítés is hozzáadhat. A bővítmények fordításkor kerülnek be: nincs futásidejű bővítménybetöltő, és a hosztolt szervezet nem adhat hozzá új bővítményt. A rendszergazdák a /admin/extensions oldalon kapcsolhatják be vagy ki az egyes bővítményeket (lásd a rendszergazdai útmutatót).

Saját bővítmény készítéséhez induljon a packages/integration/extensions/src/sample.ts mintablokkjából és témájából. Válassza ki a bővítési pontot, olvassa el a szerződését a points.ts fájlban, majd deklarálja a bővítményt azonosítóval, verzióval, licenccel, a biztosított és igényelt elemekkel, valamint azzal, hogy kikapcsolhatja-e egy szervezet. Regisztrálja ott, ahol a webalkalmazás és a worker összeáll, hogy mindkettő ugyanazt használja. A regiszter összeállításkor és minden register híváskor ellenőrzi az adott pont szabályait, elutasítja az érvénytelen konfigurációt az összes probléma felsorolásával, és ilyenkor változatlanul hagyja a regisztert. A bővítmény tesztjei ellenőrizzék, hogy az extensionContractProblems üres, és hogy kikapcsolásakor megváltozik az érintett működés.