--- title: "Jagorar mai haɓakawa" description: "REST API na Quire, OAuth, webhooks, uwar garken MCP da ƙarin fasaloli." image: "https://docs.quirelms.com/og.png" --- > Documentation Index > Fetch the complete documentation index at: https://docs.quirelms.com/ha/llms.txt > Use this file to discover all available pages before exploring further. # Jagorar mai haɓakawa Yi amfani da adireshin API na ƙungiyarka da shaidar shiga mai iyakantaccen izini. Fara da buƙatar karatu, duba amsar, kuma adana sirrika a wajen sarrafa tushen lamba da misalan takardun bayani. Quire yana da API na jama'a guda ɗaya: REST a kan HTTPS, an bayyana shi ta takardar OpenAPI 3.1, tare da webhooks masu sa hannu ga abubuwan da suka faru da uwar garken MCP ga mataimakan AI. [Jagorar API](https://docs.quirelms.com/api/) tana lissafa kowace hanyar API da taron. ## Adiresoshi Kowace ƙungiya tana da nata adireshin, API kuma yana ƙarƙashinsa: ``` https://acme.quirelms.com/api/v1/courses ``` Shaidar shiga ce ke zaɓar ƙungiya. Ana ƙin maɓallin wata ƙungiya idan an yi amfani da shi a adireshin wata. Ana samar da takardar OpenAPI a `/api/v1/openapi.json` a adireshin kowace ƙungiya, don haka janareta na abokan ciniki kullum suna ganin sigar da kake kira. ## Tabbatar da shiga **Maɓallan API** na rubutun kwamfuta da haɗin kai tsakanin uwar garke da uwar garke ne. Mai gudanarwa yana ƙirƙira ɗaya a `/admin/integrations/api-keys`, ya zaɓi izini, sannan ya gan shi sau ɗaya. Aika shi a matsayin alamar bearer: ``` curl -H "Authorization: Bearer qk_live_..." https://acme.quirelms.com/api/v1/users?limit=50 ``` Maɓallai suna farawa da `qk_live_` ko `qk_test_`. Ka ba kowane haɗin kai nasa maɓalli. **OAuth 2.1** na manhajojin da ke aiki a matsayin mutumin da ya shiga ne. Yi rajistar abokin aiki a `/admin/integrations/oauth-clients`, sannan amfani da hanyar lambar izini tare da PKCE (`/oauth/authorize`, `/oauth/token`), ko shaidar abokin ga manhajar kwamfuta. Ana gano sabar a `/.well-known/oauth-authorization-server`. Izini yana rage abin da alama za ta iya yi; ba zai taɓa ba ta ikon da mutumin da kansa ba shi da ba. Izini su ne `resource:read`, `resource:write` da `resource:delete`, misali `courses:read` ko `enrolments:write`. Hudu suna da gata kuma ana nuna gargaɗi a shafin amincewa: `audit:read`, `roles:write`, `tenants:write` da `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.
## Buƙatu - **Shafuka**: ana raba dukkan jerin bayanai zuwa shafuka da cursor. Aika `limit`, sannan `next_cursor` daga `page` a matsayin `cursor` muddin `has_more` gaskiya ne (misali a ƙasa). Babu offset. - **Canje-canje tun daga**: `updated_since` yana dawo da abin da ya canza bayan wani lokaci. Haɗa shi da `include_deleted=true`, ko karanta `//deletions`, domin sanin abin da aka cire. - **Masu ganewa na waje**: yawancin albarkatu suna karɓar `external_id` naka; `//ext:{external_id}` kuma yana karantawa ko rubutawa bisa wannan ID, don haka daidaitawa ba ya buƙatar adana ID na Quire. - **Rashin maimaita aiki**: aika header `Idempotency-Key` tare da `POST`, `PATCH` da `DELETE`. Sake gwaji da maɓalli iri ɗaya yana dawo da amsar farko maimakon yin aikin sau biyu. Hanyoyin API na yawan abubuwa suna buƙatarsa. - **Sigogi**: babban siga yana cikin hanya (`/v1`). A cikinta, kowane canjin da zai karya dacewa yana da sabuntawa mai kwanan wata, ana zaɓarsa da header `Quire-Version`, misali `Quire-Version: 2026-09-20`. Idan babu header, za ka samu sabuntawar da ke aiki lokacin da aka bayar da shaidar shiga. Shafin jerin abubuwa: ``` {"data": [...], "page": {"next_cursor": "eyJ2Ijox...", "has_more": true, "limit": 100}} ``` ## Kurakurai Kowane kuskure takardar matsalar RFC 9457 ce: ``` {"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..."} ``` Yi rarrabewa bisa `code`, wanda ba ya canzawa; an rubuta `detail` domin mutane, ana iya nuna musu, kuma zai iya canzawa. Idan ba ka san lambar ba, ware ta bisa `category`: | Rukuni | Matsayi | Sake gwadawa | | --- | --- | --- | | `validation` | 422, tare da cikakken bayanin fili a `errors` | A'a | | `authentication` | 401 | A'a | | `authorization` | 403 | A'a | | `not_found` | 404 | A'a | | `conflict` | 409 | Wani lokaci | | `precondition` | 412 | A'a | | `quota` | 402 ga tsarin, 413 ga girma | A'a | | `rate_limit` | 429, tare da `Retry-After` | Eh | | `upstream` | 502 ko 504 | Eh | | `internal` | 500 | Eh | Kawo `request_id` idan ka tuntuɓi taimako. ## Webhooks Yi rajista a `/admin/webhooks`, ko ta API a `/webhook_subscriptions`. Zaɓi tarurrukan bisa suna (`enrolment.created`), yanki (`enrolment.*`) ko duka (`*`). Da farko Quire yana aika `webhook.ping`; rajistar tana farawa bayan adireshinka ya amsa. Aika saƙonni yana bin ƙa'idar Standard Webhooks: ``` POST /hooks/quire webhook-id: 01JB7XQK4Z8FQ2M3N4P5R6S7T8 webhook-timestamp: 1790000000 webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= ``` Domin tantance aika: 1. Gina zaren `{webhook-id}.{webhook-timestamp}.{raw body}` daga ainihin bytes da aka karɓa, kafin kowane fassarar JSON. 2. Lissafa HMAC-SHA256 a kansa da sirrin rajistarka, sannan sauya zuwa base64. 3. Kwatanta shi da kowace ƙima ta `v1,` a `webhook-signature` ba tare da bayani kan lokacin kwatanta ba. A lokacin juya sirri za a iya samun biyu; duk wanda ya dace yana aiki. 4. Ƙi timestamp da ya fi minti biyar bambanci da agogonka. ``` 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); }); } ``` Kada a maimaita aiki bisa `webhook-id`: aika na iya zuwa fiye da sau ɗaya. Jikin saƙon yana ɗauke da masu ganewa da taƙaitaccen bayani; nemi albarkatun domin samun matsayinsa na yanzu. Ana sake gwada aikawa da ta gaza tare da tazarar lokaci har tsawon awa 72, kuma ana iya sake aikawa daga rajistar isarwa. ## MCP Uwar garken MCP ta Quire tana `/mcp` a adireshin ƙungiya, ta streamable HTTP. Abokin MCP yana gano uwar garken OAuth daga `/.well-known/oauth-protected-resource`, kuma mutum yana shiga ya amince kamar kowane abokin OAuth. Kayan aiki yana aiki a matsayin mutumin tare da izininsa, kayan aikin da ke da illa kuma suna neman tabbaci. Masu gudanarwa suna zaɓar kayan aikin da ake da su a `/admin/integrations/mcp`.
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.
## Tsari da API Maɓallan API, abokan OAuth, webhooks da uwar garken MCP suna ƙarƙashin izinin API na tsarin, kuma kowane tsari na yau da kullum yana haɗa shi. A tsari marar wannan, ana ƙin ƙirƙirar maɓalli, abokin aiki ko rajista; ana kuma ƙin rubutun REST da haɗin MCP, amma karatun REST yana ci gaba domin a iya fitar da bayanai. Ƙin yana zuwa a takardar matsala mai lambar `commerce.plan_entitlement`, rukuni `precondition`. ## Ƙarin fasaloli Ana ayyana nau'o'in aiki, tubalan shafi, hanyoyin shigarwa da hanyoyin shiga na Quire, nau'o'in tambaya, rahotanni, jigogi da haɗin kai ta rajistar ƙarin fasaloli iri ɗaya da shigarwar da kake sarrafawa za ta iya ƙara wa. Ana gina ƙarin fasaloli cikin Quire: babu mai loda plugin yayin aiki, kuma ƙungiyar masaukin girgije ba za ta iya ƙara ɗaya ba. Masu gudanarwa suna kunna ko kashe kowane fasali ga ƙungiyarsu a `/admin/extensions` (duba [jagorar mai gudanarwa](/ha/admin/extensions/)). Domin rubuta ɗaya, fara da tubali da jigo na misali a `packages/integration/extensions/src/sample.ts`. Zaɓi wurin faɗaɗa ka karanta yarjejeniyarsa a `points.ts`, sannan bayyana ƙarin fasalin da ID, siga, lasisi, abin da yake bayarwa da abin da yake buƙata, da ko ƙungiya za ta iya kashe shi. Yi rajista da shi inda ake haɗa manhajar yanar gizo da mai aiki, domin su yarda. Rajistar tana gwada dokokin kowane wuri idan an gina ta da duk lokacin da aka kira `register`; tana ƙin saitin da ba zai yi aiki ba tare da bayyana kowace matsala, kuma ba ta canza rajistar idan ta ƙi. Gwajin ƙarin fasalin ya kamata ya tabbatar da cewa `extensionContractProblems` babu komai a gare shi, kuma kashe shi yana canza abin da yake shafa. Source: https://docs.quirelms.com/ha/developer/index.mdx