--- title: "Fejlesztői útmutató" description: "A Quire REST API-ja, OAuth, webhookok, MCP-kiszolgáló és bővítmények." image: "https://docs.quirelms.com/og.png" --- > Documentation Index > Fetch the complete documentation index at: https://docs.quirelms.com/hu/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://docs.quirelms.com/api/) 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`.
The API keys page with one key, the person it acts as, its scopes and its status, and a form to create another.
API keys list who each key acts as and what it may reach.
## 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 `//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 `//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: | Kategória | Állapot | Újrapróbálás | | --- | --- | --- | | `validation` | 422, mezőrészletek az `errors` mezőben | Nem | | `authentication` | 401 | Nem | | `authorization` | 403 | Nem | | `not_found` | 404 | Nem | | `conflict` | 409 | Néha | | `precondition` | 412 | Nem | | `quota` | 402 a csomaghoz, 413 a mérethez | Nem | | `rate_limit` | 429, `Retry-After` fejléccel | Igen | | `upstream` | 502 vagy 504 | Igen | | `internal` | 500 | Igen | Ü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.
The AI assistants page with the server address to give an assistant and a table of the tools it can use.
AI assistants (MCP): the server address, and the tools an assistant may call.
## 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](/hu/admin/extensions/)). 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. Source: https://docs.quirelms.com/hu/developer/index.mdx