Şlüz və müştəri API-si

Müştərilər modulunuzun API-sini https://api.cosuite.io/v1/apps/{app}/{path} ünvanından öz CoSuite API açarları ilə çağırır. CoSuite açarı, abunəliyi və əhatəni yoxlayır, sonra sorğunu tətbiqinizə Connect imzası ilə ötürür; çağıran biznes X-CoSuite-Tenant başlığında göstərilir. Tətbiqiniz müştərinin açarını, müştəri də sizinkini heç vaxt görmür.

Müştəri proqramı ──Bearer cs_api_…──▶ api.cosuite.io/v1/apps/dent/patients
                                            │  açar · abunəlik · yol · əhatə · sürət limiti
                                            ▼
                      {server}/patients  ◀── Connect imzası + X-CoSuite-Tenant

#Tətbiqiniz üçün: şlüz sorğularına cavab vermək

Şlüz yalnız modulunuzun OpenAPI 3.1 sənədində olan əməliyyatları ötürür. Bunun üçün müştərinin açarında əməliyyatın tələb etdiyi əhatələrdən biri olmalıdır.

Ünvan. OpenAPI sənədinizdəki servers[0].url tətbiqinizin əsas ünvanı ilə eyni mənbədədirsə, sorğular ora gedir; əks halda əsas ünvana. Yol və sorğu parametrləri dəyişmədən əlavə olunur: GET /v1/apps/dent/patients?page=2 → GET {server}/patients?page=2.

Gələn başlıqlar (Connect imza başlıqlarına əlavə olaraq):

Müştərinin Authorization başlığı heç vaxt ötürülmür.

Öhdəlikləriniz:

• İmzanı yoxlayın və təkrarlanan sorğu identifikatorlarını rədd edin. verifyGatewayRequest hər ikisini birlikdə edir.
• Naməlum və ya bağlanmamış tenantId üçün 404 və tenant_not_found qaytarın; heç bir məlumat qaytarmayın.
• 30 saniyə ərzində, ən çox 10 MB olan cavab verin və heç vaxt yönləndirmə etməyin (3xx xəta sayılır).
• Əməliyyatın əhatəsini şlüz artıq yoxlayıb; X-CoSuite-Scopes ilə əlavə məhdudlaşdıra bilərsiniz.

import { verifyGatewayRequest, MemoryReplayStore } from "@cosuite/connect";

const replay = new MemoryReplayStore(); // bir neçə prosesdə Redis və ya verilənlər bazanızdan istifadə edin

export async function GET(req: Request) {
  const url = new URL(req.url);
  const body = await req.text();
  const v = await verifyGatewayRequest({
    method: req.method,
    pathAndQuery: url.pathname + url.search,
    body,
    headers: req.headers,
    secretsFor: (keyId) => (keyId === process.env.COSUITE_KEY_ID ? [process.env.COSUITE_SECRET!] : undefined),
    replay,
  });
  if (!v.ok) return Response.json({ ok: false, error: { code: "unauthorized", message: v.reason, retryable: false } }, { status: 401 });

  const account = await findAccountByCoSuiteTenant(v.context.tenantId);
  if (!account) return Response.json({ ok: false, error: { code: "tenant_not_found", message: "tenant not found", retryable: false } }, { status: 404 });

  return Response.json({ items: await listPatients(account.id) });
}

Digər dillərdə imzanı Connect çağırışlarındakı kimi yoxlayın və yuxarıdakı başlıqları oxuyun.

Uyğunluq testi. api tərifi olan hər modulda test parametrsiz ən çox üç GET əməliyyatını çağırır:

1. Test biznesi ilə: cavab gözlənilir.
2. Naməlum biznes ilə: 404 tenant_not_found gözlənilir.
3. İmzasız: 401 gözlənilir.

#Müştərilər üçün: API-ni çağırmaq

1. CoSuite panelində İdarəetmə › API açarları bölməsini açın və açar yaradın. Tətbiqi və yalnız lazım olan əhatələri seçin; mümkünsə etibarlılıq müddəti təyin edin. Açar yalnız bir dəfə göstərilir.
2. Açarı bearer token kimi göndərin:

curl -H "Authorization: Bearer $COSUITE_API_KEY" \
  "https://api.cosuite.io/v1/apps/dent/patients?page=2"

Açar bu şərtlərlə işləyir:

• Yalnız yaradıldığı tətbiq üçün.
• Yalnız seçdiyiniz əhatələrlə.
• Yalnız modul abunəliyinizdə olduğu müddətcə. Modulu buraxdıqda onun əhatələri işləməz.

Ləğv edilmiş və ya müddəti bitmiş açar dərhal rədd edilir.

Hər çağırış API audit qeydinə yazılır və 12 ay saxlanılır: açar, uc nöqtə, əhatə, status və müddət. Gövdələr heç vaxt saxlanılmır.

Limitlər:

• Sorğu gövdəsi ən çox 2 MB.
• Biznes başına dəqiqədə 600, açar başına dəqiqədə 300 sorğu.
• Ardıcıl 5 dəfə xəta verən tətbiq 60 saniyə dayandırılır.

#Veb-hooklar

Tətbiqiniz modulun yaydığı hadisələri manifestdə təyin edir (modules[].webhooks[], bax: modul tərifi). Hər hadisəni CoSuite-ə digər hadisələr kimi göndərir: POST /connect/v1/events, gövdədə tenantId, unikal id, təyin olunmuş type və data. CoSuite hadisəni abunə olan bizneslərə ötürür; gövdəni çatdırıldıqdan sonra saxlamır.

Müştərilər abunəliyi İdarəetmə › API açarları › Veb-hooklar bölməsində qurur: tətbiqi, hadisələri və https ünvanı seçirlər, imza üçün gizli dəyəri bir dəfə alırlar. Hər çatdırılma bir POST sorğusudur. JSON gövdəsi { "id", "type", "app", "occurredAt", "data" } formasındadır və bu başlıqları daşıyır:

İmzanı yoxlayın, vaxt 5 dəqiqə daxilindədirsə qəbul edin və 10 saniyə ərzində 2xx ilə cavab verin. Uğursuz çatdırılmalar 24 saata qədər təkrar sınanır (1, 5, 15, 60, 180, 360 və 720 dəqiqədən sonra). Təkrarları hadisə id-si ilə ayıklayın.

#Xətalar

Tətbiqin öz cavabları (status və gövdə) dəyişmədən qaytarılır. Şlüzün yaratdığı xətalar Connect zərfindən istifadə edir: { "ok": false, "error": { "code", "message", "retryable" } }.

Şlüzün hər cavabında X-CoSuite-Request-Id başlığı var; dəstəklə əlaqə saxlayarkən bu identifikatoru göstərin.