સીધા સામગ્રી પર જાઓ
Quireદસ્તાવેજીકરણ
ગુજરાતી

વિકાસકર્તા માર્ગદર્શિકા

Quire REST API, OAuth, webhooks, MCP સર્વર અને એક્સ્ટેન્શન્સ.

Markdown તરીકે જુઓ

તમારી સંસ્થાનું API સરનામું અને મર્યાદિત સ્કોપવાળું પ્રમાણપત્ર વાપરો. વાંચવાની વિનંતીથી શરૂઆત કરો, જવાબ તપાસો અને રહસ્યોને સ્રોત નિયંત્રણ તથા દસ્તાવેજીકરણનાં ઉદાહરણોથી બહાર રાખો.

Quire પાસે એક જાહેર API છે: HTTPS ઉપર REST, જેનું વર્ણન OpenAPI 3.1 દસ્તાવેજમાં છે; ઘટનાઓ માટે સહી કરેલા webhooks છે અને AI સહાયકો માટે MCP સર્વર છે. API સંદર્ભ દરેક એન્ડપૉઇન્ટ અને ઇવેન્ટની યાદી આપે છે.

સરનામાં

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

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

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

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

પ્રમાણીકરણ

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.

વિનંતીઓ

  • પૃષ્ઠ ક્રમનિર્ધારણ: દરેક યાદી 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}}

ભૂલો

દરેક ભૂલ 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

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

એક્સ્ટેન્શન્સ

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

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

નેવિગેશન

શોધવા માટે લખો…

↑↓ નેવિગેટ કરો↵ પસંદ કરોEsc બંધ કરો