# Başlarken

> Yazılımını CoSuite'e modül sağlayıcı olarak bağla. Temel kavramlar, iş ortağı yolculuğu ve 10 dakikada çalışan bir test bağlantısı.

Source: https://cosuite.io/developers

CoSuite modüler bir işletme paketidir: işletme tek bir CoSuite hesabı açar ve ihtiyaç duyduğu modülleri ekler. **CoSuite Connect v1**, yazılımının (örneğin bir diş kliniği sistemi, bir rezervasyon motoru ya da sektöre özel bir ERP) bu modüllerden biri olmasını ve CoSuite kataloğunda satılmasını sağlayan sözleşmedir.

## Bağlanmak sana ne kazandırır {#why}

Uygulaman bağlandığında ürününün çevresindeki her şeyi CoSuite üstlenir:

- **Tek hesap.** İşletme CoSuite'e bir kez kaydolur. Uygulamana işletme (biz buna *kiracı* diyoruz) adı, dili, para birimi, saat dilimi ve sahibiyle birlikte gelir; sen de hesabı otomatik olarak açarsın.
- **Faturalama.** Fiyatlandırma, ödeme, faturalar ve tahsilat CoSuite'te gerçekleşir. Bir CoSuite müşterisine hiçbir zaman ödeme ekranı göstermezsin. Müşterinin neye ödeme yaptığını CoSuite sana *yetki belgeleri* (entitlement) aracılığıyla bildirir.
- **Tek oturum açma (SSO).** Kullanıcılar CoSuite'te "Aç"a tıklar ve uygulamana zaten oturum açmış olarak gelir. Sen yalnızca kısa ömürlü, imzalı bir jetonu doğrularsın; yönetilecek bir parola yoktur.
- **Ekip yönetimi.** Hesap sahipleri iş arkadaşlarını CoSuite'te davet eder ve rollerini orada belirler; üyeler uygulamana senin yerine eklenir ve çıkarılır.
- **Erişim.** Modüllerin, satış yapmayı seçtiğin her ülke için CoSuite kataloğunda, kayıt akışında ve ürün sayfalarında görünür.

Kendi ürününün tüm kontrolü sende kalır: veritabanın, kullanıcılarının verisi, arayüzün ve sürüm döngün. CoSuite seninle yalnızca bu sözleşmedeki uçlar üzerinden konuşur.

## Kavramlar {#concepts}

