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

तुमच्या संघटनेचा 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.

विनंत्या

• पृष्ठांकन: प्रत्येक यादी कर्सर पृष्ठांकनाने चालते. 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 वर पाठवा. त्याच कुंजीने पुन्हा प्रयत्न केल्यास काम दोनदा करण्याऐवजी पहिला प्रतिसाद परततो. बल्क endpoints ला ते आवश्यक आहे.
• आवृत्त्या: प्रमुख आवृत्ती पाथमध्ये असते (/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 वर गट करा:

मदतीशी संपर्क साधताना request_id उद्धृत करा.

Webhooks

/admin/webhooks वर सबस्क्राइब करा, किंवा API द्वारे /webhook_subscriptions वर. घटना नावाने निवडा (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 वर कोणती साधने उपलब्ध आहेत ते निवडतात.

योजना आणि API

API कुंज्या, OAuth क्लायंट, webhooks आणि MCP सर्वर हे योजनेच्या API हक्कांत येतात आणि प्रत्येक प्रमाण योजनेत ते समाविष्ट असते. ते नसलेल्या योजनेत कुंजी, क्लायंट किंवा सबस्क्रिप्शन तयार करणे नाकारले जाते, REST लेखने आणि MCP कनेक्शने नाकारली जातात, आणि REST वाचने चालू राहतात ज्यामुळे डेटा एक्सपोर्ट करता येतो. नाकारणी ही commerce.plan_entitlement कोड असलेली, precondition श्रेणीतील प्रॉब्लेम दस्तावेज आहे.

एक्सटेंशन्स

Quire चे स्वतःचे कृती प्रकार, ब्लॉक, नोंदणी पद्धती, प्रवेश पद्धती, प्रश्न प्रकार, अहवाल, थीम आणि एकत्रीकरणे त्याच एक्सटेंशन रजिस्ट्रीतून जाहीर केली जातात ज्यात स्वतः-होस्ट स्थापना जोडू शकते. एक्सटेंशन्स कंपाइल केलेली असतात: रनटाइम प्लगइन लोडर नाही आणि होस्ट केलेली संघटना एक जोडू शकत नाही. प्रशासक /admin/extensions वर स्वतःच्या संघटनेसाठी प्रत्येक एक्सटेंशन चालू किंवा बंद करतात (बघा प्रशासक मार्गदर्शिका).

एक लिहिण्यासाठी, packages/integration/extensions/src/sample.ts मधील नमुना ब्लॉक आणि थीमपासून सुरुवात करा. एक्सटेंशन पॉइंट निवडा आणि points.ts मधील त्याचा करार वाचा, नंतर आयडी, आवृत्ती, परवाना, ते काय पुरवते व मागते, आणि संघटनेला ते बंद करण्याची परवानगी आहे का यासह एक्सटेंशन जाहीर करा. वेब अनुप्रयोग आणि वर्कर जिथे एकत्र होतात तिथे ते नोंदणी करा, ज्यामुळे दोन्ही सहमत राहतात. रजिस्ट्री बिल्ड झाल्यावर आणि तुम्ही register कॉल केल्येवरीत प्रत्येक पॉइंटचे स्वतःचे नियम तपासते, प्रत्येक समस्या नावासह अचूक नसलेला गट नाकारते आणि तसे झाल्यास रजिस्ट्री अपरिवर्तित ठेवते. एक्सटेंशनच्या स्वतःच्या चाचण्यांनी त्यासाठी extensionContractProblems रिकामे आहे आणि ते बंद केल्यावर प्रभावित होणारे बदलते याची खात्री असावी.