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

# Dosyalar API

> Hastalara, personellere, tenant'a veya diğer sistem kayıtlarına bağlı dosyaları yüklemek, listelemek ve silmek için endpoint'ler.

<Note>
  Tüm isteklerde `X-Tenant` header'ı **zorunludur**. Dosyalar her zaman belirli bir varlığa (hasta, personel vb.) bağlanmak zorundadır ve **hiçbir dosya başka bir tenant'a ait bir varlığa yüklenemez/ilişkilendirilemez**.
</Note>

<Warning>
  Dosyalar için **güncelleme (`PUT`) endpoint'i bulunmamaktadır**. Değişiklik gerekirse mevcut dosya silinip yenisi yüklenmelidir.
</Warning>

## Endpoint özeti

| Metot    | Endpoint                   | Açıklama                                    |
| -------- | -------------------------- | ------------------------------------------- |
| `GET`    | `/api/v1/files`            | Dosyaları filtreli olarak listeler          |
| `GET`    | `/api/v1/files/{id}`       | Tek bir dosyanın detaylarını getirir        |
| `POST`   | `/api/v1/files`            | Yeni dosya yükler (`multipart/form-data`)   |
| `DELETE` | `/api/v1/files/{id}`       | Dosyayı soft delete eder                    |
| `DELETE` | `/api/v1/files/{id}/force` | Dosyayı kalıcı olarak siler (storage dahil) |

<Tip>
  Tüm parametreler, alanlar ve örnek istek/yanıtlar için **[API Referansı](/api-reference)** sekmesine bakın.
</Tip>

## Dosya kavramı

Sistemdeki dosyalar; **hastalara (müşterilere)**, **personellere (kullanıcılara)**, **tenant'ın kendisine** veya sistemdeki diğer kayıtlara (yapay zeka raporları, sohbet kayıtları vb.) eklenen doküman, görsel veya raporları temsil eder.

<Info>
  API size doğrudan fiziksel dosyayı (byte array olarak) dönmez; bunun yerine dosyanın **meta verilerini** ve dosyaya güvenli bir şekilde erişebileceğiniz **kısa ömürlü geçici linkleri** (`temporary_url`) döner.
</Info>

## İş kuralları

<Warning>
  **Dosya yükleme formatı:** Bu istek JSON olarak yapılamaz. Body formatı kesinlikle **`multipart/form-data`** olmalıdır. Maksimum dosya boyutu **50 MB** (51200 KB)'dır.
</Warning>

<Warning>
  **Tenant izolasyonu:** `fileable_id` ile belirtilen varlık, işlemi yapan tenant'a ait olmak **zorundadır**.

  Hata mesajı: `The selected fileable does not belong to this tenant.`
</Warning>

## Silme kuralları

### Force delete (`DELETE /api/v1/files/{id}/force`)

<Warning>
  Geri alınamaz. Dosya hem veritabanından kalıcı olarak silinir hem de fiziksel storage (S3 vb.) üzerinden temizlenmesi tetiklenir.
</Warning>

## Yetkilendirme

### Uygulama izinleri (permissions)

| İşlem                       | Permission         |
| --------------------------- | ------------------ |
| Listeleme                   | `ViewAny:File`     |
| Detay / Tek gösterme        | `View:File`        |
| Dosya yükleme               | `Create:File`      |
| Silme (soft delete)         | `Delete:File`      |
| Kalıcı silme (force delete) | `ForceDelete:File` |

### Token scope'ları (Passport)

| İşlem                                     | Scope         |
| ----------------------------------------- | ------------- |
| Okuma (`index`, `show`)                   | `files:read`  |
| Yazma (`store`, `destroy`, `forceDelete`) | `files:write` |