Klinikler ve X-Tenant

Flextell’de veriler kliniğe aittir. Bir kullanıcı birden fazla kliniğin üyesi olabilir ve her klinikte farklı rollere sahip olabilir. Bu sayfa, hangi kliniklerin var olduğunu nasıl öğreneceğinizi ve klinik verisi isteyen her çağrıda hangi klinikle çalıştığınızı X-Tenant başlığıyla nasıl belirteceğinizi anlatır.

Klinik nedir

Klinik, Flextell’de hastaların, randevuların, kullanıcıların ve ayarların bağlı olduğu hesaptır. Panelde Klinikler olarak, API’de tenant olarak geçer. Kullanıcı bir kliniğe üyelik (davet kabulü veya klinik oluşturma) yoluyla bağlanır. Bir klinik isteğinin sonucu üç şeyin kesişimiyle belirlenir:

Erişim token’ınızdaki scope’lar (uygulamanın ne isteyebileceği).
Kullanıcının seçtiğiniz klinikteki izinleri (kullanıcının ne yapabileceği).
Kullanıcının o kliniğe üyeliği.

Bir kullanıcının izinleri kliniğe göre değişir. Aynı kullanıcı A kliniğinde yönetici, B kliniğinde yalnızca görüntüleyici olabilir. Üçüncü taraf uygulamanız, kullanıcının üyesi olduğu her klinikte çalışabilir; ancak her klinikte yalnızca uygulamanın scope’larıyla ve kullanıcının o klinikteki rolleriyle sınırlıdır. Ayrıntı için İzinler ve görünürlük ve Scope’lar sayfalarına bakın.

Klinikleri listeleme

Kullanıcının üyesi olduğu klinikleri GET /api/v1/account/tenants ile alın. Bu çağrı account:read scope’u ister ve X-Tenant göndermez. X-Tenant olarak kullanacağınız geçerli değerlerin kaynağı bu listedir.

Metot	Endpoint	Açıklama	Scope
GET	`/api/v1/account/tenants`	Kullanıcının üyesi olduğu klinikler	`account:read`
GET	`/api/v1/account`	Kullanıcı profili; `tenants[]` alanında klinikleri de içerir	`account:read`
GET	`/api/v1/account/roles`	Seçili klinikteki rol ve izinler (`X-Tenant` gerekir)	`account:read`

curl "https://app.flextell.ai/api/v1/account/tenants" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"

{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "Örnek Klinik",
      "slug": "ornek-klinik",
      "avatar_url": null,
      "is_active": true,
      "setup_required": false
    }
  ]
}

Alan	Tür	Açıklama
`id`	sayı	Klinik kimliği. `X-Tenant` başlığına bu değeri yazın.
`name`	metin	Klinik adı.
`slug`	metin	Kısa ad. `X-Tenant` için kullanılmaz.
`avatar_url`	metin veya `null`	Klinik görseli için imzalı adres; yaklaşık 1 saat geçerlidir. Görsel yoksa `null`.
`is_active`	mantıksal	Kliniğin aktif olup olmadığı.
`setup_required`	mantıksal	Zorunlu kurulum adımları açıksa `true`.

Liste, silinmiş klinikleri içermez. GET /api/v1/account yanıtındaki tenants[] alanında setup_required bulunmaz; bu alan yalnızca GET /api/v1/account/tenants yanıtında gelir.

X-Tenant başlığı

Klinik verisi okuyan veya yazan her endpoint, hangi klinikle çalıştığınızı X-Tenant başlığıyla ister. Değer, kliniğin sayısal id değeridir; slug değildir.

curl "https://app.flextell.ai/api/v1/customers?per_page=15" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: 123" \
  -H "Accept: application/json"

Sunucu başlığı şöyle işler:

Durum	Sonuç
Başlık yok veya boş	`400` `TENANT_HEADER_REQUIRED`
Değer yalnızca rakamlardan oluşmuyor veya sıfır	`404` `TENANT_NOT_FOUND`
Klinik yok, silinmiş ya da kullanıcı üye değil	`404` `TENANT_NOT_FOUND`
Klinik geçerli ve kullanıcı üye	İstek o klinik bağlamında çalışır

