Klinik bilgileri ve genel veriler

Bu sayfa dört grup endpoint’i kapsar: klinik profili (/v1/tenant), yeni kliniklerin kurulum sihirbazı (/v1/setup-wizard), hasta ve Lead’lerde genel arama (/v1/general/global-search) ve tüm kliniklerde ortak olan arama listeleri (/v1/general/*). Klinik profili ve arama X-Tenant ister. Ortak listeler istemez.

Endpoint özeti

Tüm istekler Authorization: Bearer <access_token> başlığı taşır. Klinik bağlamı için Klinikler ve X-Tenant, scope’lar için Scope’lar sayfasına bakın.

Metot	Endpoint	Açıklama	Scope
GET	`/v1/tenant`	Klinik profilini getirir.	`tenant:read`
PUT	`/v1/tenant`	Telefon, adres, konum, hizmetler, bilgi bankası ve çalışma saatlerini günceller.	`tenant:write`
GET	`/v1/setup-wizard`	Kurulum sihirbazı ilerlemesini getirir.	`setup_wizard:read`
PUT	`/v1/setup-wizard/clinic-info`	Klinik bilgilerini kaydeder ve adımı tamamlar.	`setup_wizard:write`
PUT	`/v1/setup-wizard/work-mode`	Çalışma modunu ve varsayılan form şablonunu kaydeder.	`setup_wizard:write`
POST	`/v1/setup-wizard/doctor/self`	Oturum açmış kullanıcıya `doctor` rolünü ekler.	`setup_wizard:write`
POST	`/v1/setup-wizard/steps/{step}/complete`	Bir adımı doğrulayıp tamamlar.	`setup_wizard:write`
POST	`/v1/setup-wizard/steps/{step}/skip`	İsteğe bağlı bir adımı atlar.	`setup_wizard:write`
POST	`/v1/setup-wizard/complete`	Kurulumu bitirir.	`setup_wizard:write`
GET	`/v1/general/global-search`	Hasta ve Lead’lerde arar.	`customers:read` veya `leads:read`
GET	`/v1/general/countries`, `cities`, `districts`, `currencies`, `exchange-rates`, `unit-codes`, `withholding-codes`, `product-types`	Ortak listeler.	Scope gerekmez

Yetki

İşlem	İzin	Panelde görünen ad
`GET /v1/tenant`	`View:TenantInfo`	Klinik Bilgileri → Görüntüle
`PUT /v1/tenant`	`Update:TenantInfo`	Klinik Bilgileri → Güncelle
Tüm `/v1/setup-wizard` endpoint’leri (GET dahil)	`Manage:SetupWizard`	Kurulum → Yönet
Genel arama	`View:Customer` ve/veya `View:Lead`	Hasta ve Lead görüntüleme
Ortak listeler	Yok	Geçerli bir token yeterlidir

İzin ve scope eksikliği 403 FORBIDDEN döndürür. Yeni kliniklerde Manage:SetupWizard izni yalnızca super_admin rolündedir. Diğer roller için rol düzenleyicisinden ekleyin. İzinlerin nasıl değerlendirildiği için İzinler ve görünürlük sayfasına bakın.

Klinik profili

GET /v1/tenant yanıtı { "success": true, "data": { ... } } zarfındadır.

Alan	Tür	Açıklama
`id`	sayı	Klinik kimliği. `X-Tenant` başlığına yazdığınız değerdir.
`name`	metin	Klinik adı. Bu endpoint ile değiştirilemez.
`avatar_url`	metin veya `null`	Klinik logosu.
`phone_number`	metin	Hastaların gördüğü telefon numarası. Yanıtta başında `+` ile gelir.
`address`	metin	Açık adres.
`location`	nesne	`{ "latitude": 41.0082, "longitude": 28.9784 }` biçiminde harita konumu.
`services`	metin dizisi	Klinik olanakları, örneğin `Otopark`, `Wi-Fi`.
`knowledge_base`	metin	AI asistanın kullandığı serbest metin.
`work_hours`	dizi (7 öğe)	Haftalık çalışma saatleri. Aşağıya bakın.
`city_id`, `district_id`, `country_id`	sayı	Adres kimlikleri.
`city`, `district`, `country`	nesne	Her biri `{ "id", "name" }`.
`created_at`, `updated_at`	tarih	Klinik saat diliminde, ofsetli.

PUT /v1/tenant kısmi güncellemedir: yalnızca gönderdiğiniz alanlar yazılır.

Alan	Kural
`phone_number`	En fazla 32 karakter.
`address`	Gönderilirse boş olamaz, en fazla 500 karakter.
`services`	Her öğe en fazla 120 karakter. Boş metinler ve metin olmayan öğeler atılır: `["Otopark", "Lab", ""]` kaydı `["Otopark", "Lab"]` olur.
`knowledge_base`	En fazla 5000 karakter. `null` gönderirseniz boş metin olarak kaydedilir.
`location`	`latitude` −90 ile 90, `longitude` −180 ile 180 arasında olmalıdır. Boş metin `null` sayılır.
`work_hours`	Tam olarak 7 öğe. Aşağıya bakın.

Klinik adı, logo, şehir, ilçe, ülke ve vergi bilgileri bu endpoint ile değiştirilemez. Klinik adını yalnızca kurulum sırasında PUT /v1/setup-wizard/clinic-info ile kaydedebilirsiniz.

Çalışma saatleri

work_hours haftanın yedi gününü içerir. Saatleri klinik saat diliminde gönderir ve okursunuz. Sistem bunları UTC olarak saklar, siz dönüşümle uğraşmazsınız.

Alan	Tür	Kural
`day`	metin	`monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
`enabled`	boolean	Gün açıksa `true`.
`open`	`H:i`	`enabled` olduğunda zorunlu. Kapalı günlerde yanıtta `null` gelir.
`close`	`H:i`	`enabled` olduğunda zorunlu ve `open` değerinden sonra olmalı. Kapalı günlerde `null` gelir.
`day_label`	metin	Yalnızca yanıtta gelir (`Pazartesi`, `Salı` …). Gönderirseniz atılır.

Çalışma saatlerini kaydettiğinizde klinik önbelleği temizlenir. AI asistan ve randevu uygunluğu yeni saatleri hemen kullanır.

curl -X PUT https://app.flextell.ai/api/v1/tenant \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+90 5xx xxx xx xx",
    "services": ["Otopark", "Wi-Fi"],
    "work_hours": [
      { "day": "monday", "enabled": true, "open": "09:00", "close": "18:00" },
      { "day": "tuesday", "enabled": true, "open": "09:00", "close": "18:00" },
      { "day": "wednesday", "enabled": true, "open": "09:00", "close": "18:00" },
      { "day": "thursday", "enabled": true, "open": "09:00", "close": "18:00" },
      { "day": "friday", "enabled": true, "open": "09:00", "close": "18:00" },
      { "day": "saturday", "enabled": true, "open": "10:00", "close": "14:00" },
      { "day": "sunday", "enabled": false }
    ]
  }'

Panelde aynı bilgiler için Klinik bilgileri sayfasına bakın.

Kurulum sihirbazı

Yeni bir klinik, zorunlu kurulum adımlarını bitirene kadar kurulum kilidi altındadır. Bu sürede kilit muafiyeti olmayan her klinik endpoint’i 428 SETUP_REQUIRED döndürür. Gövdede data.next_step sıradaki adımı verir. Kilidin genel anlatımı için Erişim kilitleri sayfasına bakın. Kilit altında şu endpoint grupları çalışmaya devam eder: setup-wizard, billing, tenant, account, notifications, general, settings, files, uploads, permissions, roles, users, invitations, occupations, channels, integrations, integration-connections, doctors, assistants, rooms, treatments, treatment-groups, form-templates, products, catalog-products, product-brands, product-categories, warehouses, invoices/accounts, invoices/series, bank-accounts, payment-methods, tickets, panel-tickets. Randevu, hasta, Lead, sohbet, satış, fatura ve etiket endpoint’leri kurulum bitene kadar 428 verir.

Faturalama kilidi kurulum kilidinden önce değerlendirilir. Süresi dolmuş abonelikte 402 SUBSCRIPTION_REQUIRED alırsınız, 428 almazsınız.

Adımlar

Adım (`step`)	Grup	Hazır sayılma koşulu
`clinic_info`	Zorunlu	Klinik adı, adres, saat dilimi, para birimi ve çalışma saatleri dolu.
`communication_channels`	Zorunlu	Aktif bir WhatsApp kanalı (bağlantı durumu önemli değil) veya bağlı (`open`) bir Telegram kanalı var. Instagram ve web sitesi kanalları sayılmaz.
`work_mode`	Zorunlu	Mod 1 veya 2 seçili. Mod 2’de varsayılan form şablonu aktif.
`doctor_setup`	Mod 1	`doctor` rolünde en az bir aktif kullanıcı var.
`treatment_doctor_assign`	Mod 1	En az bir aktif tedavi var ve her aktif tedavi en az bir aktif doktora bağlı.
`treatment_groups`	Mod 2	En az bir aktif tedavi grubu var.
`room_assistant`	İsteğe bağlı	En az bir oda veya `assistant` rolünde aktif bir üye var.
`invoice_integration`	İsteğe bağlı	Bir fatura hesabı ve aktif bir fatura entegrasyonu var.
`bank_accounts`	İsteğe bağlı	En az bir aktif hesap var. Klinik kurulurken Ana Hesap oluşturulduğu için genelde baştan hazırdır.

Çalışma modu 1 randevu akışını, mod 2 ön kayıt formu akışını seçer. Sihirbaz yalnızca ilerlemeyi tutar. Kanal, doktor, tedavi, oda gibi kayıtları normal endpoint’lerle siz oluşturursunuz, sonra adımı complete ile onaylarsınız.

Yanıt

GET /v1/setup-wizard şu alanları döndürür.

Alan	Açıklama
`tenant_id`, `work_mode`	Klinik kimliği ve seçilen mod (seçilmediyse `null`).
`setup_required`	Zorunlu bir adım hâlâ açıksa `true`.
`is_completed`	`POST /v1/setup-wizard/complete` başarıyla çalıştıysa `true`.
`next_step`	Tamamlanmamış ilk adım. Zorunlu adımlar bittiğinde isteğe bağlı bir adım olabilir.
`completed_steps`	Tamamlanan veya atlanan adımlar. İkisi ayırt edilemez.
`steps[]`	Her adım için `id`, `label`, `optional`, `completed`, `ready`, `missing[]`.
`blockers[]`	Zorunlu adımlar için `{ step, missing[] }`.
`clinic_info`	`clinic_name`, `address`, `timezone`, `currency`, `work_hours_start`, `work_hours_end`.
`work_mode_settings`	`intake_enabled` ve `default_template_id`.
`channels[]`	WhatsApp ve Telegram kanalları için `id`, `type`, `active`, `connected`.

completed ile ready birbirinden bağımsızdır. Kayıtlar var ama adım onaylanmamış olabilir. Tersi de olur: adımı onayladıktan sonra kaydı silmiş olabilirsiniz. missing[] içindeki değerler eksik alanın veya kaydın makine adıdır, örneğin active_channel, active_doctor, active_treatment_group.

Klinik bilgileri

PUT /v1/setup-wizard/clinic-info gövdesi:

Alan	Zorunlu	Kural
`clinic_name`	Evet	En fazla 255 karakter. Klinik adını değiştirir.
`address`	Evet	En fazla 500 karakter.
`timezone`	Evet	Geçerli saat dilimi adı, örneğin `Europe/Istanbul`.
`currency`	Evet	`/v1/general/currencies` listesindeki aktif bir para birimi kodu, örneğin `TRY`.
`work_hours_start`	Evet	`H:i`, klinik saat diliminde.
`work_hours_end`	Evet	`H:i`, `work_hours_start` değerinden sonra. Gece yarısını aşan aralık kabul edilmez.

Bu endpoint haftalık çalışma saatlerini sıfırlar: Pazartesi–Cuma açık, Cumartesi ve Pazar kapalı olur ve hafta içi günlere gönderdiğiniz saatler yazılır. Daha önce gün bazında girdiğiniz farklı saatler silinir. Kurulumdan sonra çalışma saatlerini PUT /v1/tenant ile ayarlayın.

Çalışma modu

PUT /v1/setup-wizard/work-mode gövdesi work_mode (zorunlu, 1 veya 2) ve default_template_id alanlarını alır. default_template_id yalnızca mod 2’de kullanılır ve bu kliniğe ait aktif bir Form Şablonu olmalıdır; başka kliniğin şablonu 422 verir. Mod 2’de şablon göndermezseniz sistem Varsayılan Ön Kayıt Formu şablonunu oluşturur veya yeniden kullanır. Mod 1’de gönderdiğiniz şablon yok sayılır. Modu sonradan değiştirebilirsiniz. Yeni modun tamamlanmamış adımı varsa setup_required yeniden true olur.

Adım ve kurulum tamamlama

POST /v1/setup-wizard/steps/{step}/complete adımın kayıtlarını doğrular ve adımı tamamlar. Kayıtlar eksikse 422 SETUP_STEP_INCOMPLETE döner ve data içinde step ile missing[] bulunur.
POST /v1/setup-wizard/steps/{step}/skip yalnızca isteğe bağlı adımlar (room_assistant, invoice_integration, bank_accounts) içindir. Kayıtları kontrol etmez.
POST /v1/setup-wizard/doctor/self oturum açmış kullanıcıya klinikteki doctor rolünü ek olarak verir ve ek kullanıcı hakkı harcamaz. Tek kullanıcılı kliniklerde mod 1 kurulumunu bitirmenin yoludur. Adımı tamamlamaz; ardından steps/doctor_setup/complete çağırın.
POST /v1/setup-wizard/complete zorunlu adımları güncel kayıtlara göre yeniden doğrular. Daha önce tamamladığınız bir adımın kaydını silmişseniz 422 SETUP_INCOMPLETE döner ve data.blockers[] eksikleri listeler. Başarılı olursa is_completed ve setup_required değerleri true ve false olur.

Kurulum bittikten sonra bir doktoru veya kanalı silmek kilidi geri getirmez.

curl https://app.flextell.ai/api/v1/setup-wizard \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

Genel arama

GET /v1/general/global-search tek istekte hasta ve Lead arar. search zorunludur (1–255 karakter).

curl "https://app.flextell.ai/api/v1/general/global-search?search=Ayşe" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

{
  "success": true,
  "data": {
    "customers": [
      { "id": 123, "full_name": "Ayşe Yılmaz", "phone_number": "+90 5xx xxx xx xx", "email": "ayse@example.com" }
    ],
    "leads": []
  }
}

Kural	Açıklama
Sınır	En fazla 10 hasta ve 10 Lead döner. Sayfalama yoktur.
Scope ve izin	`customers` bölümü `customers:read` scope’u ve `View:Customer` izni, `leads` bölümü `leads:read` scope’u ve `View:Lead` izni ister. İkisinden birine sahipseniz istek çalışır. Sahip olmadığınız bölüm boş dizi (`[]`) olarak döner. İkisine de sahip değilseniz `403 FORBIDDEN` alırsınız.
Tek taraf	Bir kişi yalnızca bir listede görünür. Lead aşamasındaki kişiler `leads`, hastaya dönüşenler `customers` içindedir.
Görünürlük	`ViewAllCustomers:Customer` veya `ViewAllLeads:Lead` izni olmayan kullanıcı yalnızca kendi kayıtlarını görür.
Eşleşme	Büyük/küçük harf ve Türkçe karakter ayrımı yapılmaz. Girdiğiniz her kelime hastada `first_name`, `last_name`, `email` veya `identity_number` alanlarından birinde, Lead’de `first_name`, `last_name` veya `email` alanlarından birinde geçmelidir. Telefon numarası, rakamlar herhangi bir biçimde yazılsa da eşleşir.
Asgari girdi	En az 2 karakterlik bir kelime veya en az 3 haneli bir rakam dizisi gerekir. Tek karakterlik arama boş döner.

Ortak listeler ve döviz kurları

/v1/general/* listeleri tüm kliniklerde aynıdır. X-Tenant ve scope gerekmez; geçerli bir bearer token yeterlidir. Bu yüzden klinik seçilmeden önce, örneğin kayıt ve adres formlarında kullanabilirsiniz. Tarihler bu isteklerde UTC döner.

Endpoint	Ek filtre	Varsayılan sıra	Önemli alanlar
`/v1/general/countries`	—	`name` artan	`id`, `name`, `iso2`, `iso3`, `numeric_code`, `phone_code`, `emoji`, `is_active`
`/v1/general/cities`	`country_id`	`name` artan	`id`, `country_id`, `name`, `code`, `is_active`
`/v1/general/districts`	`city_id`, `country_id`	`name` artan	`id`, `city_id`, `country_id`, `name`, `is_active`
`/v1/general/currencies`	—	`code` artan	`id`, `name`, `code`, `symbol`, `locale`, `is_active`
`/v1/general/exchange-rates`	—	`rate_date` azalan, sonra `currency_code`	Aşağıya bakın
`/v1/general/unit-codes`	`sort_by`: `code`, `name`	`code` artan	`id`, `name`, `code`, `is_active`
`/v1/general/withholding-codes`	—	`code` artan	`id`, `code`, `percent`, `description`, `is_active`
`/v1/general/product-types`	`category` (tam eşleşme), `sort_by`: `name`, `category`	Önce `category`, sonra `name`	`id`, `name`, `category`, `is_active`

Ortak parametreler:

Parametre	Açıklama
`search`	En fazla 255 karakter. Kelime başı eşleşmesi yapar, tüm kelimeler eşleşmelidir ve sonuçlar ilgiye göre sıralanır.
`per_page`	1–100, varsayılan 15.
`page`	Sayfa numarası.
`sort_order`	`asc` veya `desc`.
`is_active`	Boolean. `exchange-rates` bu parametreyi yok sayar.

Yanıt sayfalı listedir (data, links, meta); success anahtarı yoktur. Genel kurallar için Sayfalama ve Filtreleme ve sıralama sayfalarına bakın. Ülke ve para birimi adları Türkçedir.

Döviz kurları

exchange-rates kayıtları Türkiye Cumhuriyet Merkez Bankası (TCMB) günlük kurlarından gelir ve iş günlerinde güncellenir. Her para birimi için günde bir kayıt vardır; en yeni tarih başta gelir.

Alan	Açıklama
`currency_code`, `currency_name`, `currency_name_tr`	Para birimi kodu ve adları. `search` bu üç alanda arar.
`unit`	Kurun kaç birim için verildiği.
`forex_buying`, `forex_selling`	Döviz alış ve satış kuru (4 ondalık).
`banknote_buying`, `banknote_selling`	Efektif alış ve satış kuru (4 ondalık).
`rate_date`	Kurun tarihi. Ortak listelerde tarihler UTC döndüğü için ISO 8601 biçimindedir ve saat kısmı gece yarısıdır, örneğin `2026-10-12T00:00:00.000000Z`. Günü tarih kısmından okuyun.

curl "https://app.flextell.ai/api/v1/general/exchange-rates?search=USD&per_page=1" \
  -H "Authorization: Bearer <access_token>"

Tahsilat ve işlemlerde kullanılan currency_id değerlerini /v1/general/currencies listesinden alın. Finans tarafı için Hesaplar ve işlemler sayfasına bakın.

Hata kodları

Kod	HTTP	Ne zaman
`TENANT_HEADER_REQUIRED`	400	`X-Tenant` olmadan klinik endpoint’i çağrıldı.
`TENANT_NOT_FOUND`	404	Klinik yok veya üyesi değilsiniz.
`FORBIDDEN`	403	Scope veya izin eksik.
`VALIDATION_FAILED`	422	Geçersiz alan, örneğin eksik `search`, 7 öğeden az `work_hours`, `close` değeri `open` değerinden önce.
`SETUP_REQUIRED`	428	Kurulum bitmeden muaf olmayan bir endpoint çağrıldı. `data.next_step` sıradaki adımdır.
`SETUP_STEP_NOT_APPLICABLE`	422	Adım seçili çalışma moduna ait değil veya mod henüz seçilmedi.
`SETUP_STEP_NOT_SKIPPABLE`	422	Zorunlu bir adım atlanmak istendi.
`SETUP_STEP_INCOMPLETE`	422	Adımın gerektirdiği kayıtlar eksik. `data` içinde `step` ve `missing[]` vardır.
`SETUP_INCOMPLETE`	422	Kurulumu bitirirken zorunlu adımlarda eksik var. `data.blockers[]` eksikleri verir.

Bilinmeyen bir {step} değeri 404 döndürür. Tüm hata kodları için Hata kodları sayfasına bakın.

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

Klinik bilgileri ve genel veriler

Endpoint özeti

Yetki

Klinik profili

Çalışma saatleri

Kurulum sihirbazı

Adımlar

Yanıt

Klinik bilgileri

Çalışma modu

Adım ve kurulum tamamlama

Genel arama

Ortak listeler ve döviz kurları

Döviz kurları

Hata kodları

​Endpoint özeti

​Yetki

​Klinik profili

​Çalışma saatleri

​Kurulum sihirbazı

​Adımlar

​Yanıt

​Klinik bilgileri

​Çalışma modu

​Adım ve kurulum tamamlama

​Genel arama

​Ortak listeler ve döviz kurları

​Döviz kurları

​Hata kodları

Endpoint özeti

Yetki

Klinik profili

Çalışma saatleri

Kurulum sihirbazı

Adımlar

Yanıt

Klinik bilgileri

Çalışma modu

Adım ve kurulum tamamlama

Genel arama

Ortak listeler ve döviz kurları

Döviz kurları

Hata kodları