Tatiller

/v1/holidays kaynağı kliniğin kapalı olduğu günleri ve saatleri yönetir. İki tür kayıt döner: Flextell’in sağladığı resmî tatiller ve sizin eklediğiniz klinik tatilleri. Resmî tatillerin adını, tarihini ve türünü değiştiremezsiniz. Yalnızca kliniğiniz için randevu engelleme tercihini geçersiz kılabilirsiniz. Her istek Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> başlıklarını taşır. Bkz. Klinikler ve X-Tenant.

Endpoint özeti

Metot	Endpoint	Açıklama	Scope	İzin
`GET`	`/v1/holidays`	Tatilleri listeler.	`holidays:read`	`View:Holiday`
`POST`	`/v1/holidays`	Klinik tatili oluşturur.	`holidays:write`	`Create:Holiday`
`GET`	`/v1/holidays/{id}`	Tek tatili getirir (geçerli değerlerle).	`holidays:read`	`View:Holiday`
`PUT`	`/v1/holidays/{id}`	Klinik tatilini günceller.	`holidays:write`	`Update:Holiday`
`DELETE`	`/v1/holidays/{id}`	Klinik tatilini siler.	`holidays:delete`	`Delete:Holiday`
`PUT`	`/v1/holidays/{id}/override`	Resmî tatil için klinik tercihini kaydeder.	`holidays:write`	`Update:Holiday`
`DELETE`	`/v1/holidays/{id}/override`	Klinik tercihini siler, tatil varsayılana döner.	`holidays:delete`	`Update:Holiday`

DELETE /v1/holidays/{id}/override isteği holidays:delete scope’unu ister, ancak izin olarak Delete:Holiday değil Update:Holiday arar. Token’ınızda scope, rolünüzde Update:Holiday izni olmalıdır.

Kayıt silme kalıcıdır. Tatiller Geri Dönüşüm Kutusu’na gitmez.

Tatil türleri

Her tatilin bir type değeri ve arayüzdeki karşılığı olan type_label alanı vardır.

`type`	`type_label`
`national`	Resmi tatil
`religious`	Dini bayram
`observance`	Özel gün
`custom`	Kliniğe özel

source alanı kaydın kaynağını verir.

`source`	Anlamı
`calendarific`	Flextell’in sağladığı Türkiye resmî tatilleri. Tüm kliniklerde ortaktır (`is_global: true`).
`flextell`	Flextell’in tanımladığı ortak günler. Tüm kliniklerde ortaktır (`is_global: true`).
`tenant`	Kliniğinizin eklediği tatiller (`is_global: false`).

Önemli alanlar

Alan	Tür	Açıklama
`id`	integer	Tatil kimliği.
`date`	string	`Y-m-d` biçiminde takvim günü. Saat dilimi kaymaz.
`name`	string	Tatil adı.
`type`, `type_label`	string	Tür ve Türkçe etiketi.
`country_code`	string	Ülke kodu (`TR`).
`source`, `is_global`	string, boolean	Kaynak ve ortak kayıt bilgisi.
`blocks_appointments`	boolean	`false` ise tatil yalnızca bilgi amaçlıdır.
`is_full_day`	boolean	`true` ise kapanış günün tamamını kapsar.
`starts_at`, `ends_at`	string veya `null`	Kısmi kapanışın klinik saatiyle `HH:mm` başlangıç ve bitişi.
`has_tenant_override`	boolean	Kliniğiniz bu resmî tatil için tercih kaydettiyse `true`.
`provider_refreshed_at`, `provider_expires_at`	string veya `null`	Resmî tatil verisinin güncellenme ve geçerlilik zamanı.

Yanıttaki değerler her zaman kliniğiniz için geçerli olanlardır. Bir resmî tatil için tercih kaydettiyseniz blocks_appointments, is_full_day, starts_at ve ends_at sizin değerlerinizi gösterir.

Listeleme

GET /v1/holidays kayıtları date alanına göre sıralı döner. Sayfalama kuralları için Sayfalama sayfasına bakın. Bu kaynakta per_page varsayılanı 25, en yüksek değer 100’dür.

Parametre	Açıklama
`date_from`, `date_to`	Tarih aralığı, uçlar dahil.
`year`	2000 ile 2100 arasında yıl.
`source`	`calendarific`, `flextell` veya `tenant`.
`per_page`, `page`	Sayfalama.

Klinik tatili ekleme

POST /v1/holidays yalnızca kliniğinize ait bir tatil oluşturur. Başarılı yanıt 201 döner ve kayıtta source: tenant, is_global: false olur.

string

gerekli

Y-m-d biçiminde tarih.

string

gerekli

En fazla 255 karakter.

string

gerekli

national, religious, observance veya custom.

boolean

gerekli

true ise tatil randevuyu engeller, false ise yalnızca bilgi amaçlıdır.

boolean

gerekli

true ise gün boyu kapalı, false ise kısmi kapanış.

string

H:i biçiminde başlangıç saati. is_full_day false ise zorunludur.

string

H:i biçiminde bitiş saati, starts_at değerinden sonra olmalıdır. Boş bırakırsanız kapanış günün sonuna kadar sürer.

Saatler kliniğin yerel saatidir. Aşağıdaki örnek, 31 Aralık’ta saat 13:00’ten günün sonuna kadar klinik kapanışını ekler.

