# Modül tanımı > CoSuite modüllerini manifestte tanımla (sözleşme 1.7). Özellikler, OpenAPI 3.1 ve kapsamlarla API, webhook'lar, provides, veri kategorileri, pazarlar ve test kuralları. Source: https://cosuite.io/developers/module-definition Sözleşme sürümü **1.7**'den bu yana [manifestindeki](https://cosuite.io/developers/contract#manifest) 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 {#example} ```json { "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 {#fields} | Alan | Anlamı | |---|---| | `key`, `name`, `limits`, `usage` | Önceki sürümlerden değişmedi (bkz. [sözleşme](https://cosuite.io/developers/contract#manifest)). Modül anahtarı `.`; `name` dil başına, en fazla 200 karakter. | | `description` | Dil başına açıklama, en fazla 1000 karakter. | | `features[]` | Modülün yetenekleri: `key` (küçük harf, `^[a-z][a-z0-9_]*$`), dil başına `name`, isteğe bağlı dil başına `description` ve bağlı olduğu isteğe bağlı bir `limit` (aynı modülün `limits[].key` değerlerinden biri). | | `api` | Modülün müşterilere açtığı uçlar. `openapi`: bir OpenAPI **3.1** belgesi; ya bir URL (https ya da `baseUrl` adresine göre göreli bir yol; yalnızca JSON, en fazla 2 MB) ya da gömülü bir nesne. `scopes[]`: modülün `resource:action` biçimindeki kapsamları (`patients:read`), her biri isteğe bağlı dil başına bir `name` ile. `version`: API sürümün. | | `webhooks[]` | Modülün yaydığı olaylar: `type` (noktalı küçük harf, örneğin `treatment.completed`), isteğe bağlı dil başına `name` ve `description`, isteğe bağlı bir abonelik `scope` değeri (`api.scopes` içinden biri) ve `data` için bir JSON Schema. | | `provides[]` | Modülün CoSuite'te üstlendiği ortak iş işlevleri: `crm`, `quotes`, `einvoice`, `expenses`, `inventory`, `projects`, `inbox`, `booking`, `reviews`, `payments`, `reports`, `website`, `seo`, `social`, `shipping`, `hr`, `pos`. Aynı işletme için aynı işlevi aynı anda iki modül sağlamaz. | | `dataCategories[]` | Modülün işlediği kişisel veriler: `identity`, `contact`, `financial`, `health`, `location`, `biometric`, `children`, `communications`, `media`, `usage`, `employment`, `legal`. Gizlilik bildirimleri (GDPR, KVKK) ve inceleme için kullanılır. | | `markets[]` | Modülün sunulduğu ülkeler (`country`, ISO 3166-1 alpha-2) ve dilleri (`locales`, manifestin `locales` listesinden alınır); isteğe bağlı bir ülke fiyatı `{ currency, amount }`. Boşsa pazar CoSuite'te belirlenir. | 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 {#rules} [Uyumluluk testi](https://cosuite.io/developers/sdk#conformance) 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 {#openapi} 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": [""] }]`. 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: ```json { "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 {#gateway} 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](https://cosuite.io/developers/contract#signature) 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](https://cosuite.io/developers/customer-api) sayfasına bakın. ## Pazarlar ve diller {#markets} - 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](#rules)). 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 {#permanent-keys} 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](https://cosuite.io/developers/contract#versioning)).