Hızlı başlangıç

Bu sayfa, Flextell API’sine ilk isteğinizi göndermeniz için gereken en kısa yolu gösterir: bir uygulama oluşturur, bir kullanıcıdan yetki alır, access_token edinir, klinik seçer ve Hastalar listesini çekersiniz. Her adımın ayrıntısı için ilgili kimlik doğrulama sayfasına bağlantı verilir. Örneklerde üretim adresleri kullanılır. Test ortamı adresleri için Ortamlar sayfasına bakın.

Ne	Adres
API tabanı	`https://app.flextell.ai/api/v1`
Kimlik sunucusu	`https://id.flextell.ai`
Keşif belgesi	`https://id.flextell.ai/.well-known/openid-configuration`

Ön koşullar

Bir Flextell kullanıcı hesabı ve en az bir kliniğe üyelik.
Kullanıcının, uygulamayı oluşturacağı klinikte Create:Client izni. Panelde Bağlantılar → Uygulamalar sayfasını görmek için View:Client izni gerekir.
client_secret değerini güvenle saklayabileceğiniz bir sunucu. Flextell’de oluşturulan uygulamalar her zaman gizli (confidential) istemcidir; yetkilendirme kodunu token ile sunucunuzda değiştirmeniz gerekir.
curl ve openssl komutları (örnekler kabuk komutudur).

Bir uygulama, onu oluşturan kullanıcıya aittir. Klinikteki diğer kullanıcılar uygulamayı listede görmez ve yönetemez. Uygulamayı yetkilendiren her kullanıcı, kendi üyesi olduğu kliniklerde, uygulamanın scope’ları ve kendi izinleri ölçüsünde işlem yapabilir.

Uygulama oluşturma

Uygulama, API’ye erişecek yazılımınızın Flextell’deki kaydıdır. Oluşturma sonunda bir Client ID ve bir Client Secret alırsınız.

Sihirbazı açın

Bağlantılar → Uygulamalar sayfasında Uygulama Oluştur’a tıklayın.

Uygulama bilgilerini girin

Uygulama Bilgileri adımında Uygulama Adı ve en az bir Yönlendirme URI’leri değeri girin (en fazla 20 adres). İsterseniz Çıkış Sonrası Yönlendirme URI’leri de ekleyin. İleri’ye tıklayın.

İzinleri seçin

İzinler adımında uygulamanızın isteyebileceği scope’ları seçin. Bu rehberdeki örnekler için account:read ve customers:read yeterlidir. account:read, sonraki bölümde klinik listesini almak için gereklidir. İleri’ye tıklayın.

Kimlik bilgilerini kaydedin

Kimlik Bilgileri adımında Client ID ve Client Secret değerlerini kopyalayın, ardından Bitir’e tıklayın.

Client Secret yalnızca bir kez gösterilir. Pencereyi kapattıktan sonra göremezsiniz. Kaybederseniz POST /oauth/clients/{id}/secret ile yenisini üretebilirsiniz; eski secret hemen geçersiz olur.

Yönlendirme URI’leri yetkilendirme sırasında birebir eşleşmelidir. Adresler geçerli birer URL olmalıdır; myapp:// gibi özel şemalar kabul edilmez. Uygulamayı API ile de oluşturabilirsiniz. Bu istek, oauth_clients:write scope’u taşıyan bir token ve X-Tenant başlığı gerektirir:

curl -X POST https://app.flextell.ai/api/v1/oauth/clients \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"name":"Örnek Entegrasyon","redirect_uris":["https://example.com/callback"],"scopes":["account:read","customers:read"]}'

Yanıt 201 ile döner ve data.secret alanında secret’ı içerir. Ayrıntılar için Uygulama oluşturma ve OAuth uygulamaları sayfalarına bakın.