curl -X POST "https://app.flextell.ai/api/v1/holidays" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-12-31",
    "name": "Yılbaşı arifesi yarım gün",
    "type": "custom",
    "blocks_appointments": true,
    "is_full_day": false,
    "starts_at": "13:00"
  }'

const res = await fetch("https://app.flextell.ai/api/v1/holidays", {
  method: "POST",
  headers: {
    Authorization: "Bearer <access_token>",
    "X-Tenant": "<tenant_id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    date: "2026-12-31",
    name: "Yılbaşı arifesi yarım gün",
    type: "custom",
    blocks_appointments: true,
    is_full_day: false,
    starts_at: "13:00",
  }),
});

Bir klinik tatilini PUT /v1/holidays/{id} ile güncellersiniz. Gövdede yukarıdaki alanlardan istediğinizi gönderebilirsiniz. Resmî bir tatilin kimliğini bu endpoint’e verirseniz 404 (Tenant holiday not found) alırsınız. Resmî tatiller için aşağıdaki geçersiz kılma endpoint’ini kullanın.

Resmî tatili geçersiz kılma

Resmî tatilin adı, tarihi ve türü değişmez. Kliniğiniz yine de o gün çalışıyorsa ya da yalnızca belirli saatlerde kapalıysa tercihinizi PUT /v1/holidays/{id}/override ile kaydedersiniz.

boolean

gerekli

Tatil randevuyu engellesin mi.

boolean

gerekli

Kapanış gün boyu mu.

string

Kısmi kapanış başlangıcı (H:i).

string

Kısmi kapanış bitişi (H:i).

Geçersiz kılma gövdesinde name, date veya type gönderirseniz istek 422 ile reddedilir.

Örnek: bir resmî tatilde (id 123) kliniği açık tutmak için randevu engelini kapatın.

curl

curl -X PUT "https://app.flextell.ai/api/v1/holidays/123/override" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{"blocks_appointments": false, "is_full_day": true}'

Yanıt, geçerli değerleri içeren tatil kaydıdır ve has_tenant_override değeri true olur. Tercihi silmek için DELETE /v1/holidays/{id}/override çağırın. Yanıt, varsayılan değerlere dönmüş tatili verir. Panelde aynı işlem Varsayılana Dön düğmesidir. Bkz. Tatiller (panel). Klinik tatilleri için tercih endpoint’leri kullanılmaz. Onların kimliğiyle çağırırsanız 404 (Global holiday not found) döner.

Etkileri

Tatiller randevu akışlarını şöyle etkiler.

Alan	Etki
Ana anahtar	Kapanışlar yalnızca Resmi tatillerde kapalı ayarı (`appointments.close_on_public_holidays`) açıksa uygulanır. Varsayılan olarak açıktır. Ayar kapalıyken klinik tatilleri de randevuyu engellemez.
Bilgi amaçlı tatil	`blocks_appointments: false` olan tatil randevu engellemez.
Kısmi kapanış	`[starts_at, ends_at)` aralığı engellenir. `ends_at` boşsa günün geri kalanı engellenir. Randevunun herhangi bir dakikası bu aralığa denk gelirse randevu engellenir.
Elle randevu	API ile ve panelden elle oluşturulan randevu tatilde reddedilmez. İstemciler yalnızca uyarı gösterir.
AI asistan	AI asistan kapalı bir tatile randevu vermez: `{tatil adı} nedeniyle klinik bu tarih ve saatte kapalıdır.`
Uygun saatler	`GET /v1/appointments/available-slots` yanıtındaki `closed_periods` alanı günün engelleyen tatillerini listeler. Gün boyu kapanış `00:00` ile `24:00` arasıdır.
Takvim	`GET /v1/appointments/calendar` yanıtı `kind: holiday` öğelerini randevulardan önce verir.

Uygun saat ve takvim yanıtlarının ayrıntıları için Randevu uygunluğu ve takvim sayfasına bakın. Ayar yönetimi için Ayarlar sayfasına bakın.

closed_periods ve takvimdeki holiday öğeleri yalnızca ana anahtar açıkken kapanış olarak işlenir. Ayar kapalıyken takvim tatili göstermeye devam eder, ancak kapalı saymaz.

Hatalar

Kod	HTTP	Ne zaman
`FORBIDDEN`	403	Scope ya da izin eksik. Yalnızca `View:Appointment` veya `appointments:read` bu kaynak için yetmez.
`VALIDATION_FAILED`	422	Geçersiz alan. Örneğin `is_full_day: false` iken `starts_at` yok, `ends_at` `starts_at`’tan önce ya da geçersiz kılmada `name`, `date`, `type` var.
`RESOURCE_NOT_FOUND`	404	Kayıt yok. İleti sabit İngilizce metindir: `Holiday not found`, `Tenant holiday not found` veya `Global holiday not found`.

Genel hata biçimi için Hata kodları sayfasına bakın. Scope listesi için Scope’lar, izin mantığı 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

Endpoint özeti

Tatil türleri

Önemli alanlar

Listeleme

Klinik tatili ekleme

Resmî tatili geçersiz kılma

Etkileri

Hatalar

​Endpoint özeti

​Tatil türleri

​Önemli alanlar

​Listeleme

​Klinik tatili ekleme

​Resmî tatili geçersiz kılma

​Etkileri

​Hatalar

Endpoint özeti

Tatil türleri

Önemli alanlar

Listeleme

Klinik tatili ekleme

Resmî tatili geçersiz kılma

Etkileri

Hatalar