सामग्रीमा जानुहोस्
Quireदस्तावेज
नेपाली

विकासकर्ता मार्गदर्शिका

Quire REST API, OAuth, webhooks, MCP सर्भर र एक्सटेन्सनहरू।

Markdown का रूपमा हेर्नुहोस्

तपाईंको सङ्गठनको API ठेगाना र स्कोप भएको प्रमाण प्रयोग गर्नुहोस्। पढ्ने अनुरोधबाट सुरु गर्नुहोस्, प्रतिक्रिया जाँच्नुहोस्, र गोप्य कुरा स्रोत नियन्त्रण र दस्तावेज उदाहरणबाहिर राख्नुहोस्।

Quire को एउटा सार्वजनिक API छ: HTTPS मा REST, OpenAPI 3.1 दस्तावेजद्वारा वर्णित, घटनाका लागि हस्ताक्षरित webhooks र AI सहायकका लागि MCP सर्भर सहित। API सन्दर्भ ले हरेक endpoint र घटना सूचीबद्ध गर्छ।

ठेगानाहरू

हरेक सङ्गठनको आफ्नै ठेगाना हुन्छ, र API यसैअन्तर्गत रहन्छ:

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

प्रमाणले सङ्गठन निर्णय गर्छ। एउटा सङ्गठनको कुञ्जी अर्कोको ठेगानामा प्रयोग भए अस्वीकार हुन्छ।

OpenAPI दस्तावेज कुनै पनि सङ्गठनको ठेगानामा /api/v1/openapi.json मा दिइन्छ, त्यसैले क्लाइन्ट जेनेरेटरले सधैँ तपाईंले कल गर्ने संस्करण देख्छन्।

प्रमाणीकरण

API कुञ्जीहरू स्क्रिप्ट र सर्भर-देखि-सर्भर एकीकरणका लागि हुन्। प्रशासकले /admin/integrations/api-keys मा एउटा बनाउँछ, यसको स्कोप छान्छ, र एकपटक देख्छ। यसलाई बियरर टोकनका रूपमा पठाउनुहोस्:

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

कुञ्जी qk_live_ वा qk_test_ बाट सुरु हुन्छन्। हरेक एकीकरणलाई आफ्नै कुञ्जी दिनुहोस्।

OAuth 2.1 साइन-इन गरेको व्यक्तिका रूपमा कार्य गर्ने अनुप्रयोगका लागि हो। /admin/integrations/oauth-clients मा क्लाइन्ट दर्ता गर्नुहोस्, त्यसपछि PKCE सहित प्राधिकरण कोड प्रवाह (/oauth/authorize, /oauth/token), वा मेसिन क्लाइन्टका लागि क्लाइन्ट प्रमाण प्रयोग गर्नुहोस्। खोज /.well-known/oauth-authorization-server मा छ। स्कोपले टोकनले के गर्न सक्छ साँघुरो पार्छ; यसले व्यक्तिले सक्नेभन्दा बढी कहिल्यै गर्न दिँदैन।

स्कोपहरू resource:read, resource:write र resource:delete हुन्, जस्तै courses:read वा enrolments:write। चार विशेषाधिकारयुक्त छन् र सहमति स्क्रिनमा चेतावनीसहित देखाइन्छन्: audit:read, roles:write, tenants:write र 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.

अनुरोधहरू

  • पृष्ठांकन: हरेक सूची कर्सर पृष्ठांकित हुन्छ। limit पठाउनुहोस्, त्यसपछि next_cursor लाई page बाट cursor का रूपमा पठाउनुहोस् जब has_more सत्य हुन्छ (उदाहरण तल)। अफसेट हुँदैन।
  • यतादेखिका परिवर्तन: updated_since ले समयपछिका परिवर्तन फर्काउँछ। के हटाइयो जान्न यसलाई include_deleted=true सँग जोड्नुहोस्, वा /<resource>/deletions पढ्नुहोस्।
  • बाह्य पहिचायक: धेरैजसो स्रोतले तपाईंको आफ्नै external_id स्वीकार्छन्, र /<resource>/ext:{external_id} ले त्यसबाट पढ्छ वा अपसर्ट गर्छ, त्यसैले सिङ्कले Quire का पहिचायक भण्डारण गर्नुपर्दैन।
  • आइडेम्पोटेन्सी: Idempotency-Key हेडर POST, PATCH र DELETE मा पठाउनुहोस्। उही कुञ्जीसहित पुनः प्रयासले काम दोब्बर गर्नुको सट्टा पहिलो प्रतिक्रिया फर्काउँछ। बल्क endpoint लाई यो चाहिन्छ।
  • संस्करणहरू: प्रमुख संस्करण पथमा छ (/v1)। यसभित्र, हरेक ब्रेकिङ परिवर्तन मितियुक्त परिमार्जन हो, Quire-Version हेडरबाट छानिने, जस्तै Quire-Version: 2026-09-20। हेडरबिना तपाईंले तपाईंको प्रमाण जारी हुँदा चालु परिमार्जन पाउनुहुन्छ।

सूचीको एउटा पृष्ठ:

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

त्रुटिहरू

हरेक त्रुटि RFC 9457 समस्या दस्तावेज हो:

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

स्थिर हुने code मा शाखा गर्नुहोस्; detail मानिसका लागि लेखिएको हो, तिनलाई देखाउन सुरक्षित छ, र परिवर्तन हुन सक्छ। कोड नचिनेमा, category मा समूह बनाउनुहोस्:

श्रेणी स्थिति पुनः प्रयास
validation 422, errors मा फिल्ड विवरणसहित होइन
authentication 401 होइन
authorization 403 होइन
not_found 404 होइन
conflict 409 कहिलेकाहीँ
precondition 412 होइन
quota योजनाका लागि 402, आकारका लागि 413 होइन
rate_limit 429, Retry-After सहित हो
upstream 502 वा 504 हो
internal 500 हो

