Tərtibatçı təlimatı

Təşkilatınızın API ünvanından və məhdud scope-lu etimadnamədən istifadə edin. Oxuma sorğusu ilə başlayın, cavabı yoxlayın, secret-ləri isə mənbə nəzarətindən və sənədlərdəki nümunələrdən kənarda saxlayın.

Quire-in bir açıq API-si var: OpenAPI 3.1 sənədi ilə təsvir edilən HTTPS üzərindən REST, hadisələr üçün imzalı vebhuklar və süni intellekt köməkçiləri üçün MCP serveri. API arayışında hər endpoint və hadisə sadalanır.

Ünvanlar

Hər təşkilatın öz ünvanı var və API onun altında yerləşir:

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

Təşkilatı etimadnamə müəyyən edir. Bir təşkilatın açarı ilə başqasının ünvanına sorğu rədd edilir.

OpenAPI sənədi istənilən təşkilat ünvanında /api/v1/openapi.json yolundan verilir, buna görə client generatorları çağırdığınız versiyanı həmişə görür.

Autentifikasiya

API açarları skriptlər və serverdən serverə inteqrasiyalar üçündür. Administrator /admin/integrations/api-keys ünvanında açar yaradıb scope-ları seçir və onu yalnız bir dəfə görür. Bearer token kimi göndərin:

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

Açarlar qk_live_ və ya qk_test_ ilə başlayır. Hər inteqrasiyaya ayrıca açar verin.

OAuth 2.1 daxil olmuş şəxs adından işləyən tətbiqlər üçündür. /admin/integrations/oauth-clients ünvanında client qeydiyyatdan keçirin, sonra PKCE ilə avtorizasiya kodu axınından (/oauth/authorize, /oauth/token) və ya maşın client-i üçün client credentials-dən istifadə edin. Kəşf ünvanı /.well-known/oauth-authorization-server-dir. Scope tokenin edə biləcəklərini məhdudlaşdırır; şəxsə verilən icazədən artıq səlahiyyət vermir.

Scope-lar resource:read, resource:write və resource:delete formatındadır, məsələn, courses:read və ya enrolments:write. Dördü imtiyazlıdır və razılıq ekranında xəbərdarlıqla göstərilir: audit:read, roles:write, tenants:write və users:delete.

Sorğular

• Səhifələmə: hər siyahı cursor ilə səhifələnir. limit göndərin, sonra next_cursor-ı page-dən götürüb cursor kimi ötürün, has_more true olduqca (aşağıdakı nümunəyə baxın). Offset yoxdur.
• Bu vaxtdan bəri dəyişikliklər: updated_since vaxtdan sonra dəyişənləri qaytarır. Silinənləri öyrənmək üçün bunu include_deleted=true ilə birləşdirin və ya /<resource>/deletions oxuyun.
• Xarici identifikatorlar: əksər resurslar öz external_id dəyərinizi qəbul edir; /<resource>/ext:{external_id} həmin dəyərlə oxuyur və ya upsert edir, buna görə sinxronizasiya Quire identifikatorlarını saxlamağı tələb etmir.
• İdemponentlik: Idempotency-Key başlığını POST, PATCH və DELETE sorğularında göndərin. Eyni açarla təkrar sorğu işi ikinci dəfə görmək əvəzinə ilk cavabı qaytarır. Bulk endpoint-lərdə bu məcburidir.
• Versiyalar: əsas versiya yoldadır (/v1). Onun daxilində pozucu dəyişikliklərin hər biri tarixli reviziyadır və Quire-Version başlığı ilə seçilir, məsələn, Quire-Version: 2026-09-20. Başlıq verilməsə, etimadnaməniz yaradılan vaxt qüvvədə olan reviziyanı alırsınız.

Siyahının bir səhifəsi:

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

Xətalar

Hər xəta RFC 9457 problem sənədidir:

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

Sabit olan code-a əsasən yönləndirin; detail insanlar üçün yazılıb, onlara göstərmək təhlükəsizdir və dəyişə bilər. Kodu tanımırsınızsa, category üzrə qruplaşdırın:

Dəstəyə müraciət edəndə request_id dəyərini verin.

