Başlarken

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

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

#İş ortağı yolculuğu

1. 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.
5. Modüllerini manifestte tanımla: adlar, açıklamalar, özellikler, API, pazarlar. Bkz. modül tanımı.
6. Hazırlık URL'ine karşı uyumluluk testini çalıştır ve yeşil olana kadar devam et. Bkz. SDK ve araçlar.
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ı

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.

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):

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:

// 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 göz at.

#Sırada ne var

• 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 adresine yaz ya da iş ortağı portalını kullan.