Uygun saatler ve takvim

Randevu oluşturmadan önce bir entegrasyonun üç şeye ihtiyacı vardır: formda seçilecek doktor, tedavi, oda ve asistan listeleri, doktorun seçilen gündeki uygun saatleri ve mevcut doluluk. Bu sayfa bu okuma uç noktalarını anlatır. Randevuyu oluşturma, güncelleme ve iptal etme Randevular sayfasındadır. Adım adım bir akış için Randevu oluşturma rehberine bakın.

Her istekte Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> başlıkları gerekir. Başlık yoksa 400 TENANT_HEADER_REQUIRED döner. Ayrıntı: Klinikler ve X-Tenant.

Endpoint özeti

Taban adres https://app.flextell.ai/api/v1. Bu sayfadaki tüm uç noktalar yalnızca okur ve token’da appointments:read scope’u ister. Scope’lar hakkında: Scope’lar.

Metot	Endpoint	Açıklama	İzin
GET	`/appointments/options/doctors`	Formdaki doktor seçeneklerini listeler	`Create:Appointment` veya `Update:Appointment`
GET	`/appointments/options/doctors/{id}/treatments`	Doktorun yaptığı tedavileri listeler	`Create:Appointment` veya `Update:Appointment`
GET	`/appointments/options/rooms`	Oda seçeneklerini listeler	`Create:Appointment` veya `Update:Appointment`
GET	`/appointments/options/assistants`	Asistan seçeneklerini listeler	`Create:Appointment` veya `Update:Appointment`
GET	`/appointments/options/products`	Seans ürünü seçeneklerini listeler	`Create:Appointment` veya `Update:Appointment`
GET	`/appointments/options/treatments/{id}`	Bir tedaviyi seans şablonuyla döner	`Create:Appointment` veya `Update:Appointment`
GET	`/appointments/available-slots`	Doktorun bir gündeki önerilen saatlerini, mevcut randevularını ve kapalı dönemlerini döner	`Create:Appointment` veya `Update:Appointment`
GET	`/appointments/calendar`	Tarih aralığı için takvim öğelerini döner	`View:Appointment`
GET	`/appointments/summary`	Bugünün randevu sayılarını döner	`View:Appointment` ve tüm randevuları görme izni

Form seçenekleri