Vebhuklar

/admin/webhooks ünvanında və ya API vasitəsilə /webhook_subscriptions yolunda abunə olun. Hadisələri adla (enrolment.created), sahəyə görə (enrolment.*) və ya hamısını (*) seçin. Quire əvvəlcə webhook.ping göndərir; endpoint cavab verdikdən sonra abunəlik başlayır.

Çatdırılmalar Standard Webhooks spesifikasiyasına əməl edir:

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

Çatdırılmanı yoxlamaq üçün:

1. JSON təhlilindən əvvəl alınmış dəqiq baytlarla {webhook-id}.{webhook-timestamp}.{raw body} sətrini qurun.
2. Abunəlik secret-i ilə üzərində HMAC-SHA256 hesablayın və Base64-a çevirin.
3. v1, dəyərlərinin hər birini webhook-signature başlığı ilə sabit vaxtda müqayisə edin. Secret dəyişdirilərkən iki dəyər ola bilər; istənilən uyğunluq etibarlıdır.
4. Saatınızdan beş dəqiqədən artıq fərqlənən timestamp-i rədd edin.

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 dəyərinə əsasən dublikatı aradan qaldırın: çatdırılma birdən çox gələ bilər. Gövdədə identifikatorlar və qısa xülasə var; cari vəziyyət üçün resursu əldə edin. Uğursuz çatdırılmalar 72 saata qədər artan intervallarla yenidən göndərilir və çatdırılma jurnalından təkrar oynadıla bilər.

MCP

Quire MCP serveri təşkilatın ünvanındakı /mcp yolunda, axınlı HTTP üzərində işləyir. MCP client OAuth serverini /.well-known/oauth-protected-resource ünvanından aşkarlayır; şəxs istənilən OAuth client-də olduğu kimi daxil olub razılıq verir. Alətlər həmin şəxsin icazələri ilə onun adından işləyir, dağıdıcı alətlər isə təsdiq istəyir. Administratorlar əlçatan alətləri /admin/integrations/mcp ünvanında seçirlər.

Planlar və API

API açarları, OAuth client-lər, vebhuklar və MCP serveri planın API hüququna daxildir; hər standart planda bu hüquq var. Daxil etməyən planda açar, client və ya abunəlik yaratmaq, REST yazmaları və MCP bağlantısı rədd edilir; REST oxumaları məlumatın ixrac edilə bilməsi üçün işləyir. Rədd cavabı commerce.plan_entitlement kodlu və precondition kateqoriyalı problem sənədidir.

Genişlənmələr

Quire-in öz fəaliyyət növləri, blokları, qeydiyyat üsulları, giriş üsulları, sual növləri, hesabatları, mövzuları və inteqrasiyaları öz serverində quraşdırmanın əlavə edə bildiyi eyni genişlənmə reyestrində elan edilir. Genişlənmələr yığıma daxil edilir: işləmə zamanı plagin yükləyicisi yoxdur və hostinq təşkilatı yenisini əlavə edə bilməz. Administratorlar hər genişlənməni təşkilatları üçün /admin/extensions ünvanında aktivləşdirir və ya söndürür (administrator təlimatına baxın).

Genişlənmə yazmaq üçün packages/integration/extensions/src/sample.ts nümunə blok və mövzusundan başlayın. Genişlənmə nöqtəsini seçin, points.ts daxilində müqaviləsini oxuyun, sonra ID, versiya, lisenziya, təqdim etdiyi və tələb etdiyi imkanlar, eləcə də təşkilatın onu söndürə bilib-bilməməsi ilə elan edin. Veb tətbiq və worker-in tərkib olunduğu yerə qeydiyyatdan keçirin ki, hər ikisi uyğun olsun. Reyestr qurularkən və register çağırışında hər nöqtənin öz qaydalarını yoxlayır, bütün problemləri adlandıraraq etibarsız dəsti rədd edir və belə olduqda reyestri dəyişməz saxlayır. Genişlənmənin öz testləri onun üçün extensionContractProblems boş olduğunu və söndürməyin təsir etdiyi imkanları dəyişdirdiyini təsdiqləməlidir.