Modul tərifi

Müqavilənin 1.7 versiyasından etibarən manifestindəki hər modul özünü ətraflı təsvir edə bilər. CoSuite kataloqu, qeydiyyat axını, tətbiqinin CoSuite-dəki səhifəsi, cosuite.io məhsul səhifələri və (2-ci mərhələdə) müştəri API arayışı bu sahələrdən yaradılır. Bütün sahələr istəyə bağlıdır; 1.6 manifesti olduğu kimi etibarlı qalır.

#Nümunə

{
  "key": "dent.treatment",
  "name": { "tr": "Hasta ve tedavi planı", "en": "Patients and treatment plans", "az": "Xəstə və müalicə planı" },
  "description": { "tr": "Hasta kartı ve tedavi planı.", "en": "Patient records and treatment plans.", "az": "Xəstə kartı və müalicə planı." },
  "limits": [{ "key": "smsPerMonth", "unit": "count_per_month" }],
  "features": [
    { "key": "plan_pdf", "name": { "tr": "Tedavi planı PDF'i", "en": "Treatment plan PDF", "az": "Müalicə planı PDF" } },
    { "key": "sms", "name": { "tr": "SMS hatırlatma", "en": "SMS reminders", "az": "SMS xatırlatma" }, "limit": "smsPerMonth" }
  ],
  "api": { "version": "2026-11", "openapi": "/openapi.json", "scopes": [{ "key": "patients:read" }, { "key": "patients:write" }] },
  "webhooks": [{ "type": "treatment.completed", "scope": "patients:read", "schema": { "type": "object" } }],
  "provides": [],
  "dataCategories": ["identity", "contact", "health"],
  "markets": [
    { "country": "TR", "locales": ["tr"] },
    { "country": "AZ", "locales": ["az"], "price": { "currency": "AZN", "amount": 25 } }
  ]
}

#Sahələr

Limitlər bir baxışda: hər modul üçün 64 funksiya, 64 scope, 64 webhook, 16 provides, 32 məlumat kateqoriyası və 100 bazara qədər.

#Uyğunluq testinin tətbiq etdiyi qaydalar

Uyğunluq testi yalnız doldurduğun sahələri yoxlayır. Partnyor portalı da göndərəndə eyni yoxlamaları işə salır.

• Hər bazar dilində mətnlər. markets siyahısında istifadə olunan hər dil üçün modulun name, description dəyərləri və hər funksiyanın name dəyəri doldurulmalıdır.
• Bazar dilləri manifestdən gəlir. markets[].locales siyahısındakı hər dil manifestin locales siyahısında da olmalıdır.
• Təkrarlanan açar yoxdur: features, api.scopes, webhooks (type üzrə) və markets (country üzrə) siyahılarında; provides siyahısında təkrar yoxdur.
• Funksiya limitləri mövcuddur. Funksiyanın limit dəyəri modulun limits[].key dəyərlərindən biri olmalıdır.
• Webhook scope-ları mövcuddur. Webhook-un scope dəyəri api tərifini tələb edir və api.scopes siyahısından biri olmalıdır.
• Yalnız tanınan dəyərlər. provides və dataCategories yalnız yuxarıda sadalanan dəyərləri qəbul edir. CoSuite özü naməlum dəyərləri nəzərə almır (irəli uyğunluq), amma test yazı səhvlərini tutmaq üçün onları rədd edir.
• OpenAPI yoxlanılır: api olan hər modul üçün sənəd yüklənir (və ya daxildən oxunur) və aşağıda təsvir olunduğu kimi yoxlanılır.

#OpenAPI tələbləri

Test CoSuite-in güvəndiyi hissələri yoxlayır; bu, tam sxem yoxlaması deyil.

• openapi 3.1.x olur; info.title və info.version mövcuddur; paths boş deyil və hər yol / ilə başlayır.
• Hər əməliyyat cosuite təhlükəsizlik sxemi vasitəsilə ən azı bir scope tələb edir: security: [{ "cosuite": ["<scope>"] }]. Öz security dəyəri olmayan əməliyyat kök səviyyəsindəki security dəyərini miras alır.
• Sənəddə istifadə olunan hər scope modulun api.scopes siyahısında elan olunmalıdır.
• operationId dəyərləri unikaldır.
• openapi URL olduqda: baseUrl https-dirsə, o da https olmalıdır, 10 saniyə ərzində yönləndirmə olmadan JSON ilə 200 qaytarmalıdır (YAML dəstəklənmir) və ən çoxu 2 MB olmalıdır.

Minimal etibarlı sənəd:

{
  "openapi": "3.1.0",
  "info": { "title": "DentCloud treatment API", "version": "2026-11" },
  "security": [{ "cosuite": ["patients:read"] }],
  "components": {
    "securitySchemes": {
      "cosuite": { "type": "http", "scheme": "bearer", "bearerFormat": "CoSuite API key", "description": "CoSuite customer API key; the gateway checks the scopes in security" }
    }
  },
  "paths": {
    "/patients": {
      "get": { "operationId": "listPatients", "responses": { "200": { "description": "Patients" } } },
      "post": {
        "operationId": "createPatient",
        "security": [{ "cosuite": ["patients:write"] }],
        "responses": { "201": { "description": "Created" } }
      }
    }
  }
}

Yuxarıdakı cosuite sxemi yekun tərifdir: müştərilər CoSuite API açarlarını şlüzə bearer token kimi göndərir, şlüz security-dəki əhatələri yoxlayır. İstəsəniz servers[0].url sahəsinə API-nizin tətbiqinizlə eyni mənbədəki əsas yolunu yazın (məs. https://app.dentcloud.example/api); şlüz sorğuları ora ötürür.

#Müştərilər API-nə necə çatır

Müştərilər modulunuzun uc nöqtələrini öz CoSuite açarları ilə api.cosuite.io şlüzü vasitəsilə çağırır. Sorğu tətbiqinizə Connect imzası və hansı biznesin çağırdığını bildirən X-CoSuite-Tenant başlığı ilə gəlir. Başlıqlar, öhdəlikləriniz və xəta kodları üçün Şlüz və müştəri API-si səhifəsinə baxın.

#Bazarlar və dillər

• Müştəri yalnız öz ölkəsində təklif olunan modulları görür. markets siyahısını doldursan, modulun yalnız həmin ölkələrdə göstərilir.
• Hər bazarın dillərində mətn məcburidir (bax: qaydalar). Digər dillər istəyə bağlıdır.
• price həmin ölkə üçün yerli qiymət təyin edir. O olmadıqda CoSuite modulun USD qiymətini cari məzənnə ilə çevirir.
• markets boşdursa və ya yoxdursa, modulun harada təklif olunacağına CoSuite qərar verir.

#Açarlar daimidir

Modulun canlıya çıxdıqdan sonra modul, funksiya, limit, scope və webhook açarları müqavilənin bir hissəsinə çevrilir. Onların adını dəyişmə; yeni açar əlavə et və köhnəsini ən azı 6 ay saxla (bax: versiyalama).