> ## 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.

# Tatiller

> Resmî tatilleri, klinik tatillerini ve istisnaları API ile yönetmeyi anlatır.

`/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](/api/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` |

<Note>
  `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.
</Note>

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](/api/istekler/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.

<ParamField body="date" type="string" required>
  `Y-m-d` biçiminde tarih.
</ParamField>

<ParamField body="name" type="string" required>
  En fazla 255 karakter.
</ParamField>

<ParamField body="type" type="string" required>
  `national`, `religious`, `observance` veya `custom`.
</ParamField>

<ParamField body="blocks_appointments" type="boolean" required>
  `true` ise tatil randevuyu engeller, `false` ise yalnızca bilgi amaçlıdır.
</ParamField>

<ParamField body="is_full_day" type="boolean" required>
  `true` ise gün boyu kapalı, `false` ise kısmi kapanış.
</ParamField>

<ParamField body="starts_at" type="string">
  `H:i` biçiminde başlangıç saati. `is_full_day` `false` ise zorunludur.
</ParamField>

<ParamField body="ends_at" type="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.
</ParamField>

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.

<CodeGroup>
  ```bash curl theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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",
    }),
  });
  ```
</CodeGroup>

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.

<ParamField body="blocks_appointments" type="boolean" required>
  Tatil randevuyu engellesin mi.
</ParamField>

<ParamField body="is_full_day" type="boolean" required>
  Kapanış gün boyu mu.
</ParamField>

<ParamField body="starts_at" type="string">
  Kısmi kapanış başlangıcı (`H:i`).
</ParamField>

<ParamField body="ends_at" type="string">
  Kısmi kapanış bitişi (`H:i`).
</ParamField>

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

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

```bash curl theme={null}
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)](/panel/randevular/tatiller).

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](/api/kaynaklar/randevu-uygunlugu-ve-takvim) sayfasına bakın. Ayar yönetimi için [Ayarlar](/api/kaynaklar/ayarlar) sayfasına bakın.

<Info>
  `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.
</Info>

## 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ı](/api/istekler/hata-kodlari) sayfasına bakın. Scope listesi için [Scope'lar](/api/kimlik-dogrulama/scopelar), izin mantığı için [İzinler ve görünürlük](/api/izinler-ve-gorunurluk) sayfasına bakın.


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