Panelin geçerli sürümünde İzinler adımındaki scope listesi yüklenemeyebilir (Yetki listesi yüklenemedi.). Bu durumda sihirbaz bir scope seçmenize izin vermez ve uygulama panelden oluşturulamaz; uygulamayı yukarıdaki API isteğiyle oluşturun. Aynı sorun, mevcut bir uygulamanın Yetkileri Güncelle işleminde de görülür.

Kullanıcıyı yetkilendirme

Flextell, yetkilendirme kodu akışını PKCE ile destekler. Önce rastgele bir code_verifier ve ondan türeyen code_challenge üretin:

CODE_VERIFIER=$(openssl rand -base64 64 | tr -d '\n=+/' | cut -c1-64)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

code_verifier, 43–128 karakterlik ve yalnızca A-Z a-z 0-9 - . _ ~ karakterlerinden oluşan bir metin olmalıdır. code_challenge_method değerini her zaman S256 gönderin; göndermezseniz sunucu plain varsayar. Kullanıcının tarayıcısını şu adrese yönlendirin:

https://id.flextell.ai/oauth/authorize?response_type=code&client_id=<client_id>&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=openid%20profile%20email%20account%3Aread%20customers%3Aread&state=<state>&nonce=<nonce>&code_challenge=<code_challenge>&code_challenge_method=S256

Parametre	Açıklama
`client_id`	Uygulamanın `Client ID` değeri.
`redirect_uri`	Kayıtlı adreslerden biri; birebir aynı olmalı.
`scope`	Boşlukla ayrılmış scope listesi. Uygulamada tanımlı olmayan bir scope istenirse yetkilendirme `invalid_scope` hatasıyla reddedilir.
`state`	Sizin ürettiğiniz rastgele değer; dönüşte aynen geri gelir.
`nonce`	İsteğe bağlı. `openid` scope’u ile `id_token` istiyorsanız kullanın.

Kullanıcı oturum açar (Giriş Yap), iki adımlı doğrulaması varsa kodunu girer ve onay ekranında Erişim İzni Ver’e tıklar. Sonra tarayıcı şu adrese döner:

https://example.com/callback?code=<code>&state=<state>

Kullanıcı reddederse adrese error=access_denied eklenir. state değerini kontrol edin, ardından kodu hemen kullanın: kod 10 dakika geçerlidir ve yalnızca bir kez çalışır. Akışın tamamı için Yetkilendirme kodu ve PKCE sayfasına bakın.

Token alma

Kodu sunucunuzdan token ile değiştirin:

curl -X POST https://id.flextell.ai/oauth/token \
  -H "Accept: application/json" \
  -d grant_type=authorization_code \
  -d client_id=<client_id> -d client_secret=<client_secret> \
  -d redirect_uri=https://example.com/callback \
  -d code=<code> -d code_verifier=<code_verifier>

Başarılı yanıt:

{
  "scope": "openid profile email account:read customers:read",
  "id_token": "…",
  "token_type": "Bearer",
  "expires_in": 300,
  "access_token": "…",
  "refresh_token": "…"
}

client_id ve client_secret alanları yerine HTTP Basic kimlik doğrulaması da kullanabilirsiniz (-u "<client_id>:<client_secret>"). Accept: application/json başlığını gönderin; hatalar JSON döner.

access_token 5 dakika geçerlidir (expires_in: 300). refresh_token 7 gün geçerlidir ve her kullanımda yenilenir. Yenileme isteği yeni bir access_token ile yeni bir refresh_token döndürür; eski refresh_token geçersiz olur, bu yüzden yenisini hemen saklayın.

Süresi dolan token’ı yenilemek için:

curl -X POST https://id.flextell.ai/oauth/token \
  -H "Accept: application/json" \
  -d grant_type=refresh_token -d refresh_token=<refresh_token> \
  -d client_id=<client_id> -d client_secret=<client_secret>

Yenilemede scope yalnızca daraltılabilir; yeni bir scope için kullanıcıyı yeniden yetkilendirmeniz gerekir. Ayrıntılar: Token’lar ve Scope’lar.