Üye olmadığınız bir klinik için de 403 değil 404 TENANT_NOT_FOUND döner. Böylece bir klinik kimliğinin var olup olmadığı dışarıdan anlaşılamaz.

Seçtiğiniz klinik, isteğin tamamında rolleri, izinleri ve kayıt görünürlüğünü belirler. Klinik bağlamındaki her yanıtta X-Timezone başlığı kliniğin saat dilimini (ör. Europe/Istanbul) taşır. Başlığın genel kuralları için İstek başlıkları sayfasına bakın.

İstek gövdesinde tenant adlı bir alan gönderirseniz, sunucu bu alanı seçili klinik bilgisiyle ezer. Gövdede tenant adını kullanmayın.

Kullanıcının seçili kliniğe göre yapabilecekleri

GET /api/v1/account/roles çağrısı X-Tenant ile seçtiğiniz klinikteki rol adlarını ve izin adlarını döndürür. Kullanıcıya göstereceğiniz düğmeleri ve menüleri bu listeye göre açıp kapatabilirsiniz.

curl "https://app.flextell.ai/api/v1/account/roles" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: 123" \
  -H "Accept: application/json"

{ "roles": ["super_admin"], "permissions": ["View:User", "View:Customer"] }

Bu çağrı da klinik kapsamındadır; kliniğin aboneliği bitmişse veya gecikmiş ödeme varsa 402 döner (bkz. Hatalar).

Klinik gerektirmeyen endpoint’ler

Aşağıdaki endpoint grupları X-Tenant istemez:

Grup	Not
`/api/v1/account*`	Tek istisna `GET /api/v1/account/roles`; o `X-Tenant` ister.
`/api/v1/general/*`	Ülke, para birimi gibi ortak arama listeleri. Yalnızca bearer token gerekir.
`/api/v1/channels/capabilities`	Kanal yetenekleri.
`/api/v1/invitations/preview`	Davet önizlemesi (herkese açık).
`/api/v1/public/forms/*`	Herkese açık hasta formları.
`/api/v1/integrations/inbound/*`	Gelen entegrasyon webhook’ları.

