Yanıt yapısı

Flextell API’si başarılı isteklerde üç farklı gövde biçimi döndürür: tekil kaynak zarfı, sayfalı liste ve sayfasız koleksiyon. Bir endpoint’in hangi biçimi kullandığını yanıtta success ve links anahtarlarının olup olmadığına bakarak ayırt edebilirsiniz. Hata yanıtları için Hata yanıtları sayfasına bakın.

Biçim	`success`	`data`	`links`	`meta`
Tekil kaynak veya işlem sonucu	var	nesne	yok	`timezone`
Sayfalı liste	yok	dizi	var	sayfalama bilgisi + `timezone`
Sayfasız koleksiyon	yok	dizi	yok	`timezone`

meta.timezone yalnızca klinik (X-Tenant) bağlamında çalışan endpoint’lerde gelir. Klinik gerektirmeyen endpoint’lerde meta bulunmaz. Klinik seçimi için Klinikler ve X-Tenant sayfasına bakın.

Tekil kaynak yanıtı

Bir kaynağı okuyan, oluşturan veya güncelleyen endpoint’ler success ve data anahtarlarını içeren bir zarf döndürür. Klinik bağlamındaki endpoint’lerde zarfa meta.timezone eklenir. Bu değer, yanıttaki tarih-saat alanlarının hangi saat diliminde yazıldığını gösterir.

{
  "success": true,
  "data": {
    "id": 7,
    "name": "VIP",
    "created_at": "2026-03-01T12:00:00+03:00"
  },
  "meta": { "timezone": "Europe/Istanbul" }
}

success değeri, HTTP durum kodu 2xx olduğunda true olur. Başarılı yanıtlarda şu durum kodları kullanılır:

Kod	Ne zaman
`200`	Okuma, güncelleme, silme ve işlem çağrıları.
`201`	Kaynak oluşturma.
`202`	Kuyruğa alınan işler: AI rapor oluşturma, toplu randevu taşıma, gelen webhook, teklif PDF’i, dışa aktarmalar ve sohbet mesajı gönderimi. Sonuç sonradan bildirim olarak gelir veya kaynağı sorgulayarak izlenir.

Silme çağrıları kaynağı döndürmez. Yanıt, yerelleştirilmiş bir mesaj taşır:

{
  "success": true,
  "data": { "message": "<Kaynak> başarıyla silindi" }
}

Mesaj metni Accept-Language başlığına göre değişir. Kodunuzu message metnine göre dallandırmayın. Başlık ayrıntıları için İstek başlıkları sayfasına bakın.

Sayfalı liste

Çoğu liste endpoint’i sayfalı yanıt verir. Bu yanıtta success anahtarı yoktur; gövde data, links ve meta olmak üzere üç bölümden oluşur.

Anahtar	İçerik
`data`	Kaynak nesnelerinin dizisi.
`links`	`first`, `last`, `prev`, `next`. Mutlak URL’dir; ilgili sayfa yoksa `null` olur.
`meta`	`current_page`, `from`, `last_page`, `path`, `per_page`, `to`, `total`, `links[]` (`url`, `label`, `active`) ve klinik bağlamında `timezone`.

{
  "data": [{ "id": 7, "name": "VIP" }],
  "links": {
    "first": "https://app.flextell.ai/api/v1/tags?page=1",
    "last": "https://app.flextell.ai/api/v1/tags?page=3",
    "prev": null,
    "next": "https://app.flextell.ai/api/v1/tags?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://app.flextell.ai/api/v1/tags",
    "per_page": 15,
    "to": 15,
    "total": 42,
    "timezone": "Europe/Istanbul"
  }
}

links.first, links.last, links.prev ve links.next yalnızca ?page=N içerir. Filtrelerinizi, per_page ve sıralama parametrelerinizi sonraki sayfa isteklerinde kendiniz yeniden göndermelisiniz.

Sayfa numarası aralığın dışındaysa data boş dizi olur ve meta geçerli kalır. Sayfa boyutu, sınırlar ve sayfalama kuralları için Sayfalama, filtre ve sıralama için Filtreleme ve sıralama sayfalarına bakın.

Sayfasız koleksiyon

Bazı listeler sayfalanmaz ve tüm kayıtları tek yanıtta verir. Gövde data dizisi ile klinik bağlamında meta.timezone içerir; success ve links yoktur.

{ "data": [], "meta": { "timezone": "Europe/Istanbul" } }

Sayfasız koleksiyon döndüren endpoint’lerden bazıları:

GET /v1/channels
GET /v1/integrations
GET /v1/pipelines/{id}/stages
GET /v1/oauth/scopes
GET /v1/billing/quota-packages
GET /v1/billing/payment-providers
GET /v1/channels/whatsapp/history-syncs

Bir liste endpoint’inin sayfalı olup olmadığını varsayımla değil, API Referansı’ndaki yanıt şemasına bakarak belirleyin. Bazı sayfalı endpoint’ler OpenAPI belgesinde yalnızca data içeren yanıt olarak görünebilir; gerçek yanıt links ve meta de taşır.

Toplu işlem sonucu

