# Başlanğıc

> Proqramını modul təminatçısı kimi CoSuite-ə qoş. Əsas anlayışlar, partnyor yolu və 10 dəqiqədə işləyən test bağlantısı.

Source: https://cosuite.io/az/developers

CoSuite modullu biznes paketidir: biznes bir CoSuite hesabı açır və ehtiyac duyduğu modulları əlavə edir. **CoSuite Connect v1** sənin proqramının, məsələn, diş klinikası sisteminin, rezervasiya mühərrikinin və ya sahəyə xas ERP-nin bu modullardan birinə çevrilməsinə və CoSuite kataloqunda satılmasına imkan verən müqavilədir.

## Qoşulmaq sənə nə verir {#why}

Tətbiqin qoşulduqda məhsulun ətrafındakı hər şeyi CoSuite öz üzərinə götürür:

- **Bir hesab.** Biznes CoSuite-də bir dəfə qeydiyyatdan keçir. Tətbiqin biznesi (biz buna *tenant* deyirik) adı, dili, valyutası, saat qurşağı və sahibi ilə birlikdə alır, sən də hesabı avtomatik açırsan.
- **Ödəniş.** Qiymətləndirmə, ödəniş səhifəsi, fakturalar və ödənişlərin yığılması CoSuite-də olur. CoSuite müştərisinə heç vaxt ödəniş ekranı göstərmirsən. Müştərinin nəyə görə ödədiyini CoSuite sənə *entitlement* (istifadə hüququ) vasitəsilə bildirir.
- **Vahid giriş (SSO).** İstifadəçilər CoSuite-də "Aç" düyməsinə basır və artıq daxil olmuş halda sənin tətbiqinə düşür. Sən qısa ömürlü imzalı tokeni yoxlayırsan; idarə ediləcək şifrə yoxdur.
- **Komanda idarəetməsi.** Sahiblər həmkarlarını CoSuite-də dəvət edir və rollarını təyin edir; üzvlər sənin tətbiqinə sənin əvəzinə əlavə edilir və oradan çıxarılır.
- **Əhatə.** Modulların satmağı seçdiyin hər ölkə üçün CoSuite kataloqunda, qeydiyyat axınında və məhsul səhifələrində görünür.

Öz məhsulun üzərində tam nəzarət səndə qalır: verilənlər bazan, istifadəçilərinin məlumatları, interfeysin və buraxılış dövrün. CoSuite səninlə yalnız bu müqavilədəki endpoint-lər vasitəsilə danışır.

## Anlayışlar {#concepts}