/appointments/options/* uç noktaları, randevu formunu dolduran kullanıcının View:Doctor, View:Room, View:Assistant veya View:Product izni olmadan da seçenekleri görmesini sağlar. Randevu oluşturma ya da güncelleme izni yeterlidir. Listeler yalnızca aktif kayıtları içerir. Web paneli v1.8.0 formdaki doktor, oda, asistan, ürün, doktorun tedavileri ve tedavi şablonunu bu uç noktalardan alır. Liste uç noktaları (doctors, rooms, assistants, products) aynı parametreleri alır:

Parametre	Açıklama
`search`	Ada göre arama
`per_page`	En çok 100, varsayılan 15
`page`	Sayfa numarası
`ids[]`	En çok 100 kimlik. Verilen kayıtları, pasif olsalar bile döner; arama ve aktiflik süzgeci uygulanmaz

Sayfalama yanıtı için Sayfalama sayfasına bakın. ids[] bir randevudaki mevcut seçimin adını göstermek için kullanışlıdır: doktor sonradan pasife alınmış olsa bile adı çözülür.

Uç nokta	Yanıtın öğeleri
`doctors`	`{id, name}`. Kliniğin `doctor` rolündeki aktif kullanıcıları; ada, sonra kimliğe göre sıralı
`rooms`	`{id, name}`, aktif odalar
`assistants`	`{id, name}`, aktif asistanlar
`products`	`{id, name, full_name, unit_code{id, name, code}}`, kliniğin ürünleri ve temel birimleri

doctors/{id}/treatments, doktorun yaptığı tedavileri data dizisinde {id, name, invoice_name, group} olarak ve ada göre sıralı döner. Kimlik bir doktora ait değilse 404 (Doktor bulunamadı) döner. treatments/{id} bir tedaviyi seans şablonuyla verir: id, name, invoice_name, group ve sessions[]. Her seans session_order, session_type, offset_days, next_gap_days ve products[] (product_id, name, full_name, min_quantity, unit_code) taşır. Pasif tedaviler de döner. Tedavi bulunamazsa 404 (Tedavi bulunamadı) döner.

Doktoru seçin

GET /appointments/options/doctors ile doktoru bulun.

Tedaviyi seçin

GET /appointments/options/doctors/{id}/treatments yalnızca o doktorun yaptığı tedavileri verir. Randevuyu oluştururken tedavi, seçilen doktora atanmış olmalıdır.

Saati seçin

GET /appointments/available-slots ile doktorun o günkü önerilen saatlerine bakın.

Randevuyu oluşturun

Seçimlerle POST /appointments çağırın. Bkz. Randevular.

Uygun saatler

GET /appointments/available-slots, bir doktorun bir gündeki önerilen başlangıç saatlerini, o günkü randevularını ve kapalı dönemlerini verir.

Parametre	Zorunlu	Açıklama
`date`	Evet	Gün (`YYYY-MM-DD`). Klinik saat diliminde değerlendirilir
`user_id`	Evet	Doktorun kimliği. Kliniğin üyesi olmalıdır; değilse `422` (`Seçilen kullanıcı bu kliniğe ait değil.`)
`duration_minutes`	Evet	Randevu süresi, 5–1440 dakika

curl "https://app.flextell.ai/api/v1/appointments/available-slots?date=2026-10-14&user_id=123&duration_minutes=30" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

{
  "success": true,
  "data": {
    "date": "2026-10-14",
    "timezone": "Europe/Istanbul",
    "suggested_step_minutes": 15,
    "slots": [
      { "start_at": "09:00", "end_at": "09:30" },
      { "start_at": "09:15", "end_at": "09:45" }
    ],
    "appointments": [
      {
        "id": 456,
        "customer_name": "Ayşe Yılmaz",
        "customer_is_masked": false,
        "start_at": "10:00",
        "end_at": "10:30",
        "status": "approved",
        "is_pending_reschedule": false
      }
    ],
    "closed_periods": [
      { "start_at": "00:00", "end_at": "24:00", "reason": "Cumhuriyet Bayramı" }
    ]
  }
}

Örnekteki değerler yalnızca biçimi gösterir. slots ve closed_periods saatleri HH:mm metnidir.

Alan	Açıklama
`suggested_step_minutes`	Önerilerin adımı. Klinik ayarı Önerilen saat adımı (dakika) belirler, varsayılan 15. Bkz. Randevu ayarları
`slots[]`	Önerilen başlangıç saatleri. Öneriler günün açılış saatinden başlar ve adım kadar ilerler. `end_at`, başlangıç artı istenen süredir
`appointments[]`	Doktorun o gün başlayan `pending` ve `approved` randevuları. Hâlâ onay bekleyen toplu taşıma önerilerinin saatleri de `is_pending_reschedule: true` ile gelir
`closed_periods[]`	Randevuyu engelleyen tatil ve kapanışlar. Tam gün kapanış `00:00`–`24:00` olarak gelir; `24:00` günün kapanış işaretidir

Bilmeniz gereken kurallar:

Bir öneri yalnızca kapanıştan sonra bitecekse listeden çıkar. Dolu saatler, kapanışlar ve çakışmalar öneriyi kaldırmaz. Çakışmayı appointments ve closed_periods ile siz uyarı olarak gösterin.
Kapalı bir hafta günü için 200 ve boş diziler döner; hata değildir.
closed_periods, yalnızca kliniğin tatillerde randevuyu kapatma ayarı açıksa dolu gelir. Bkz. Tatiller.
Görme yetkiniz olmayan bir randevunun customer_name değeri null döner. Size atanmamış bir Lead’in adı maskelenir ve customer_is_masked: true gelir.
duration_minutes yanıtta tekrar edilmez.

Manuel randevu oluştururken sunucu bu önerilere uymayı zorunlu tutmaz. Geçmiş tarih, kapalı gün, çalışma saati dışı, tatil ve doktorun başka randevusuyla çakışma POST /appointments isteğini reddettirmez. Bu durumlar istemcide uyarıdır.

Takvim akışı

GET /appointments/calendar, istenen aralıktaki randevuları, tatilleri ve tutulan saatleri tek bir listede verir.

Parametre	Zorunlu	Açıklama
`from`	Evet	Başlangıç günü. Bitişten sonra olamaz; aksi hâlde `422` (`Başlangıç tarihi bitiş tarihinden sonra olamaz.`)
`to`	Evet	Bitiş günü. Aralık uçlar dahil en çok 50 gün olabilir; aksi hâlde `422` (`Tarih aralığı en fazla 50 gün olabilir.`)

from ve to klinik saat diliminde okunur ve tam günlere genişletilir. View:Appointment iznine ek olarak tüm randevuları görme izni varsa klinikteki bütün randevular, yoksa yalnızca kendi randevularınız gelir. Yanıt {from, to, timezone, items[]} biçimindedir. Liste önce tatilleri, sonra randevuları scheduled_at sırasıyla verir. İptal edilmiş ve reddedilmiş olanlar dahil her statüdeki randevu döner; silinmişler dönmez. Bitiş saati, başlangıç artı duration_minutes değeridir. Randevuda süre yoksa kliniğin varsayılan randevu süresi kullanılır. Her öğenin kind ve reason alanı öğenin türünü söyler:

`kind`	`reason`	Anlamı
`appointment`	`appointment`	Normal randevu
`appointment`	`old_slot`	Toplu taşıma bekleyen randevunun mevcut saati
`lock`	`pending_reschedule`	Toplu taşımada önerilen ve süresi geçmemiş, tutulan saat
`lock`	`expired_pending`	Önerinin tutma süresi dolmuş
`holiday`	`holiday`	Tatil veya kapanış

Toplu taşıma bekleyen bir randevu en çok iki öğe üretir: mevcut saati ve önerilen saati. Her biri yalnızca istenen aralığın içindeyse listelenir. Toplu taşıma için bkz. Toplu randevu taşıma. Öğe alanları:

Alan	Açıklama
`start_at`, `end_at`	Klinik saat diliminde ISO 8601
`customer_name`, `customer_is_masked`	Hasta adı. Görme yetkiniz olmayan Lead’lerin adı maskelenir
`doctor_name`, `treatment_name`	Doktor ve tedaviler (virgülle ayrılmış). Eksikse `Doktor Atanmamış`, `Tedavi Yok` gelir
`occupation`, `tags[]`	Meslek ve etiketler (`id`, `name`, `color`)
`time_label`	Tatillerde `Tüm gün`, `HH:mm–HH:mm` veya `HH:mm sonrası`
`appointment_id`	Randevu kimliği
`show_details`	Tatillerde `false`
`meta`	Randevularda `status`, `status_label`, `is_old_slot`, `reschedule_confirmation_pending`, `is_hard_reserved`, `original_scheduled_at`, `proposed_scheduled_at`, `pending_expires_at`. Tatillerde `holiday_name`, `holiday_type`, `holiday_source`, `is_full_day`, `blocks_appointments`, `clinic_closed`

curl "https://app.flextell.ai/api/v1/appointments/calendar?from=2026-10-12&to=2026-10-18" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

Aylık bir görünüm için ay başından ay sonuna tek istek yeterlidir; en çok 50 günlük sınır bir aya sığar.

Randevu özeti

GET /appointments/summary, kliniğin saat diliminde bugünkü randevuların sayısını verir. Parametre almaz; liste süzgeçleri uygulanmaz.

{
  "success": true,
  "data": {
    "date": "2026-10-13",
    "total": 18,
    "pending": 4,
    "approved": 9,
    "completed": 3
  }
}

total iptal, red ve gelmedi dahil her statüyü sayar. pending, approved ve completed statü başına sayılardır; üçünün toplamı total olmayabilir. Silinmiş randevular sayılmaz. Sayılar her istekte yeniden hesaplanır. Özet kliniğin tamamını kapsadığı için View:Appointment iznine ek olarak tüm randevuları görme izni (Tümünü Görüntüle) gerekir. Yoksa 403 döner.

Web paneli ve mobil uygulama bu uç noktayı çağırmaz. Panelin “bugün” kartları farklı bir istatistik uç noktasından beslenir.

Saat dilimi

Tüm tarih-saat değerleri kliniğin saat dilimine göre okunur ve yazılır. Varsayılan saat dilimi Europe/Istanbul’dur.

Yön	Kural
Giriş	Ofseti olmayan değer (`2026-10-14T09:00:00`) klinik saat diliminde okunur. `Z` veya `+03:00` gibi ofset taşıyan değer olduğu gibi kabul edilir
Çıkış	Tarih-saat alanları klinik saat diliminde ofsetli döner (`2026-10-14T09:00:00+03:00`)
Başlık ve meta	Yanıtlar `X-Timezone` başlığını ve `meta.timezone` alanını taşır
Gün sınırları	`available-slots` `date`, takvim `from`/`to` ve özetin “bugün” değeri klinik saat diliminin günlerine göre hesaplanır
Saat metinleri	Uygun saat yanıtındaki `start_at` ve `end_at`, `HH:mm` metnidir ve klinik yerel saatidir

Veri biçimleri için genel kurallar: Veri biçimleri.

Hatalar ve yetki

Bu uç noktalara özgü hatalar yukarıdaki bölümlerdedir. Genel hata kodları için Hata kodları sayfasına bakın.

Kod	HTTP	Ne zaman
`FORBIDDEN`	403	Scope veya izin eksik. `summary` için tüm randevuları görme izni de gerekir
`RESOURCE_NOT_FOUND`	404	Doktor veya tedavi kimliği bulunamadı
`VALIDATION_FAILED`	422	Zorunlu parametre eksik, `user_id` kliniğin üyesi değil, takvim aralığı geçersiz

İzinlerin rollerdeki karşılıkları ve görünürlük kuralları için İzinler ve görünürlük 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

Uygun saatler ve takvim

Endpoint özeti

Form seçenekleri

Uygun saatler

Takvim akışı

Randevu özeti

Saat dilimi

Hatalar ve yetki

​Endpoint özeti

​Form seçenekleri

​Uygun saatler

​Takvim akışı

​Randevu özeti

​Saat dilimi

​Hatalar ve yetki

Endpoint özeti

Form seçenekleri

Uygun saatler

Takvim akışı

Randevu özeti

Saat dilimi

Hatalar ve yetki