Ağ geçidi ve müşteri API'si

Müşteriler modülünüzün API'sini https://api.cosuite.io/v1/apps/{app}/{path} adresinden kendi CoSuite API anahtarlarıyla çağırır. CoSuite anahtarı, aboneliği ve kapsamı denetler, ardından isteği uygulamanıza Connect imzasıyla ve çağıran işletmeyi X-CoSuite-Tenant başlığında belirterek iletir. Uygulamanız müşterinin anahtarını, müşteri de sizinkini hiç görmez.

Müşteri yazılımı ──Bearer cs_api_…──▶ api.cosuite.io/v1/apps/dent/patients
                                            │  anahtar · abonelik · yol · kapsam · hız sınırı
                                            ▼
                      {server}/patients  ◀── Connect imzası + X-CoSuite-Tenant

#Uygulamanız için: ağ geçidi isteklerini karşılamak

Ağ geçidi yalnız modülünüzün OpenAPI 3.1 belgesinde bulunan işlemleri iletir. Bunun için müşterinin anahtarında, işlemin istediği bir kapsam olmalıdır.

Adres. OpenAPI belgenizdeki servers[0].url, uygulamanızın temel adresiyle aynı kökendeyse istekler oraya gider; değilse temel adrese. Yol ve sorgu değiştirilmeden eklenir: GET /v1/apps/dent/patients?page=2 → GET {server}/patients?page=2.

Gelen başlıklar (Connect imza başlıklarına ek olarak):

Müşterinin Authorization başlığı hiçbir zaman iletilmez.

Yükümlülükleriniz:

• İmzayı doğrulayın ve tekrar kullanılan istek kimliklerini reddedin. verifyGatewayRequest ikisini birlikte yapar.
• Bilinmeyen ya da bağlı olmayan bir tenantId için 404 ve tenant_not_found döndürün, hiç veri döndürmeyin.
• 30 saniye içinde, en fazla 10 MB'lık bir yanıt verin ve asla yönlendirme yapmayın (3xx hata sayılır).
• İşlemin kapsamını ağ geçidi zaten denetledi; X-CoSuite-Scopes ile ayrıca daraltabilirsiniz.

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

const replay = new MemoryReplayStore(); // birden çok süreçte Redis ya da veritabanınızı kullanın

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) });
}

Diğer dillerde imzayı Connect çağrılarındaki gibi doğrulayın ve yukarıdaki başlıkları okuyun.

Uyumluluk testi. api tanımı olan her modülde, test parametresiz en fazla üç GET işlemini çağırır:

1. Test işletmesiyle: bir yanıt beklenir.
2. Bilinmeyen bir işletmeyle: 404 tenant_not_found beklenir.
3. İmzasız olarak: 401 beklenir.

#Müşteriler için: API'yi çağırmak

1. CoSuite panelinde Yönetim › API anahtarları ekranını açın ve bir anahtar oluşturun. Uygulamayı ve yalnız ihtiyacınız olan kapsamları seçin; mümkünse bir geçerlilik süresi belirleyin. Anahtar bir kez gösterilir.
2. Anahtarı bearer token olarak gönderin:

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

Anahtar şu koşullarda çalışır:

• Yalnız oluşturulduğu uygulama için.
• Yalnız seçtiğiniz kapsamlarla.
• Yalnız modül aboneliğinizde olduğu sürece. Modülü bırakınca kapsamları çalışmaz olur.

Kaldırılan ya da süresi dolan anahtar hemen reddedilir.

Her çağrı API denetim kaydına yazılır ve 12 ay tutulur: anahtar, uç, kapsam, durum ve süre. Gövdeler asla kaydedilmez.

Sınırlar:

• İstek gövdesi en fazla 2 MB.
• İşletme başına dakikada 600, anahtar başına dakikada 300 istek.
• Art arda 5 kez hata veren uygulama 60 saniye bekletilir.

#Web kancaları

Uygulamanız, bir modülün yaydığı olayları manifest'te tanımlar (modules[].webhooks[], bkz. modül tanımı). Her olayı CoSuite'e diğer olaylar gibi gönderir: POST /connect/v1/events, gövdede tenantId, tekil bir id, tanımlı type ve data. CoSuite olayı abone olan işletmelere iletir; gövdeyi teslimden sonra saklamaz.

Müşteriler aboneliği Yönetim › API anahtarları › Web kancaları ekranından kurar: uygulamayı, olayları ve bir https adresi seçerler, imza için gizli değeri bir kez alırlar. Her teslim bir POST isteğidir. JSON gövdesi { "id", "type", "app", "occurredAt", "data" } biçimindedir, şu başlıkları taşır:

İmzayı doğrulayın, zamanı 5 dakika içindeyse kabul edin ve 10 saniye içinde 2xx ile yanıt verin. Başarısız teslimler 24 saate kadar yeniden denenir (1, 5, 15, 60, 180, 360 ve 720 dakika sonra). Tekrarları olay id'siyle ayıklayın.

#Hatalar

Uygulamanın kendi yanıtları (durum kodu ve gövde) değiştirilmeden döner. Ağ geçidinin ürettiği hatalar Connect zarfını kullanır: { "ok": false, "error": { "code", "message", "retryable" } }.

Ağ geçidinin her yanıtında X-CoSuite-Request-Id başlığı bulunur; destekle iletişime geçerken bu kimliği belirtin.