Modül tanımı

Sözleşme sürümü 1.7'den bu yana manifestindeki her modül kendini ayrıntılı olarak tanımlayabilir. CoSuite kataloğu, kayıt akışı, uygulamanın CoSuite'teki sayfası, cosuite.io ürün sayfaları ve (Faz 2'de) müşteri API başvuru belgesi bu alanlardan üretilir. Her alan isteğe bağlıdır; bir 1.6 manifesti olduğu gibi geçerli kalır.

#Örnek

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

#Alanlar

Sınırlar bir bakışta: modül başına en fazla 64 özellik, 64 kapsam, 64 webhook, 16 provides, 32 veri kategorisi ve 100 pazar.

#Uyumluluk testinin uyguladığı kurallar

Uyumluluk testi yalnızca doldurduğun alanları denetler. İş ortağı portalı da gönderdiğinde aynı denetimleri çalıştırır.

• Her pazar dilinde metin. markets içinde kullanılan her dil için modülün name ve description alanları ile her özelliğin name alanı doldurulmuş olmalıdır.
• Pazar dilleri manifestten gelir. markets[].locales içindeki her dil, manifestin locales listesinde de bulunmalıdır.
• features, api.scopes, webhooks (type değerine göre) ve markets (country değerine göre) içinde yinelenen anahtar olmaz; provides içinde de yineleme olmaz.
• Özellik limitleri mevcuttur. Bir özelliğin limit değeri modülün limits[].key değerlerinden biri olmalıdır.
• Webhook kapsamları mevcuttur. Bir webhook'un scope değeri bir api tanımı gerektirir ve api.scopes içinden biri olmalıdır.
• Yalnızca bilinen değerler. provides ve dataCategories yalnızca yukarıda listelenen değerleri kabul eder. CoSuite'in kendisi bilinmeyen değerleri yok sayar (ileriye uyumluluk), ama test yazım hatalarını yakalamak için onları reddeder.
• api içeren her modül için OpenAPI denetlenir: belge indirilir (ya da satır içinden okunur) ve aşağıda anlatıldığı gibi doğrulanır.

#OpenAPI gereksinimleri

Test, CoSuite'in dayandığı kısımları denetler; tam bir şema doğrulaması değildir.

• openapi değeri 3.1.x; info.title ve info.version mevcut; paths boş değil ve her yol / ile başlıyor.
• Her işlem (operation), cosuite güvenlik şeması üzerinden en az bir kapsam gerektirir: security: [{ "cosuite": ["<scope>"] }]. Kendi security tanımı olmayan bir işlem, kök düzeydeki security tanımını devralır.
• Belgede kullanılan her kapsam, modülün api.scopes listesinde tanımlanmış olmalıdır.
• operationId değerleri benzersizdir.
• openapi bir URL olduğunda: baseUrl adresin https ise https olmalı, yönlendirme olmadan 10 saniye içinde JSON ile 200 dönmeli (YAML desteklenmez) ve en fazla 2 MB olmalıdır.

En sade geçerli belge:

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

Yukarıdaki cosuite şeması kesin tanımdır: müşteriler CoSuite API anahtarlarını ağ geçidine bearer token olarak gönderir, ağ geçidi security içindeki kapsamları denetler. İsterseniz servers[0].url alanına API'nizin, uygulamanızla aynı kökendeki temel yolunu yazın (ör. https://app.dentcloud.example/api); ağ geçidi istekleri oraya iletir.

#Müşteriler API'ne nasıl ulaşır

Müşteriler modülünüzün uçlarını kendi CoSuite anahtarlarıyla api.cosuite.io ağ geçidi üzerinden çağırır. İstek uygulamanıza Connect imzasıyla ve hangi işletmenin çağırdığını bildiren X-CoSuite-Tenant başlığıyla gelir. Başlıklar, yükümlülükleriniz ve hata kodları için Ağ geçidi ve müşteri API'si sayfasına bakın.

#Pazarlar ve diller

• Bir müşteri yalnızca kendi ülkesinde sunulan modülleri görür. markets listelersen modülün yalnızca o ülkelerde gösterilir.
• Her pazarın dillerinde metin zorunludur (bkz. kurallar). Diğer diller isteğe bağlıdır.
• price o ülke için yerel bir fiyat belirler. Yoksa CoSuite modülün USD fiyatını güncel döviz kuruyla çevirir.
• markets boşsa ya da yoksa modülün nerede sunulacağına CoSuite karar verir.

#Anahtarlar kalıcıdır

Modülün yayına çıktıktan sonra modül, özellik, limit, kapsam ve webhook anahtarları sözleşmenin parçasıdır. Onları yeniden adlandırma; yeni bir anahtar ekle ve eskisini en az 6 ay koru (bkz. sürümleme).