Diğer tüm klinik endpoint’leri X-Tenant ister. Bunlara /api/v1/oauth/* (OAuth uygulamaları ve GET /api/v1/oauth/scopes) ve /api/v1/announcements de dahildir. OAuth uygulamalarını yönetirken izin de başlıkta verdiğiniz klinik için kontrol edilir; başka bir klinikteki izin bu istek için geçerli olmaz. Bkz. OAuth uygulamaları.

Duyurular (/api/v1/announcements) içerik olarak tüm kliniklere ortaktır; yine de çağrı X-Tenant ve View:Announcement izni ister. Bu izin tüm klinik rollerinde bulunur.

Klinik değiştirme

Klinik değiştirmek için yeni bir token almanız gerekmez. Aynı access token tüm kliniklerde geçerlidir; yalnızca X-Tenant değerini değiştirirsiniz. Önerilen akış:

Kullanıcıyı doğrulayın

Yetkilendirme kodu ve PKCE akışıyla token alın. Token’ın account:read scope’unu içerdiğinden emin olun.

Klinikleri listeleyin

GET /api/v1/account/tenants çağrısını X-Tenant olmadan yapın.

Kliniği seçin

Kullanıcıya liste gösterin ya da tek klinik varsa doğrudan onu kullanın. Seçilen kliniğin id değerini saklayın.

Her istekte gönderin

Klinik endpoint’lerine yaptığınız her çağrıya X-Tenant: <tenant_id> ekleyin. Başka bir kliniğe geçerken yalnızca bu değeri değiştirin ve izin listesini GET /api/v1/account/roles ile yeniden yükleyin.

Flextell paneli oturum açtıktan sonra klinik listesini alır, son seçilen kliniği hatırlar ve yoksa listedeki ilk kliniği seçer; seçili klinik artık erişilebilir değilse sizi klinik seçmeye yönlendirir. Mobil uygulama aynı mantıkla çalışır ve klinik adı yerine Firma der. Uygulamanızda da aynı yaklaşımı izleyebilirsiniz.

Kullanıcı kliniğe üyeliğini yitirirse veya klinik silinirse, sakladığınız id ile yapılan istekler 404 TENANT_NOT_FOUND döner. Bu durumda listeyi yeniden alın ve kullanıcıdan kliniği yeniden seçmesini isteyin.

Hatalar

Klinik endpoint’lerinde istek şu sırayla denetlenir ve ilk başarısız denetim yanıtı belirler: 401 (token) → 429 (oran sınırı) → 400/404 (X-Tenant) → 402 (abonelik) → 428 (kurulum) → 403 (scope) → 403 (izin) → 404/422 (kaynak ve doğrulama) Tek istisna GET /api/v1/account/roles: bu çağrıda scope denetimi X-Tenant denetiminden önce yapılır.

Kod	HTTP	Ne zaman
`UNAUTHENTICATED`	401	Token yok, geçersiz, süresi dolmuş veya iptal edilmiş. `Kimlik doğrulaması gerekli.`
`TENANT_HEADER_REQUIRED`	400	`X-Tenant` yok veya boş. `X-Tenant başlığı zorunludur.`
`TENANT_NOT_FOUND`	404	Değer sayısal değil, klinik yok ya da silinmiş, kullanıcı üye değil. `Klinik bulunamadı.`
`SUBSCRIPTION_REQUIRED`	402	Kliniğin aboneliği sona ermiş. `data` alanı abonelik özetini taşır.
`ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT`	402	Gecikmiş ödeme var. `data.proforma_invoice_id` ve `data.due_date` döner.
`SETUP_REQUIRED`	428	Zorunlu kurulum adımları tamamlanmamış. `data.next_step` bir sonraki adımı belirtir.
`FORBIDDEN`	403	Token’da gerekli scope yok (`Invalid scope(s) provided.`) ya da kullanıcının o klinikte izni yok (`Bu işlem için yetkiniz yok.`).

Hata zarfı ve genel hata kodları için Hatalar ve Hata kodları sayfalarına bakın. 402 ve 428 kilitlerinin ayrıntıları ve hangi yolların bu kilitlerden muaf olduğu Erişim kilitleri sayfasındadır.

404 TENANT_NOT_FOUND aldığınızda önce X-Tenant değerinin slug değil sayısal id olduğunu, ardından kullanıcının o kliniğin üyesi olduğunu kontrol edin. Üyelik için GET /api/v1/account/tenants çağrısına bakın.

İlgili sayfalar

İzinler ve görünürlük

Klinik bazında izinlerin ve kayıt görünürlüğünün nasıl çalıştığı.

Scope'lar

Uygulamanızın isteyebileceği scope’lar.

Erişim kilitleri

402 ve 428 yanıtları.

Hesap

Hesap ve klinik endpoint’leri.

Başlarken

Kimlik Doğrulama

Çok Kiracılılık

İstek Kuralları

Kaynak Rehberleri

Gerçek Zamanlı

Webhook'lar ve Açık Uçlar

Entegrasyonlar

Rehberler

Kaynaklar

Klinikler ve X-Tenant

Klinik nedir

Klinikleri listeleme

X-Tenant başlığı

Kullanıcının seçili kliniğe göre yapabilecekleri

Klinik gerektirmeyen endpoint’ler

Klinik değiştirme

Hatalar

İlgili sayfalar

İzinler ve görünürlük

Scope'lar

Erişim kilitleri

Hesap

​Klinik nedir

​Klinikleri listeleme

​X-Tenant başlığı

​Kullanıcının seçili kliniğe göre yapabilecekleri

​Klinik gerektirmeyen endpoint’ler

​Klinik değiştirme

​Hatalar

​İlgili sayfalar

İzinler ve görünürlük

Scope'lar

Erişim kilitleri

Hesap

Klinik nedir

Klinikleri listeleme

X-Tenant başlığı

Kullanıcının seçili kliniğe göre yapabilecekleri

Klinik gerektirmeyen endpoint’ler

Klinik değiştirme

Hatalar

İlgili sayfalar