Klinik seçme

Flextell’de bir kullanıcı birden fazla kliniğe üye olabilir. Klinik verisi kullanan her istekte, hangi klinikte çalıştığınızı X-Tenant başlığıyla bildirirsiniz. Başlığın değeri kliniğin sayısal id değeridir (slug değil). Kullanıcının kliniklerini account:read scope’u ile listeleyin; bu istekte X-Tenant gerekmez:

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

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

Listeden çalışacağınız kliniğin id değerini alın. Klinik değiştirmek için yeni token almanız gerekmez; aynı token kullanıcının tüm kliniklerinde geçerlidir, yalnızca X-Tenant değerini değiştirirsiniz. Ayrıntılar: Klinikler ve X-Tenant.

İlk istek

Seçtiğiniz klinikte hastaları listeleyin:

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

const response = await fetch("https://app.flextell.ai/api/v1/customers?per_page=15", {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "X-Tenant": "12",
    Accept: "application/json",
    "Accept-Language": "tr",
  },
});
const body = await response.json();

Bu istek iki şey gerektirir: token’da customers:read scope’u ve kullanıcının seçili klinikte View:Customer izni. Liste sayfalıdır; yanıt data, links ve meta alanlarını içerir. Hangi kayıtları göreceğiniz kullanıcının izinlerine bağlıdır; bkz. İzinler ve görünürlük. Sayfalama için Sayfalama, alan ayrıntıları için Hastalar sayfasına bakın.

200 yanıtı ve data içinde hasta kayıtları aldıysanız kurulum tamamdır.

Sık karşılaşılan hatalar

Yanıt	Ne zaman	Ne yapın
`401 UNAUTHENTICATED`	Token süresi dolmuş veya iptal edilmiş.	`refresh_token` ile yenileyin.
`403 FORBIDDEN`, `Invalid scope(s) provided.`	Token’da isteğin gerektirdiği scope yok.	Kullanıcıyı gereken scope ile yeniden yetkilendirin.
`403 FORBIDDEN`, `Bu işlem için yetkiniz yok.`	Kullanıcının o klinikte gereken izni yok.	Klinik yöneticisinden izin isteyin.
`400 TENANT_HEADER_REQUIRED`	`X-Tenant` başlığı yok.	Başlığı ekleyin.
`404 TENANT_NOT_FOUND`	Klinik yok veya kullanıcı üye değil.	`/account/tenants` listesindeki `id` değerini kullanın.
`429 TOO_MANY_REQUESTS`	Dakikada 300 istek sınırı aşıldı.	`Retry-After` süresi kadar bekleyin.

Tüm hata kodları için Hata kodları ve Kimlik doğrulama hataları sayfalarına bakın.

Sonraki adımlar

Kimlik doğrulama

Akışın tamamı, token ömürleri ve çıkış.

Başlıklar

Her istekte kullanacağınız başlıklar.

Sayfalama

Liste yanıtlarında sayfa gezme.

Oran sınırları

İstek sınırları ve 429 yanıtı.

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

Hızlı başlangıç

Ön koşullar

Uygulama oluşturma

Kullanıcıyı yetkilendirme

Token alma

Klinik seçme

İlk istek

Sık karşılaşılan hatalar

Sonraki adımlar

Kimlik doğrulama

Başlıklar

Sayfalama

Oran sınırları

​Ön koşullar

​Uygulama oluşturma

​Kullanıcıyı yetkilendirme

​Token alma

​Klinik seçme

​İlk istek

​Sık karşılaşılan hatalar

​Sonraki adımlar

Kimlik doğrulama

Başlıklar

Sayfalama

Oran sınırları

Ön koşullar

Uygulama oluşturma

Kullanıcıyı yetkilendirme

Token alma

Klinik seçme

İlk istek

Sık karşılaşılan hatalar

Sonraki adımlar