| Termin | Mənası |
|---|---|
| **Tərtibatçı** | Sən: tətbiqi quran və işlədən şirkət və ya şəxs. Bir dəfə müraciət edirsən və tətbiqlərini [partners.cosuite.io](https://partners.cosuite.io) ünvanında idarə edirsən. |
| **Tətbiq** | CoSuite-in gördüyü şəkildə sənin məhsulun: bir əsas URL, bir açar cütü, bir manifest. Qısa, kiçik hərfli *tətbiq açarı* ilə tanınır, məsələn, `dent`. |
| **Modul** | Müştərinin aldığı şey. Tətbiq bir və ya bir neçə modul təklif edir; hər birinin `<appKey>.<module>` formasında açarı var, məsələn, `dent.treatment`. `core.` ilə başlayan açarlar CoSuite üçün ayrılıb. |
| **Funksiya** | Modulun daxilində adı olan imkan (məsələn, "SMS xatırlatmaları"); istəyə görə bir limitə bağlana bilər. Funksiyalar kataloqda göstərilir. |
| **Limit** | Müştərinin ödədiyi rəqəm, məsələn, `smsPerMonth`. CoSuite alınmış dəyəri göndərir, tətbiqin isə ona riayət olunmasını təmin edir. |
| **API səthi** | Modulunun müştərilərə açdığı endpoint-lər; OpenAPI 3.1 ilə təsvir olunur və `patients:read` kimi scope-larla qorunur. |
| **Tenant** | CoSuite-dəki biznes. Onun qeyri-şəffaf `tenantId` identifikatoru var; sən onu öz hesab identifikatoruna (`localTenantId`) uyğunlaşdırırsan. |
| **Entitlement** | Tenant-ın sənin hansı modullarına, hansı limitlərlə, hansı tarixə qədər və hansı abunə vəziyyətində sahib olduğunu göstərən tam sənəd. |

## Partnyor yolu {#journey}

1. **Müraciət et:** [partners.cosuite.io](https://partners.cosuite.io). Bizə şirkətin və məhsulun haqqında danış.
2. **Test açarı al.** Təsdiqdən sonra tətbiq yaradırsan və test açar cütü alırsan: `keyId` (məsələn, `csk_dent_test`) və 32 baytlıq gizli açar (secret). Gizli açarı şifrələnmiş saxla və heç vaxt loglara yazma.
3. **Sandbox tenant-dan istifadə et.** CoSuite staging URL-inə qarşı test bizneslər (`"test": true`) yaradır. Onlara ödəniş yazmırsan, hesabatlarına düşmürlər və CoSuite onları silən kimi dərhal silinirlər.
4. **Əsas URL-ində `/api/cosuite/v1` altındakı endpoint-ləri reallaşdır.** Bax: [müqavilə](https://cosuite.io/az/developers/contract).
5. **Modullarını manifestdə təsvir et:** adlar, təsvirlər, funksiyalar, API, bazarlar. Bax: [modul tərifi](https://cosuite.io/az/developers/module-definition).
6. **Uyğunluq testini** staging URL-inə qarşı yaşıl olana qədər işə sal. Bax: [SDK və alətlər](https://cosuite.io/az/developers/sdk#conformance).
7. **Partnyor portalında yoxlamaya göndər.** Uyğunluq nəticəsini, modul mətnlərini və məlumat kateqoriyalarını yoxlayırıq.
8. **Canlıya çıx.** Canlı açar cütü alırsan və modulların seçdiyin bazarlar üçün kataloqda görünür.

## 10 dəqiqədə test bağlantısı {#quickstart}

Sənə Node.js 18.17 və ya daha yeni versiya lazımdır. SDK bütün müqaviləni yaddaşda reallaşdıran istinad tətbiqi ("mock") və CoSuite-in tətbiqin canlıya çıxmazdan əvvəl işə saldığı eyni uyğunluq testi ilə birlikdə gəlir.

**1. İstinad tətbiqini** inkişaf açarı ilə başlat. Gizli açar əmr sətrindən yox, mühit dəyişənindən oxunur.

```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. Uyğunluq testini** ikinci terminalda ona qarşı işə sal (eyni `COSUITE_CONNECT_SECRET` ilə):

```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
```

Bütün yoxlamaların keçdiyini və yaşıl yekunu (`YEŞİL`) görməlisən. Tətbiqin elan etmədiyi imkanlar üçün yoxlamalar ötürülür.

**3. Testi öz tətbiqinə yönəlt.** SDK ilə `/api/cosuite/v1/*` yollarını emal edən route əlavə et, sonra eyni əmri staging URL-inlə işə sal. Minimal 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` imzanı və zaman möhürünü yoxlayır, sorğu gövdəsinin ölçü limitini tətbiq edir, request-id təkrarlarını idarə edir və nəticəni cavab zərfinə bükür; beləliklə, handler-lərində yalnız biznes məntiqi qalır. Node istifadə etmirsən? İmza tək bir funksiyadır; bax: [.NET, PHP və Python nümunələri](https://cosuite.io/az/developers/sdk#signature-snippets).

## Bundan sonra nə var {#next}

- Müştərilər modulunun API-sini birbaşa da çağıra biləcək: ona öz CoSuite açarları ilə `api.cosuite.io` üzərindən çatacaqlar, CoSuite isə çağırışı Connect imzası ilə sənə ötürəcək. Müştəri API arayışı 2-ci mərhələdə gəlir; API-ni manifestdə indidən təsvir edə bilərsən.
- Sualın var? [hello@cosuite.io](mailto:hello@cosuite.io) ünvanına yaz və ya partnyor portalından istifadə et.