| Terim | Anlamı |
|---|---|
| **Geliştirici** | Sen: bir uygulamayı geliştiren ve işleten şirket ya da kişi. Bir kez başvurursun ve uygulamalarını [partners.cosuite.io](https://partners.cosuite.io) üzerinden yönetirsin. |
| **Uygulama** | Ürününün CoSuite'teki karşılığı: tek bir taban URL, tek bir anahtar çifti, tek bir manifest. Kısa, küçük harfli bir *uygulama anahtarıyla* tanımlanır, örneğin `dent`. |
| **Modül** | Müşterinin satın aldığı şey. Bir uygulama bir ya da daha fazla modül sunar; her birinin `<appKey>.<module>` biçiminde bir anahtarı vardır, örneğin `dent.treatment`. `core.` ile başlayan anahtarlar CoSuite'e ayrılmıştır. |
| **Özellik** | Bir modülün içindeki adlandırılmış bir yetenek (örneğin "SMS hatırlatma"); isteğe bağlı olarak bir limite bağlanabilir. Özellikler katalogda gösterilir. |
| **Limit** | Müşterinin ödeme yaptığı bir sayı, örneğin `smsPerMonth`. Satın alınan değeri CoSuite gönderir; uygulaman bunu uygular. |
| **API yüzeyi** | Modülünün müşterilere açtığı uçlar; OpenAPI 3.1 ile tanımlanır ve `patients:read` gibi kapsamlarla (scope) korunur. |
| **Kiracı** | CoSuite'teki bir işletme. Opak bir `tenantId` değeri vardır; sen bunu kendi hesap kimliğinle (`localTenantId`) eşlersin. |
| **Yetki belgesi** | Bir kiracının senin modüllerinden hangilerine, hangi limitlerle, ne zamana kadar ve hangi abonelik durumunda sahip olduğunu söyleyen eksiksiz belge (entitlement). |

## İş ortağı yolculuğu {#journey}

1. [partners.cosuite.io](https://partners.cosuite.io) üzerinden **başvur**. Bize şirketini ve ürününü anlat.
2. **Test anahtarını al.** Onaylandıktan sonra bir uygulama oluşturursun ve bir test anahtar çifti alırsın: bir `keyId` (örneğin `csk_dent_test`) ve 32 baytlık bir secret. Secret'ı şifreli sakla ve asla loglara yazma.
3. **Deneme (sandbox) kiracısı kullan.** CoSuite, hazırlık (staging) URL'ine karşı test işletmeleri (`"test": true`) oluşturur. Bunları faturalamazsın, raporlarına girmezler ve CoSuite onları sildiğinde hemen silinirler.
4. Taban URL'inde `/api/cosuite/v1` altındaki uçları **uygula**. Bkz. [sözleşme](https://cosuite.io/developers/contract).
5. **Modüllerini** manifestte **tanımla**: adlar, açıklamalar, özellikler, API, pazarlar. Bkz. [modül tanımı](https://cosuite.io/developers/module-definition).
6. Hazırlık URL'ine karşı **uyumluluk testini çalıştır** ve yeşil olana kadar devam et. Bkz. [SDK ve araçlar](https://cosuite.io/developers/sdk#conformance).
7. İş ortağı portalında **incelemeye gönder**. Uyumluluk sonucunu, modül metinlerini ve veri kategorilerini kontrol ederiz.
8. **Yayına çık.** Canlı anahtar çiftini alırsın ve modüllerin seçtiğin pazarlar için katalogda görünür.

## 10 dakikada test bağlantısı {#quickstart}

Node.js 18.17 ya da daha yeni bir sürüme ihtiyacın var. SDK, sözleşmenin tamamını bellekte uygulayan bir referans uygulama ("mock") ve CoSuite'in uygulaman yayına çıkmadan önce çalıştırdığı uyumluluk testinin aynısıyla gelir.

**1. Referans uygulamayı** bir geliştirme anahtarıyla **başlat.** Secret komut satırından değil, her zaman bir ortam değişkeninden okunur.

```bash
export COSUITE_CONNECT_SECRET="$(openssl rand -hex 32)"
npx --yes --package=https://cosuite.io/developers/sdk/cosuite-connect-1.8.0.tgz cosuite-connect mock --asist dent --port 4010 --key csk_dent_dev
```

**2. Uyumluluk testini** ikinci bir terminalde ona karşı **çalıştır** (aynı `COSUITE_CONNECT_SECRET` ile):

```bash
npx --yes --package=https://cosuite.io/developers/sdk/cosuite-connect-1.8.0.tgz cosuite-connect conformance --url http://127.0.0.1:4010 --key csk_dent_dev
```

Her denetimin geçtiğini ve yeşil bir özet (`YEŞİL`) görmelisin. Uygulamanın bildirmediği yeteneklere ait denetimler atlanır.

**3. Testi kendi uygulamana yönlendir.** SDK ile `/api/cosuite/v1/*` isteklerini karşılayan bir route ekle, ardından aynı komutu hazırlık URL'inle çalıştır. En sade hâliyle bir Next.js route handler:

```ts
// app/api/cosuite/v1/[...path]/route.ts
import { ConnectError, handleConnectRequest, matchAsistRoute, MemoryReplayStore } from "@cosuite/connect";

const replay = new MemoryReplayStore(); // use Redis or your database when you run more than one process
const options = {
  replay,
  secretsFor: (keyId: string) =>
    keyId === process.env.COSUITE_KEY_ID ? [process.env.COSUITE_CONNECT_SECRET!] : undefined,
};

async function handle(req: Request) {
  return handleConnectRequest(req, options, async (ctx) => {
    const route = matchAsistRoute(ctx.url.pathname);
    switch (route?.name) {
      case "manifest":
        return manifest; // your manifest object, see the contract
      case "health":
        return { status: "ok" };
      case "tenants":
        return createOrLinkTenant(ctx.json); // returns { status: 201 | 200, data: { localTenantId, status, created } }
      // ... tenant, entitlements, members, usage, summary
      default:
        throw new ConnectError("not_found", "unknown endpoint");
    }
  });
}

export { handle as GET, handle as POST, handle as PUT, handle as PATCH, handle as DELETE };
```

`handleConnectRequest` imzayı ve zaman damgasını doğrular, gövde boyutu sınırını uygular, istek kimliği tekrarlarını yönetir ve sonucunu yanıt zarfına sarar; böylece handler'ların yalnızca iş mantığını içerir. Node kullanmıyor musun? İmza tek bir fonksiyondan ibarettir; [.NET, PHP ve Python örneklerine](https://cosuite.io/developers/sdk#signature-snippets) göz at.

## Sırada ne var {#next}

- Müşteriler modülünün API'sini doğrudan da çağırabilecek: kendi CoSuite anahtarlarıyla `api.cosuite.io` üzerinden ulaşacaklar, CoSuite de çağrıyı Connect imzasıyla sana iletecek. Müşteri API başvuru belgesi Faz 2'de geliyor; API'ni manifestte bugünden tanımlayabilirsin.
- Soruların mı var? [hello@cosuite.io](mailto:hello@cosuite.io) adresine yaz ya da iş ortağı portalını kullan.