Toplu endpoint’ler, kayıtların bir kısmı başarısız olsa bile 200 döndürür. Hangi kaydın neden başarısız olduğunu data.results içinden okuyun. Bu davranışa sahip endpoint’ler:

POST /v1/appointment-reminders/bulk/approve
POST /v1/appointment-reminders/bulk/reject
POST /v1/appointment-reminders/bulk/retry
POST /v1/appointment-reminders/bulk/send
POST /v1/appointment-reminders/bulk/delete
POST /v1/leads/bulk-delete

{
  "success": true,
  "data": {
    "success_count": 1,
    "failed_count": 1,
    "results": [
      { "id": 101, "success": true },
      {
        "id": 102,
        "success": false,
        "error_code": "RESOURCE_NOT_FOUND",
        "message": "<yerelleştirilmiş mesaj>"
      }
    ]
  },
  "meta": { "timezone": "Europe/Istanbul" }
}

Alan	Açıklama
`success_count`, `failed_count`	Başarılı ve başarısız kayıt sayısı.
`results[]`	Gönderdiğiniz her kayıt için bir sonuç. Her sonuçta `success` bulunur.
`results[].error_code`, `results[].message`	Yalnızca başarısız kayıtlarda gelir.

Sonuçtaki kayıt kimliği anahtarı endpoint’e göre değişir: hatırlatma işlemlerinde id, Lead toplu silmede lead_id. Sık görülen kayıt bazlı hata kodları:

Kod	Ne zaman
`RESOURCE_NOT_FOUND`	Kimlik bulunamadı.
`CUSTOMER_ERASED`	Hastanın verisi imha edilmiş.
`LEAD_NOT_ASSIGNED`	Lead size atanmamış ve erişiminiz kısıtlı.

Boş ve eksik alanlar

Kaynak nesnelerindeki anahtarlar çoğunlukla her zaman bulunur. Değeri yoksa null döner, örneğin deleted_at: null.
İlişki alanları (örneğin bir randevunun doktoru) yalnızca endpoint o ilişkiyi yüklediyse gelir. Anahtar yoksa “değer null” diye yorumlamayın; o endpoint ilişkiyi hiç döndürmüyordur.
Hata zarfında errors ve data anahtarları, taşıyacak içerik yoksa null gönderilmez, hiç gelmez.
Toplu işlem sonuçlarında boş error_code ve message alanları da yanıttan çıkarılır.
Boş bir nesne bazı alanlarda {} yerine [] olarak gelebilir (örneğin relation_summary: []). Bu alanları okuyan kodunuz her iki biçimi de kabul etmelidir.
Gelen isteklerde boş metin değerleri null olarak, metinler de kırpılmış olarak işlenir. Ayrıntı için Veri biçimleri sayfasına bakın.

Bir Lead size atanmadıysa, o Lead’e bağlı gömülü hasta nesnesi maskelenmiş gelir: ad ve soyad sözcük başına ilk 2 harf ile • olarak, telefon ve e-posta kısmen gizli, date_of_birth ise null olur. Nesne is_masked: true taşır. Ayrıntılar için İzinler ve görünürlük sayfasına bakın.

İstisnalar

Aşağıdaki durumlar yukarıdaki üç biçime uymaz.

Zarflı liste. Birkaç liste endpoint’i sayfalı biçim yerine success ve data zarfını kullanır. GET /v1/general/global-search bunlardan biridir ve data içinde { "customers": [...], "leads": [...] } döndürür. Aynı biçimi kullanan diğer endpoint’ler: GET /v1/account-transaction-types, GET /v1/payment-methods, GET /v1/integration-entities, GET /v1/permissions.
Hepsi ya da hiçbiri. Hesap hareketlerinin toplu silinmesi (POST /v1/bank-accounts/{accountId}/transactions/bulk-delete) kayıt bazlı sonuç vermez. Başarılıysa data: { "deleted_count": 2 } döner. Seçilenlerden biri silinemiyorsa hiçbir hareket silinmez ve 422 ACCOUNT_TRANSACTION_NOT_DELETABLE hatası gelir.
JSON olmayan yanıtlar. Dosya, ZIP, PDF ve XML indirmeleri Content-Disposition başlığıyla, sohbet dışa aktarımı CSV olarak, Flexy sohbet akışı ise text/event-stream olarak döner.
Hata yanıtları. success: false, error_code ve message içeren ayrı bir zarf kullanır. Bkz. Hata yanıtları ve Hata kodları.

Silinen kayıtların nasıl saklandığı ve geri alındığı Silme ve yaşam döngüsü sayfasında anlatılır.

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

Tekil kaynak yanıtı

Sayfalı liste

Sayfasız koleksiyon

Toplu işlem sonucu

Boş ve eksik alanlar

İstisnalar

​Tekil kaynak yanıtı

​Sayfalı liste

​Sayfasız koleksiyon

​Toplu işlem sonucu

​Boş ve eksik alanlar

​İstisnalar

Tekil kaynak yanıtı

Sayfalı liste

Sayfasız koleksiyon

Toplu işlem sonucu

Boş ve eksik alanlar

İstisnalar