---
title: "विकासकर्ता मार्गदर्शिका"
description: "Quire REST API, OAuth, webhooks, MCP सर्वर आणि एक्सटेंशन्स."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/mr/llms.txt
> Use this file to discover all available pages before exploring further.

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

<span id="developer-guide"></span>

तुमच्या संघटनेचा API पत्ता आणि स्कोप केलेली प्रमाणपत्र वापरा. वाचन
विनंतीने सुरुवात करा, प्रतिसाद तपासा आणि गोप्य माहिती स्रोत नियंत्रणाबाहेर
आणि दस्तावेज उदाहरणांबाहेर ठेवा.

Quire ला एकच सार्वजनिक API आहे: HTTPS वरील REST, OpenAPI 3.1
दस्तावेजाने वर्णित, घटनांसाठी सही केलेल्या webhooks आणि AI
सहाय्यकांसाठी MCP सर्वरसह. [API संदर्भ](https://docs.quirelms.com/api/) प्रत्येक endpoint
आणि घटना दाखवतो.

## पत्ते <!--quire:addresses-->

प्रत्येक संघटनेचा स्वतःचा पत्ता असतो आणि API त्याखाली असतो:

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

प्रमाणपत्र संघटना ठरवते. एका संघटनेची कुंजी दुसऱ्याच्या पत्त्यावर
वापरली ती नाकारली जाते.

OpenAPI दस्तावेज कोणत्याही संघटनेच्या पत्त्यावर `/api/v1/openapi.json`
वर मिळतो, त्यामुळे क्लायंट जनरेटर कधीही तुम्ही कॉल करणारी आवृत्तीच
पाहतात.

## प्रमाणीकरण <!--quire:authentication-->

**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`.

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-api-keys.webp" alt="The API keys page with one key, the person it acts as, its scopes and its status, and a form to create another." width="944" height="700" loading="lazy" decoding="async"><figcaption>API keys list who each key acts as and what it may reach.</figcaption></figure>

## विनंत्या <!--quire:requests-->

- **पृष्ठांकन**: प्रत्येक यादी कर्सर पृष्ठांकनाने चालते. `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}}
```

## त्रुटी <!--quire:errors-->

प्रत्येक त्रुटी ही 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 <!--quire: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-->

Quire चा MCP सर्वर संघटनेच्या पत्त्यावर `/mcp` वर, स्ट्रीमेबल HTTP वर
असतो. MCP क्लायंट `/.well-known/oauth-protected-resource` वरून OAuth
सर्वर शोधतो आणि व्यक्ती कोणत्याही OAuth क्लायंटप्रमाणेच साइन इन करून
संमती देते. साधने त्या व्यक्तीच्या परवानग्यांनी काम करतात आणि
विनाशकारक साधने खात्री मागतात. प्रशासक `/admin/integrations/mcp` वर
कोणती साधने उपलब्ध आहेत ते निवडतात.

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-mcp.webp" alt="The AI assistants page with the server address to give an assistant and a table of the tools it can use." width="944" height="700" loading="lazy" decoding="async"><figcaption>AI assistants (MCP): the server address, and the tools an assistant may call.</figcaption></figure>

## योजना आणि API <!--quire:plans-and-the-api-->

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

## एक्सटेंशन्स <!--quire:extensions-->

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

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

Source: https://docs.quirelms.com/mr/developer/index.mdx