> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flextell API'ye giriş

> Flextell API'nin ne sunduğunu, erişim modelini ve bu belgelerin nasıl okunacağını özetler.

Flextell API, panelde ve mobil uygulamada yaptığınız işlemlerin çoğunu kendi yazılımınızdan yapmanızı sağlar. Bu sayfa entegrasyon geliştiricileri içindir. API'nin kapsamını, istek akışını ve belgeler arasında nasıl gezineceğinizi özetler.

## API ile neler yapılabilir

API, bir kliniğin günlük çalışmasındaki temel kaynakları REST uç noktaları olarak sunar. Tüm yollar `/api/v1` önekiyle başlar. `v2` yoktur, değişiklikler `v1` içinde yayımlanır.

<CardGroup cols={2}>
  <Card title="Hastalar ve Lead'ler" icon="users" href="/api/kaynaklar/hastalar">
    Hasta ve Lead kayıtlarını oluşturun, güncelleyin, not ve görev ekleyin, Pipeline aşamalarında ilerletin.
  </Card>

  <Card title="Randevular" icon="calendar" href="/api/kaynaklar/randevular">
    Randevu oluşturun, uygun saatleri sorgulayın, hatırlatmaları ve tatilleri yönetin.
  </Card>

  <Card title="Sohbetler ve mesajlar" icon="message-circle" href="/api/kaynaklar/sohbetler">
    Kanallardan gelen Sohbetleri okuyun, mesaj ve medya gönderin, AI asistanı denetleyin.
  </Card>

  <Card title="Satış, tahsilat ve fatura" icon="receipt" href="/api/kaynaklar/satislar">
    Satış kaydedin, tahsilat alın, fatura ve stok verilerine erişin.
  </Card>
</CardGroup>

Bunların dışında dosya yükleme, bildirimler, ayarlar, istatistikler ve Geri Dönüşüm Kutusu gibi kaynaklar da vardır. Tam liste için sol menüdeki **Kaynak Rehberleri** grubuna bakın.

API üç ek yol daha sunar:

* **Gerçek zamanlı olaylar:** Yeni mesaj, Sohbet ve Hasta değişikliklerini Pusher protokolüyle dinlersiniz. Bkz. [Gerçek zamanlı olaylar](/api/gercek-zamanli/genel-bakis).
* **Webhook'lar:** Dış sistemlerden Flextell'e Lead gönderirsiniz. Bkz. [Gelen Lead webhook'u](/api/webhooklar/gelen-lead-webhooku).
* **Kanal entegrasyonları:** WhatsApp, Telegram ve e-Fatura bağlantılarını yönetirsiniz. Bkz. [Entegrasyonlara genel bakış](/api/entegrasyonlar/genel-bakis).

## Erişim modeli

Her istek aynı üç adımdan geçer: kimliğiniz doğrulanır, çalışacağınız klinik seçilir, sonra yetkiniz denetlenir.

```mermaid theme={null}
flowchart LR
  A["Bearer token"] --> B["X-Tenant: klinik"]
  B --> C["scope kontrolü"]
  C --> D["Kullanıcının izinleri"]
  D --> E["Yanıt"]
```

| Adım | Ne yapar | Nasıl sağlarsınız |
| - | - | - |
| Kimlik doğrulama | OAuth 2.0 ve OpenID Connect kullanır. Kimlik sunucusu `https://id.flextell.ai` adresindedir. | `Authorization: Bearer <access_token>` başlığı |
| Klinik seçimi | Aynı kullanıcı birden fazla kliniğe üye olabilir. API hangi klinikte çalışacağınızı sizden bekler. | `X-Tenant: <tenant_id>` başlığı |
| scope | Uygulamanızın hangi kaynaklara erişebileceğini belirler. | Uygulamayı oluştururken seçtiğiniz scope listesi |
| İzin | İşlemi yapan kullanıcının o klinikteki rol izinlerini uygular. | Kullanıcının rolü |

Etkin yetki, token scope'ları ile kullanıcının o klinikteki izinlerinin kesişimidir. Uygulamanız kullanıcının yapamadığı bir işi yapamaz. Aynı biçimde kullanıcı izin verse bile token'da gerekli scope yoksa istek `403` döner.

<Info>
  Kullanıcının üye olmadığı ya da var olmayan bir klinik için `404 TENANT_NOT_FOUND` döner, `403` dönmez. Başlık hiç yoksa `400 TENANT_HEADER_REQUIRED` alırsınız. Kliniklerin listesi için `GET /account/tenants` çağrısını kullanın. Ayrıntı için [Klinikler ve X-Tenant](/api/klinikler-ve-x-tenant) sayfasına bakın.
</Info>

### Uygulama kaydı ve token'lar

* Uygulamanızı panelde **Bağlantılar → Uygulamalar → Uygulama Oluştur** yoluyla ya da `/oauth/clients` uç noktalarıyla kaydedersiniz. Uygulama bir `Client ID` ve gizli bir `Client Secret` alır. Secret yalnızca bir kez gösterilir.
* Kullanıcıdan yetki almak için yetkilendirme kodu akışını ve PKCE'yi kullanırsınız. Kullanıcı Flextell giriş ekranında oturum açar ve uygulamanıza izin verir.
* Access token 5 dakika geçerlidir. Refresh token 7 gün geçerlidir ve her kullanımda yenisiyle değişir. Süresi dolan token ile yapılan istek `401 UNAUTHENTICATED` döner.

Akışın tamamı için [Kimlik doğrulamaya genel bakış](/api/kimlik-dogrulama/genel-bakis) sayfasından başlayın.

### Görünürlük, abonelik ve kurulum

* İzin vermediğiniz bir kayıt bulunamadıysa API çoğunlukla `404` döner. Kaydın var olduğu sızdırılmaz. `ViewAllConversations` izni olmayan kullanıcılar, örneğin varsayılan satış temsilcisi rolü, yalnızca kendilerine atanmış Lead'lerin Sohbetlerini görür. Ayrıntı için [İzinler ve görünürlük](/api/izinler-ve-gorunurluk) sayfasına bakın.
* Kliniğin aboneliği bittiyse `402`, zorunlu kurulum adımları açıksa `428` döner. Bkz. [Erişim kilitleri](/api/istekler/erisim-kilitleri).
* İstekler kullanıcı ve uygulama başına dakikada 300 ile sınırlıdır. Bkz. [Oran sınırları](/api/istekler/oran-sinirlari).

## Temel kavramlar

<AccordionGroup>
  <Accordion title="Uygulama (OAuth istemcisi)">
    Entegrasyonunuzun Flextell'deki kimliğidir. Bir `Client ID`, bir `Client Secret`, yönlendirme URI'leri ve scope listesi içerir. Her ortam için ayrı uygulama oluşturun.
  </Accordion>

  <Accordion title="Klinik (tenant)">
    Verinin ait olduğu kuruluştur. API'de `tenant`, istek başlığında `X-Tenant` adıyla geçer. Hastalar, randevular ve diğer tüm klinik kayıtları yalnızca seçilen klinikte görünür.
  </Accordion>

  <Accordion title="scope">
    Token'ın erişebileceği kaynak ve işlemdir. Biçimi `kaynak:okuma-ya-da-yazma` şeklindedir, örneğin `customers:read`. Bir endpoint'in hangi scope'u istediğini ilgili kaynak sayfasında bulursunuz. Bkz. [scope'lar](/api/kimlik-dogrulama/scopelar).
  </Accordion>

  <Accordion title="İzin">
    Kullanıcının rolünden gelen yetkidir, örneğin `View:Customer`. scope uygulamayı, izin kullanıcıyı sınırlar. İkisi birlikte gerekir.
  </Accordion>

  <Accordion title="Yanıt zarfı">
    Başarılı yanıtlar `{ "success": true, "data": ... }` biçimindedir. Hatalar `{ "success": false, "error_code": "...", "message": "..." }` döner. Doğrulama hatalarında `errors` alanı alan alan ayrıntı verir. Bkz. [Yanıt yapısı](/api/istekler/yanit-yapisi).
  </Accordion>
