> ## 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 > Dosyaları listelemeyi, yüklemeyi, indirmeyi, sıralamayı ve silmeyi; dosya türlerini ve dosyanın bağlanabildiği kayıtları anlatır. Dosya, bir kayda bağlı belge, görsel, ses ya da videodur: hastanın röntgeni, tedavi galerisindeki bir fotoğraf, kliniğin kataloğu gibi. Her dosya tam bir kayda bağlanır (`fileable_type` ve `fileable_id`). Bu sayfa `/v1/files` kaynağını anlatır. Yükleme akışının ayrıntıları (ön imzalı yükleme, MIME türleri, boyut sınırları, depolama kotası) için [Dosya yükleme](/api/istekler/dosya-yukleme) sayfasına bakın. Her istek `Authorization: Bearer ` ve `X-Tenant: ` 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/files` | Dosyaları listeler, arar, filtreler. | `files:read` | `View:File` | | `POST` | `/v1/files` | Tek dosyayı `multipart/form-data` ile yükler. | `files:write` | `Create:File` | | `POST` | `/v1/uploads/presign` | Ön imzalı yükleme adresi üretir. | `files:write` | `Create:File` | | `POST` | `/v1/uploads/confirm` | Ön imzalı yüklemeyi onaylar, dosya kaydını oluşturur. | `files:write` | `Create:File` | | `GET` | `/v1/files/{id}` | Tek dosyayı getirir. | `files:read` | `View:File` | | `GET` | `/v1/files/{id}/download` | Dosyayı indirir. | `files:read` | `Download:File` | | `GET` | `/v1/files/group/{id}/download` | Bir dosya grubunu ZIP olarak indirir. | `files:read` | `Download:File` | | `PUT` | `/v1/files/reorder` | Tedavi ve tedavi grubu galerisini sıralar. | `files:write` | `Reorder:File` | | `DELETE` | `/v1/files/{id}` | Dosyayı siler. | `files:write` | `Delete:File` | Hastanın dosyalarını gruplanmış hâlde almak için `GET /v1/customers/{id}/files` kullanılır. Bu endpoint `customers:read` scope'u, `View:Customer` ve `View:File` izinlerini ister. Bkz. [Hastalar](/api/kaynaklar/hastalar). ## Dosya nesnesi Dosya yanıtlarının alanları: | Alan | Tür | Açıklama | | - | - | - | | `id` | integer | Dosya kimliği. | | `name` | string | Görünen ad. | | `description` | string veya `null` | Açıklama; en çok 1000 karakter. | | `type` | string | Dosya türü. Değerler aşağıdaki "Dosya türleri" bölümündedir. | | `mime_type` | string veya `null` | Dosyanın MIME türü. | | `size` | integer veya `null` | Bayt cinsinden boyut. | | `formatted_size` | string | Okunur boyut, örneğin `1,50 MB`. Boyut yoksa `N/A`. | | `group_id` | string (UUID) | Birlikte yüklenen dosyaların ortak kimliği. | | `fileable_type` | string | Dosyanın bağlı olduğu kayıt türü. | | `fileable_id` | integer | Bağlı kaydın kimliği. | | `fileable_name` | string veya `null` | Bağlı kaydın adı. Bağlı kayıt yoksa ya da başka klinikteyse `null`. | | `sort_order` | integer veya `null` | Galerideki sıra. Yalnızca tedavi ve tedavi grubu dosyalarında dolu. | | `temporary_url` | string | Dosyayı göstermek için geçici imzalı adres. | | `temporary_thumbnail_url` | string | Küçük resim için geçici imzalı adres. | | `record_state` | object | `is_read_only` ve `reason_code`. Bkz. aşağıdaki not. | | `created_at`, `updated_at`, `deleted_at` | string | Klinik saat diliminde, saat farkıyla birlikte tarih. Silinen dosyalar listelenmediği için `deleted_at` pratikte `null` gelir. | `fileable_name` değeri bağlı kayda göre şöyle belirlenir: hasta ve lead için ad soyad (yoksa telefon), sohbet mesajı için hastanın adı, kullanıcı, klinik, tedavi ve tedavi grubu için `name`, AI raporu için `title`. `record_state`, hasta, lead ve sohbet mesajı dosyalarında hastanın durumunu izler. Hasta verileri imha edilmişse `is_read_only` `true` olur (`reason_code`: `CUSTOMER_ERASED`). Lead size atanmamışsa neden `LEAD_NOT_ASSIGNED` olur. Diğer bağlı kayıtlarda dosya her zaman yazılabilirdir. ### Dosya türleri `type` alanı şu değerlerden birini alır: | Değer | Anlamı | Not | | - | - | - | | `image` | Görsel | | | `form_image` | Form görseli | | | `before_after` | Öncesi/sonrası görseli | | | `audio` | Ses | Sohbetten gönderilen sesli mesajlar bu türde saklanır. | | `video` | Video | | | `catalog` | Katalog | Klinik başına en çok bir tane olabilir. | | `certificate` | Sertifika | | | `other` | Diğer | | Klinikte zaten bir `catalog` dosyası varken ikincisini yüklemek `500 SERVER_ERROR` döndürür. Yeni katalog yüklemeden önce eskisini silin. ## Bağlanabilen kayıtlar `fileable_type` sekiz değerden birini alır. Kayıt, çağırdığınız kliniğe ait olmalıdır. | `fileable_type` | Bağlı kayıt | Not | | - | - | - | | `customer` | Hasta | | | `lead` | Lead | Lead'in size görünür olması gerekir. | | `user` | Kullanıcı (örneğin doktor) | Kullanıcı klinik üyesi olmalıdır. Başka biri dosya yüklerse o kullanıcıya bildirim gider. | | `tenant` | Klinik | Kliniğin kendi dosyaları, örneğin katalog. | | `chat_log` | Sohbet mesajı | Sohbetlerden gönderilen medya. | | `ai_report` | AI raporu | | | `treatment` | Tedavi | Görsel galeri. | | `treatment_group` | Tedavi grubu | Görsel galeri. | Tedavi ve tedavi grubu galerileri yalnızca görsel (`image/*`) kabul eder ve hastaya gönderilen içeriktir. Bu galerilerde yükleme, sıralama ve silme için dosya izninin yanında `Update:Treatment` ya da `Update:TreatmentGroup` izni de gerekir. Eksikse `403 FORBIDDEN` döner. Bkz. [Tedaviler](/api/kaynaklar/tedaviler). ### Kimin hangi dosyayı gördüğü * Dosya izinleri klinik geneldir; yalnızca kendi dosyalarınızı gösteren bir izin yoktur. * `ViewAllLeads:Lead` iznine sahip olmayan kullanıcılar, yalnızca kendilerine atanmış lead'lerin dosyalarını görür. Başkasının lead'i için yazma isteği `403 LEAD_NOT_ASSIGNED` döner. * Sohbet mesajına bağlı dosyalar, o sohbeti görme yetkiniz yoksa listelenmez ve indirilemez. * İmha edilmiş hastanın dosyalarını yüklemek ya da silmek `409 CUSTOMER_ERASED` döner. Ayrıntı için [İzinler ve görünürlük](/api/izinler-ve-gorunurluk) sayfasına bakın. ## Dosyaları listeleme `GET /v1/files` sayfalanmış bir liste döner. Silinen dosyalar listelenmez. | Parametre | Açıklama | | - | - | | `search` | En çok 255 karakter. Ad, açıklama ve MIME türünde tam metin araması yapar. | | `type` | Dosya türüne göre filtreler. | | `fileable_type`, `fileable_id` | Belirli bir kayda bağlı dosyaları getirir. | | `created_at_from`, `created_at_to` | Yüklenme tarihi aralığı. `created_at_to`, `created_at_from` değerinden önce olamaz. Tarihler klinik saat dilimine göre yorumlanır; `created_at_to` seçilen günün tamamını kapsar. | | `per_page`, `page` | Sayfalama. `per_page` 1 ile 100 arasındadır, varsayılan 15. Bkz. [Sayfalama](/api/istekler/sayfalama). | | `sort_by`, `sort_order` | Sıralama. Bkz. aşağıdaki "Sıralama" bölümü. | ```bash theme={null} curl -G https://app.flextell.ai/api/v1/files \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ --data-urlencode "fileable_type=customer" \ --data-urlencode "fileable_id=123" \ --data-urlencode "type=image" \ --data-urlencode "created_at_from=2026-10-01" ``` ## Yükleme ve indirme Dosya iki yolla yüklenir: `POST /v1/files` ile tek istekte (en çok 50 MB) ya da `POST /v1/uploads/presign` ve `POST /v1/uploads/confirm` ile üç adımda (en çok 50 MB, `video/*` için 5 GB). İkinci yolda aynı `group_id` ile birden çok dosyayı tek gruba toplayabilirsiniz. `POST /v1/files` her dosyayı kendi grubuna koyar. Alanlar, MIME türleri, depolama sınırı ve hata kodları [Dosya yükleme](/api/istekler/dosya-yukleme) sayfasındadır. ### Tek dosyayı indirme `GET /v1/files/{id}/download` dosyayı `Content-Disposition: attachment` ile bayt akışı olarak döner. Dosya adında uzantı yoksa kayıtlı uzantı eklenir. Dosyanın saklanan içeriğine ulaşılamıyorsa `404 FILE_CONTENT_UNAVAILABLE` döner. ```bash theme={null} curl https://app.flextell.ai/api/v1/files/123/download \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -o panoramik.pdf ``` Dosyayı yalnızca göstermek istiyorsanız yanıttaki `temporary_url` değerini kullanın. ### Grubu ZIP olarak indirme `GET /v1/files/group/{id}/download` isteğinde `{id}`, grubun herhangi bir dosyasının kimliğidir. Yanıt `group-{group_id}.zip` adlı bir ZIP'tir. Gruba şu dosyalar girer: aynı `group_id`, `fileable_type`, `fileable_id` ve `type` değerine sahip dosyalar. Aynı ada sahip dosyalar `ad_1.uzanti` biçiminde yeniden adlandırılır. İçeriği olmayan dosyalar ve size görünmeyen lead dosyaları ZIP'e girmez. Dosyanın grubu yoksa `404 RESOURCE_NOT_FOUND`, hiçbir dosyanın içeriği yoksa `404 FILE_CONTENT_UNAVAILABLE` döner. ## Sıralama Liste sıralaması için `sort_by` şu anahtarları kabul eder: `name`, `size`, `type`, `sort_order`, `created_at`, `updated_at`. Varsayılan `created_at` alanıdır, yeniden eskiye doğru. `sort_order` yalnızca `asc` ya da `desc` olabilir. Anahtar listede yoksa istek `422 VALIDATION_FAILED` ile reddedilir. `sort_by` göndermezseniz ve `search` kullanırsanız sonuçlar önce arama alaka düzeyine göre gelir. Genel kurallar için [Arama, filtreleme ve sıralama](/api/istekler/filtreleme-ve-siralama) sayfasına bakın. Sıralamayı her zaman `sort_order` ile birlikte açıkça verin: ```bash theme={null} curl -G https://app.flextell.ai/api/v1/files \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ --data-urlencode "fileable_type=treatment" \ --data-urlencode "fileable_id=123" \ --data-urlencode "sort_by=sort_order" \ --data-urlencode "sort_order=asc" ``` ### Galeri sırasını değiştirme Yeni yüklenen galeri görseli listenin sonuna eklenir. Sırayı değiştirmek için `PUT /v1/files/reorder` kullanın. İstek `Reorder:File` iznini ve ilgili `Update:Treatment` ya da `Update:TreatmentGroup` iznini ister. | Alan | Zorunlu | Açıklama | | - | - | - | | `fileable_type` | Evet | `treatment` ya da `treatment_group`. | | `fileable_id` | Evet | Tedavi ya da tedavi grubu kimliği. | | `ids` | Evet | Dosya kimliklerinin yeni sırası. En az 1 kimlik, tekrarsız. | `ids` listesi, galerideki bütün dosyaları eksiksiz içermelidir; eksik ya da yabancı kimlik varsa istek `422 FILE_REORDER_MISMATCH` ile reddedilir ve hiçbir şey değişmez. Başarılı yanıt, dosyaları yeni sırasıyla ve `sort_order` 1'den n'e olacak biçimde döner. ```bash theme={null} curl -X PUT https://app.flextell.ai/api/v1/files/reorder \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Content-Type: application/json" \ -d '{ "fileable_type": "treatment", "fileable_id": 123, "ids": [31, 29, 30] }' ``` ## Silme `DELETE /v1/files/{id}` isteği başarılı olursa `200` ve `{"success": true, "data": {"message": "Dosya başarıyla silindi"}}` döner. Dosya silindiğinde içeriği hemen kaldırılır. Aynı içeriği başka bir dosya kullanmıyorsa küçük resim de silinir. API'de geri alma yoktur. Silinen bir dosyanın Geri Dönüşüm Kutusu'ndan içeriğiyle geri geleceğini varsaymayın. Bkz. [Silme ve yaşam döngüsü](/api/istekler/silme-yasam-dongusu). Silinen dosya kota hesabından hemen düşer. Hasta silindiğinde hastanın dosyaları da silinir. ## Hatalar Hata zarfı için [Hata yanıtları](/api/istekler/hatalar), tüm kodlar için [Hata kodları](/api/istekler/hata-kodlari) sayfasına bakın. | Kod | HTTP | Ne zaman | | - | - | - | | `UNAUTHENTICATED` | 401 | Token eksik ya da geçersiz. | | `FORBIDDEN` | 403 | Scope ya da izin eksik; galeri dosyası için `Update:Treatment` ya da `Update:TreatmentGroup` yok. | | `LEAD_NOT_ASSIGNED` | 403 | Dosya, size atanmamış bir lead'e ait. | | `RESOURCE_NOT_FOUND` | 404 | Dosya yok ya da size görünmüyor (`Dosya bulunamadı`). | | `FILE_CONTENT_UNAVAILABLE` | 404 | Dosyanın saklanan içeriğine ulaşılamıyor. | | `CUSTOMER_ERASED` | 409 | Hasta verileri imha edilmiş; kayıt salt okunurdur. | | `VALIDATION_FAILED` | 422 | Alan eksik ya da geçersiz, `sort_by` anahtarı izinli değil. | | `FILE_REORDER_MISMATCH` | 422 | `ids`, galerideki dosyalarla birebir aynı değil. | | `STORAGE_HARD_LIMIT_EXCEEDED` | 422 | Yükleme depolama üst sınırını aşar. | | `SUBSCRIPTION_REQUIRED` | 402 | Abonelik sona erdi ya da klinik ödeme kısıtında. Bkz. [Erişim kilitleri](/api/istekler/erisim-kilitleri). | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.