Arama, filtreleme ve sıralama

Liste endpoint’leri (GET ile koleksiyon döndürenler) aynı sorgu parametresi kurallarını paylaşır: search ile arama, <alan>_from / <alan>_to ile tarih aralığı, sort_by ve sort_order ile sıralama. Bu sayfa genel kuralları anlatır. Bir listenin hangi filtreleri ve sıralama anahtarlarını desteklediğini ilgili kaynak sayfasında ve API Referansı’nda bulursunuz. Sonuçları sayfalamak için Sayfalama sayfasına bakın.

Tüm örneklerde https://app.flextell.ai/api/v1 tabanı, Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> başlıkları kullanılır. Başlıklar için İstek başlıkları sayfasına bakın.

Arama

search parametresi, listenin arama alanlarında metin araması yapar.

Arama metni harf ve rakam olmayan her karakterden bölünür. Her parça önek olarak eşleşir ve tüm parçalar birlikte (VE) aranır.
ali veli araması, hem ali hem veli ile başlayan sözcükleri içeren kayıtları bulur.
test@example.com üç parçaya bölünür: test, example, com.
+90 555 111 22 33 beş sayısal önek olarak aranır.
Türkçe harfler (ı, ğ, ü, ş, ö, ç) olduğu gibi korunur.
Yalnızca noktalama işaretlerinden oluşan bir arama (!!!) hiçbir kayıtla eşleşmez.
Sözcük kökü bulma ve durak sözcük ayıklama yoktur. Arama yalnızca yazdığınız önekle eşleşir.
search değeri genellikle en fazla 255 karakterdir.

Sıralama ile ilişkisi. sort_by göndermezseniz sonuçlar önce eşleşme alaka düzeyine, sonra listenin varsayılan sıralamasına göre gelir. sort_by gönderirseniz alaka düzeyi devre dışı kalır ve sonuçlar yalnızca istediğiniz sıraya göre dizilir.

Kullanıcılar, doktorlar ve asistanlar listelerinde search, kimlik (id), ad ve e-posta üzerinde çalışır.

Filtreler

Filtreler sorgu parametreleridir. Hangi filtrelerin geçerli olduğu listeye göre değişir. En sık görülen adlar şunlardır.

Parametre	Anlamı
`status`	Duruma göre filtreler. Geçerli değerler listeye özgüdür.
`is_active`	Aktif/pasif kayıtları filtreler.
`<ilişki>_id`	İlişkili kaydın kimliğine göre filtreler (örneğin `doctor_id`).
`<alan>_from`, `<alan>_to`	Tarih aralığı. Sonraki bölüme bakın.

API tanımadığı veya kaldırılmış parametreleri sessizce yok sayar. Filtre adını yanlış yazarsanız hata almazsınız, filtresiz tam liste döner. Beklediğinizden çok kayıt geliyorsa parametre adını API Referansı’ndaki liste ile karşılaştırın.

Mantıksal (boolean) filtrelerde 1 ve 0 gönderin. true ve false metinlerini yalnızca bazı endpoint’ler kabul eder.

Tarih aralığı filtreleri

Her filtrelenebilir tarih alanı için iki parametre vardır: <alan>_from ve <alan>_to. Örneğin created_at_from, created_at_to, issue_date_from, issue_date_to, scheduled_at_from. Eski adlar (date_from, from, created_from, created_until) kaldırılmıştır ve çalışmaz.

Kural	Açıklama
Sınırlar dahildir	`_from` ve `_to` değerlerinin ikisi de aralığa dahildir.
Tarih biçimi	`YYYY-MM-DD` veya saat bilgili ISO 8601 (`2026-10-12T14:30:00+03:00`).
Sıra	`_to`, `_from` değerinden önce olamaz. Olursa `_to` alanında 422 döner.

Anlık (saatli) alanlar

created_at gibi anlık alanlar UTC saklanır, ama sınırlar klinik saat dilimine göre okunur.