समर्थनलाई सम्पर्क गर्दा request_id उल्लेख गर्नुहोस्।

Webhooks

/admin/webhooks मा, वा /webhook_subscriptions मा API मार्फत सदस्यता लिनुहोस्। घटना नामबाट (enrolment.created), क्षेत्रबाट (enrolment.*) वा सबै (*) छान्नुहोस्। Quire ले पहिले webhook.ping पठाउँछ; तपाईंको endpoint ले जवाफ दिएपछि सदस्यता सुरु हुन्छ।

वितरणले Standard Webhooks विशिष्टता पछ्याउँछ:

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

वितरण प्रमाणित गर्न:

  1. कुनै JSON पार्सिङअघि, प्राप्त ठ्याक्कै बाइटबाट {webhook-id}.{webhook-timestamp}.{raw body} स्ट्रिङ बनाउनुहोस्।
  2. तपाईंको सदस्यता गोप्यसँग यसमा HMAC-SHA256 गणना गर्नुहोस्, र base64 गर्नुहोस्।
  3. हरेक v1, मानलाई स्थिर समयमा webhook-signature मा तुलना गर्नुहोस्। गोप्य घुमाउँदा दुई हुन सक्छन्; कुनै मिल्नु मान्य हो।
  4. तपाईंको घडीबाट पाँच मिनेटभन्दा टाढाको टाइमस्ट्याम्प अस्वीकार गर्नुहोस्।
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);
  });
}

webhook-id मा डुप्लिकेट हटाउनुहोस्: वितरण एकभन्दा बढीपटक आउन सक्छ। बडीले पहिचायक र छोटो सारांश बोक्छ; हालको स्थितिका लागि स्रोत फेच गर्नुहोस्। असफल वितरण 72 घण्टासम्म ब्याकअफसहित पुनः प्रयास गरिन्छ, र वितरण लगबाट पुनः चलाउन सकिन्छ।

MCP

Quire को MCP सर्भर सङ्गठनको ठेगानामा /mcp मा छ, स्ट्रिमेबल HTTP मा। MCP क्लाइन्टले /.well-known/oauth-protected-resource बाट OAuth सर्भर पत्ता लगाउँछ, र व्यक्ति कुनै पनि OAuth क्लाइन्टमा जस्तै साइन इन र सहमति गर्छ। उपकरणले त्यो व्यक्तिका रूपमा, तिनको अनुमतिसहित कार्य गर्छन्, र विनाशकारी उपकरण पुष्टि माग्छन्। प्रशासकले /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.

योजना र API

API कुञ्जी, OAuth क्लाइन्ट, webhooks र MCP सर्भर योजनाको API हकका हुन्, र हरेक मानक योजनामा यो समावेश छ। यो नभएको योजनामा, कुञ्जी, क्लाइन्ट वा सदस्यता बनाउन अस्वीकार हुन्छ, REST लेखन र MCP जडान अस्वीकार हुन्छन्, र REST पढाइ चलिरहन्छ ताकि डेटा निर्यातयोग्य रहोस्। अस्वीकार commerce.plan_entitlement कोडसहित समस्या दस्तावेज हो, precondition श्रेणीमा।

एक्सटेन्सनहरू

Quire का आफ्नै गतिविधि प्रकार, ब्लक, भर्ना विधि, साइन-इन विधि, प्रश्न प्रकार, प्रतिवेदन, थिम र एकीकरण उही एक्सटेन्सन रजिस्ट्रीबाट घोषणा गरिन्छन् जसमा स्व-होस्टेड स्थापनाले थप्न सक्छ। एक्सटेन्सन कम्पाइल हुन्छन्: कुनै रनटाइम प्लगइन लोडर हुँदैन, र होस्ट गरिएको सङ्गठनले एउटा थप्न सक्दैन। प्रशासकहरूले /admin/extensions मा आफ्नो सङ्गठनका लागि हरेक एक्सटेन्सन खोल्छन् वा बन्द गर्छन् (प्रशासक मार्गदर्शिका हेर्नुहोस्)।

एउटा लेख्न, packages/integration/extensions/src/sample.ts मा नमुना ब्लक र थिमबाट सुरु गर्नुहोस्। एक्सटेन्सन बिन्दु छान्नुहोस् र points.ts मा यसको सम्झौता पढ्नुहोस्, त्यसपछि एक्सटेन्सनलाई id, संस्करण, इजाजत, यसले के दिन्छ र माग्छ, र सङ्गठनले यसलाई बन्द गर्न सक्छ कि सक्दैन सहित घोषणा गर्नुहोस्। वेब अनुप्रयोग र वर्कर जहाँ मिल्छन् त्यहाँ दर्ता गर्नुहोस्, ताकि दुवै सहमत होऊन्। रजिस्ट्रीले निर्माण हुँदा र तपाईंले register कल गर्दा हरेक बिन्दुका आफ्नै नियम जाँच्छ र अमान्य हुने सेटलाई हरेक समस्या नामसहित अस्वीकार गर्छ, र गर्दा रजिस्ट्री अपरिवर्तित छोड्छ। एक्सटेन्सनका आफ्नै परीक्षणले extensionContractProblems यसका लागि खाली छ र यसलाई बन्द गर्दा यसले असर गर्ने कुरा परिवर्तन हुन्छ भनी दाबी गर्नुपर्छ।

नेभिगेसन

खोज्न टाइप गर्नुहोस्…

↑↓ नेभिगेट↵ छान्नुहोस्Esc बन्द गर्नुहोस्