Dosyalar

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 sayfasına bakın. 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/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.

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.

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 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.
`sort_by`, `sort_order`	Sıralama. Bkz. aşağıdaki “Sıralama” bölümü.

curl -G https://app.flextell.ai/api/v1/files \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  --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 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.

curl https://app.flextell.ai/api/v1/files/123/download \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -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 sayfasına bakın. Sıralamayı her zaman sort_order ile birlikte açıkça verin:

curl -G https://app.flextell.ai/api/v1/files \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  --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.

curl -X PUT https://app.flextell.ai/api/v1/files/reorder \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -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ü.

Silinen dosya kota hesabından hemen düşer. Hasta silindiğinde hastanın dosyaları da silinir.

Hatalar

Hata zarfı için Hata yanıtları, tüm kodlar için Hata kodları 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.

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

Dosya nesnesi

Dosya türleri

Bağlanabilen kayıtlar

Kimin hangi dosyayı gördüğü

Dosyaları listeleme

Yükleme ve indirme

Tek dosyayı indirme

Grubu ZIP olarak indirme

Sıralama

Galeri sırasını değiştirme

Silme

Hatalar

​Endpoint özeti

​Dosya nesnesi

​Dosya türleri

​Bağlanabilen kayıtlar

​Kimin hangi dosyayı gördüğü

​Dosyaları listeleme

​Yükleme ve indirme

​Tek dosyayı indirme

​Grubu ZIP olarak indirme

​Sıralama

​Galeri sırasını değiştirme

​Silme

​Hatalar

Endpoint özeti

Dosya nesnesi

Dosya türleri

Bağlanabilen kayıtlar

Kimin hangi dosyayı gördüğü

Dosyaları listeleme

Yükleme ve indirme

Tek dosyayı indirme

Grubu ZIP olarak indirme

Sıralama

Galeri sırasını değiştirme

Silme

Hatalar