Gönderdiğiniz	Yorum
Yalnızca tarih, `_from`	O günün 00:00:00 saati (klinik saati).
Yalnızca tarih, `_to`	O günün 23:59:59.999999 saati (klinik saati). Günün tamamı dahil olur.
Saat dilimli tarih-saat (`Z`, `+03:00`)	Verdiğiniz saat dilimi geçerlidir.
Saat dilimsiz tarih-saat	Klinik saati kabul edilir.

Sorgu dizesinde + işareti boşluk olarak okunur. Saat dilimi farkını %2B03:00 olarak kodlayın.

Takvim tarihi alanları

Fatura issue_date ve due_date gibi takvim tarihi alanlarında saat dilimi kayması uygulanmaz. Değerler olduğu gibi karşılaştırılır. Yalnızca tarih içeren _to değeri o günün tamamını kapsar. Randevunun scheduled_at alanı kendi saat dilimi çözümlemesini kullanır, ama parametre adları aynıdır. Saat dilimi ve tarih biçimi kuralları için Veri biçimleri sayfasına bakın.

Sıralama

İki parametre sıralamayı belirler.

string

Sıralanacak alan. Değer, listenin izin verdiği anahtarlardan biri olmalıdır. Anahtarlar listeye göre değişir ve API Referansı’nda sort_by parametresinin değer listesinde yer alır.

string

Yön. Yalnızca küçük harfle asc (artan) veya desc (azalan). ASC, Desc gibi değerler 422 döndürür.

Davranış kuralları:

İkisi de yoksa, liste kendi varsayılan sütununu ve yönünü kullanır. Çoğu liste created_at sütununa göre azalan sıralar. Bazı listelerin varsayılanı farklıdır (aşağıdaki tabloya bakın).
Yalnızca sort_order varsa, varsayılan sütun belirttiğiniz yönde sıralanır.
Yalnızca sort_by varsa, metin sütunları artan (A’dan Z’ye), sayı ve tarih sütunları azalan sıralanır. İstediğiniz yönü her zaman açıkça sort_order ile belirtin.
Metin sıralaması Türkçe alfabeye göre yapılır. Sıra Armut, Ceviz, Çilek, elma, Elma, ıhlamur, İncir, Oya, Ördek, Sarımsak, Şeftali, Uğur, Üzüm, Zeytin biçimindedir. Büyük/küçük harf farkı yalnızca eşit sözcükleri ayırmada rol oynar.
Eşit değerler kararlı sıralanır. Kayıt kimliği aynı yönde son ölçüt olarak eklenir. Böylece sayfalar arasında kayıtlar yer değiştirmez.
Sıralama sayfalamadan önce, filtrelenmiş kümenin tamamı üzerinde uygulanır.

Liste	Örnek `sort_by` anahtarları	Varsayılan
`GET /customers`	`first_name`, `last_name`, `date_of_birth`, `gender`, `created_at`, `updated_at`	`created_at` azalan
`GET /appointments`	`scheduled_at`, `status`, `created_at`, `updated_at`, `upcoming`	`scheduled_at` azalan
`GET /sales`	`sale_date`, `created_at`, `updated_at`, `status`, `total_price`, `balance`	`sale_date` azalan
`GET /quick-replies`	`shortcut`, `usage_count`, `last_used_at`, `created_at`, `updated_at`	`usage_count` azalan

Randevularda `upcoming`

GET /appointments için sort_by=upcoming özel bir anahtardır. Yaklaşan randevular önce gelir (en yakın olan en başta), ardından geçmiş randevular gelir (en yeni olan en başta). Bu anahtar sort_order değerini yok sayar ve search alaka düzeyinin yerine geçer.

Örnek

Ekim 2026’da oluşturulan hastaları soyadına göre A’dan Z’ye sıralayın:

curl -G "https://app.flextell.ai/api/v1/customers" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  --data-urlencode "search=ayşe" \
  --data-urlencode "created_at_from=2026-10-01" \
  --data-urlencode "created_at_to=2026-10-31" \
  --data-urlencode "sort_by=last_name" \
  --data-urlencode "sort_order=asc"

const params = new URLSearchParams({
  search: "ayşe",
  created_at_from: "2026-10-01",
  created_at_to: "2026-10-31",
  sort_by: "last_name",
  sort_order: "asc",
});

const res = await fetch(`https://app.flextell.ai/api/v1/customers?${params}`, {
  headers: {
    Authorization: "Bearer <access_token>",
    "X-Tenant": "<tenant_id>",
  },
});

Hangi hastaları görebileceğiniz kullanıcı izinlerinize bağlıdır. Ayrıntı için İzinler ve görünürlük sayfasına bakın.

Form seçenek endpoint’leri

Form açılır listelerini doldurmak için tasarlanmış endpoint’ler arama ve sıralamayı farklı işler.

GET /appointments/options/doctors, /rooms, /assistants, /products
GET /appointments/options/doctors/{id}/treatments
GET /appointments/options/treatments/{id}
GET /offers/options/products, /treatments

Kullanım	Davranış
`ids[]` olmadan	Aranabilir (`search`) seçici listesi döner. Yalnızca aktif kayıtlar gelir.
`ids[]` ile	Tam olarak verdiğiniz kayıtlar döner; pasif kayıtlar dahildir. `search` ve aktiflik filtresi uygulanmaz.
Sıralama	Ada göre, eşitlikte kimliğe göre.
`per_page`	Varsayılan 15. `ids[]` gönderirseniz varsayılan, gönderdiğiniz kimlik sayısıdır.

ids[] en fazla 100 tam sayı alır. Düzenleme formunda daha önce seçilmiş (şimdi pasif olabilecek) bir kaydın adını göstermek için bu kullanımı tercih edin. Randevu seçenek endpoint’leri Create:Appointment veya Update:Appointment iznini, teklif seçenek endpoint’leri Create:Offer veya Update:Offer iznini gerektirir.

Hatalı parametreler

Geçersiz sorgu parametreleri 422 VALIDATION_FAILED hatası üretir. Yanıt gövdesinde errors alanı, hatalı parametrenin adını anahtar olarak taşır.

Durum	Sonuç
`sort_by`, listenin izin verdiği anahtarlardan biri değil	422, `errors.sort_by`. Bazı listeler bilinmeyen anahtarı doğrulamadan varsayılan sütuna döner. Her durumda yalnızca belgelenmiş anahtarları kullanın.
`sort_order`, `asc` veya `desc` değil (büyük harf dahil)	422, `errors.sort_order`.
`<alan>_from` veya `<alan>_to` geçerli bir tarih değil	422, ilgili parametre.
`<alan>_to`, `<alan>_from` değerinden önce	422, `errors.<alan>_to`.
Tanınmayan parametre adı	Hata yok, parametre yok sayılır.
Yalnızca noktalama içeren `search`	Hata yok, boş liste döner.

Hata yanıtının yapısı için Hatalar, tüm kodlar için Hata kodları 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

Arama, filtreleme ve sıralama

Arama

Filtreler

Tarih aralığı filtreleri

Anlık (saatli) alanlar

Takvim tarihi alanları

Sıralama

Randevularda `upcoming`

Örnek

Form seçenek endpoint’leri

Hatalı parametreler

​Arama

​Filtreler

​Tarih aralığı filtreleri

​Anlık (saatli) alanlar

​Takvim tarihi alanları

​Sıralama

​Randevularda upcoming

​Örnek

​Form seçenek endpoint’leri

​Hatalı parametreler

Arama

Filtreler

Tarih aralığı filtreleri

Anlık (saatli) alanlar

Takvim tarihi alanları

Sıralama

Randevularda `upcoming`

Örnek

Form seçenek endpoint’leri

Hatalı parametreler