</AccordionGroup>

Tek bir isteğin nasıl göründüğü:

```bash theme={null}
curl "https://app.flextell.ai/api/v1/customers?per_page=15" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Accept: application/json" \
  -H "Accept-Language: tr"
```

Bu çağrı `customers:read` scope'unu ve klinikte `View:Customer` iznini gerektirir. `Accept-Language` isteğe bağlıdır ve `tr` ya da `en` alır. Başka bir değer gönderirseniz yanıt Türkçe döner.

## Belgeleri okuma

Bu bölümdeki sayfalar sırayla okunacak şekilde dizilmiştir.

| Menü grubu | Ne bulursunuz |
| - | - |
| **Başlarken** | Bu giriş, [hızlı başlangıç](/api/hizli-baslangic) ve [ortamlar](/api/ortamlar) |
| **Kimlik Doğrulama** | Uygulama oluşturma, yetkilendirme kodu ve PKCE, token'lar, scope'lar, OpenID Connect, hatalar |
| **Çok Kiracılılık** | Klinik seçimi ve izinler |
| **İstek Kuralları** | Başlıklar, sayfalama, filtreleme ve sıralama, veri biçimleri, hata kodları, oran sınırları, idempotency, dosya yükleme |
| **Kaynak Rehberleri** | Her kaynak için uç nokta özeti, nesne alanları, iş kuralları, hata kodları, izinler ve örnekler |
| **Gerçek Zamanlı**, **Webhook'lar ve Açık Uçlar**, **Entegrasyonlar** | Canlı olaylar, gelen webhook'lar, kanal bağlantıları |
| **Rehberler** | Uçtan uca senaryolar, örneğin [randevu oluşturma](/api/rehberler/randevu-olusturma) ve [Lead akışı](/api/rehberler/lead-akisi) |

Önerilen sıra:

<Steps>
  <Step title="Ortamı seçin">
    [Ortamlar](/api/ortamlar) sayfasından üretim ve geliştirme adreslerini alın. Ortamlar arasında secret paylaşmayın.
  </Step>

  <Step title="İlk isteği yapın">
    [Hızlı başlangıç](/api/hizli-baslangic) uygulama oluşturmadan ilk klinik çağrısına kadar götürür.
  </Step>

  <Step title="Ortak kuralları okuyun">
    [Başlıklar](/api/istekler/basliklar), [sayfalama](/api/istekler/sayfalama) ve [hatalar](/api/istekler/hatalar) tüm kaynaklarda aynıdır. Kaynak sayfaları bunları tekrar etmez, bağlantı verir.
  </Step>

  <Step title="Kaynağınıza geçin">
    İhtiyacınız olan kaynağın sayfasını açın.
  </Step>
</Steps>

Kaynak sayfalarındaki tablolar ve örnekler panelde göreceğiniz Türkçe adları kullanır. API alan adları, scope'lar ve hata kodları ise olduğu gibi yazılır. Bazı terimler API'de İngilizce kalır, örneğin `conversation`. Terimlerin karşılıkları için [Sözlük](/api/sozluk) sayfasına bakın.

## API referansı

**API Referansı** sekmesi OpenAPI belirtiminden otomatik üretilir. Her endpoint için parametreleri, istek gövdesini ve yanıt şemasını verir, istekleri deneyebilirsiniz. Elle yazılmış **API** sekmesi ise kavramları, iş kurallarını ve senaryoları anlatır. Bir endpoint'in ne yaptığını anlamak için önce **API** sekmesindeki kaynak sayfasını, alan ayrıntısı için **API Referansı** sekmesini kullanın.

<Note>
  OpenAPI belirtimindeki OAuth bölümü yalnızca `*` scope'unu gösterir. Gerçek scope listesi için [scope'lar](/api/kimlik-dogrulama/scopelar) sayfasını kullanın.
</Note>

Sorunuz çözülmediyse [Destek](/api/destek) sayfasına bakın.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.