---
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/gu/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/) દરેક એન્ડપૉઇન્ટ અને ઇવેન્ટની યાદી આપે છે.

## સરનામાં <!--quire:addresses-->

દરેક સંસ્થાનું પોતાનું સરનામું હોય છે અને API તેની નીચે છે:

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

પ્રમાણપત્ર સંસ્થા નક્કી કરે છે. એક સંસ્થાની કી બીજીના સરનામે વાપરવામાં આવે તો વિનંતી નકારાય છે.

OpenAPI દસ્તાવેજ દરેક સંસ્થાના સરનામે `/api/v1/openapi.json` પર મળે છે, તેથી ક્લાયન્ટ જનરેટર હંમેશાં તમે બોલાવી રહ્યાં છો તે આવૃત્તિ જુએ છે.

## પ્રમાણીકરણ <!--quire:authentication-->

**API કી** સ્ક્રિપ્ટ અને સર્વર-થી-સર્વર સંકલન માટે છે. વ્યવસ્થાપક `/admin/integrations/api-keys` પર એક બનાવે છે, તેના સ્કોપ પસંદ કરે છે અને કી એક જ વાર જુએ છે. તેને bearer token તરીકે મોકલો:

```
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 સાથે authorization code flow (`/oauth/authorize`, `/oauth/token`) અથવા મશીન ક્લાયન્ટ માટે client credentials વાપરો. શોધ માહિતી `/.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-->

- **પૃષ્ઠ ક્રમનિર્ધારણ**: દરેક યાદી cursor પ્રમાણે પૃષ્ઠોમાં વહેંચાય છે. `limit` આપો, પછી `next_cursor` જે `page` માંથી મળે તેને `cursor` તરીકે આપો; `has_more` સાચું હોય ત્યાં સુધી આ રીતે ચાલુ રાખો (નીચે ઉદાહરણ). offset નથી.
- **ત્યારથી થયેલા ફેરફારો**: `updated_since` સમય પછી બદલાયેલી વસ્તુઓ આપે છે. શું દૂર થયું તે જાણવા તેની સાથે `include_deleted=true` આપો અથવા `/<resource>/deletions` વાંચો.
- **બાહ્ય ઓળખક**: મોટા ભાગનાં સંસાધનો તમારો `external_id` સ્વીકારે છે અને `/<resource>/ext:{external_id}` તેના આધારે વાંચે અથવા અપસર્ટ કરે છે, જેથી સિંક માટે Quire ના ઓળખક સંગ્રહવાની જરૂર રહેતી નથી.
- **Idempotency**: `Idempotency-Key` હેડર `POST`, `PATCH` અને `DELETE` પર મોકલો. એ જ કી સાથે ફરી પ્રયાસ કરતાં કામ બે વાર થવાને બદલે પહેલો જવાબ મળે છે. બલ્ક એન્ડપૉઇન્ટ માટે તે જરૂરી છે.
- **આવૃત્તિઓ**: મુખ્ય આવૃત્તિ પાથમાં છે (`/v1`). તેની અંદર દરેક તોડફોડ કરતો ફેરફાર તારીખવાળી આવૃત્તિ હોય છે, જે `Quire-Version` હેડરથી પસંદ થાય છે, ઉદાહરણ તરીકે `Quire-Version: 2026-09-20`. હેડર ન આપો તો તમારું પ્રમાણપત્ર અપાયું ત્યારે ચાલુ રહેલી આવૃત્તિ મળે છે.

યાદીનું એક પૃષ્ઠ:

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

## ભૂલો <!--quire:errors-->

દરેક ભૂલ RFC 9457 problem દસ્તાવેજ છે:

```
{"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` મોકલે છે; તમારું એન્ડપૉઇન્ટ તેનો જવાબ આપે પછી જ સબ્સ્ક્રિપ્શન શરૂ થાય છે.

ડિલિવરી Standard Webhooks સ્પેસિફિકેશન અનુસરે છે:

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

ડિલિવરી ચકાસવા:

1. મળેલા ચોક્કસ બાઇટ્સમાંથી `{webhook-id}.{webhook-timestamp}.{raw body}` શબ્દમાળા બનાવો; JSON પાર્સ કરતા પહેલાં આ કરો.
2. સબ્સ્ક્રિપ્શનના રહસ્યથી તેના પર HMAC-SHA256 ગણો અને base64 કરો.
3. દરેક `v1,` મૂલ્યને `webhook-signature` સાથે constant time માં સરખાવો. રહસ્ય રોટેશન દરમિયાન બે મૂલ્ય હોઈ શકે છે; તેમાંનું કોઈ એક મેળ ખાય તો માન્ય છે.
4. તમારી ઘડિયાળથી પાંચ મિનિટથી વધુ જૂનો કે નવો timestamp નકારો.

```
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` પર streamable 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` શ્રેણીનો problem દસ્તાવેજ છે.

## એક્સ્ટેન્શન્સ <!--quire:extensions-->

Quire ના પોતાના પ્રવૃત્તિ પ્રકારો, બ્લૉક, નોંધણી પદ્ધતિઓ, સાઇન-ઇન પદ્ધતિઓ, પ્રશ્ન પ્રકારો, અહેવાલો, થીમ અને સંકલનો એ જ એક્સ્ટેન્શન રજિસ્ટ્રી દ્વારા જાહેર થાય છે જેમાં સ્વ-હોસ્ટેડ ઇન્સ્ટૉલેશન ઉમેરો કરી શકે છે. એક્સ્ટેન્શન બિલ્ડમાં જ સંકલિત હોય છે: રનટાઇમ પ્લગઇન લોડર નથી અને હોસ્ટેડ સંસ્થા નવું ઉમેરી શકતી નથી. વ્યવસ્થાપકો `/admin/extensions` પર તેમની સંસ્થા માટે દરેક એક્સ્ટેન્શન ચાલુ કે બંધ કરે છે ([વ્યવસ્થાપક માર્ગદર્શિકા](/gu/admin/extensions/) જુઓ).

એક્સ્ટેન્શન લખવા, `packages/integration/extensions/src/sample.ts` માંના નમૂના બ્લૉક અને થીમથી શરૂઆત કરો. એક્સ્ટેન્શન પૉઇન્ટ પસંદ કરી `points.ts` માં તેનો કરાર વાંચો; પછી ઓળખક, આવૃત્તિ, લાઇસન્સ, તે શું આપે છે અને શું માગે છે તથા સંસ્થા તેને બંધ કરી શકે કે નહીં તે દર્શાવી એક્સ્ટેન્શન જાહેર કરો. વેબ ઍપ્લિકેશન અને વર્કર જ્યાં જોડાય છે ત્યાં રજિસ્ટર કરો, જેથી બંને સહમત રહે. બિલ્ડ વખતે અને `register` બોલાવતાં રજિસ્ટ્રી દરેક પૉઇન્ટના નિયમો તપાસે છે, અમાન્ય સમૂહને તમામ સમસ્યાઓ સાથે નકારે છે અને તેમ થાય ત્યારે રજિસ્ટ્રી બદલાતી નથી. તમારા એક્સ્ટેન્શનની પોતાની કસોટીઓમાં ખાતરી કરો કે `extensionContractProblems` ખાલી છે અને તેને બંધ કરવાથી તેની અસર બદલાય છે.

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