Destek talepleri

/v1/tickets kaynağı Destek Talebi kayıtlarını yönetir. Destek Talebi, bir Hasta için açılan şikayet, yan etki bildirimi, istek veya öneridir ve kliniğin takip etmesi gereken bir iş kalemidir. Her talebin bir türü, dört adımlı bir durumu, serbest metin açıklaması ve isteğe bağlı bir sorumlu personeli vardır. Talepler iki yoldan açılır. Hastayla WhatsApp’ta konuşan AI asistan talep açar (creation_type: ai_generated). Personel panelden, mobil uygulamadan veya API üzerinden talep açar (creation_type: manuel). Panelde aynı ekran için Destek talepleri, mobilde Destek talepleri sayfasına bakın.

Bu kaynak, kliniğin Flextell’e ilettiği Sorun Bildirimleri’nden farklıdır. Onlar için Sorun bildirimleri sayfasına bakın.

Endpoint özeti

Tüm isteklerde Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> başlıkları gerekir. Scope’ların anlamı için Scope’lar, izin ve görünürlük kuralları için İzinler ve görünürlük sayfasına bakın.

Metot	Endpoint	Açıklama	Scope	İzin
GET	`/v1/tickets`	Talepleri listeler.	`tickets:read`	`View:Ticket`
POST	`/v1/tickets`	Talep oluşturur.	`tickets:write`	`Create:Ticket`
GET	`/v1/tickets/{id}`	Tek talebi getirir.	`tickets:read`	`View:Ticket`
PUT	`/v1/tickets/{id}`	Talebi kısmi olarak günceller.	`tickets:write`	`Update:Ticket`
DELETE	`/v1/tickets/{id}`	Talebi siler.	`tickets:write`	`Delete:Ticket`

Kaynakta başka endpoint yoktur. Toplu işlem, kalıcı silme veya geri yükleme endpoint’i bulunmaz. Rol editöründe izinler Destek Talepleri grubunda görünür.

İzin	Rol editöründeki etiket	Ne açar
`View:Ticket`	Görüntüle	Listeleme ve tek talep. Tek başına yalnızca size atanmış lead’lerin hastalarına ait talepleri gösterir.
`ViewAllTickets:Ticket`	Tümünü Görüntüle	Kliniğin tüm taleplerini görme.
`Create:Ticket`	Oluştur	`POST`.
`Update:Ticket`	Güncelle	`PUT`.
`Delete:Ticket`	Sil	`DELETE`.

tickets:read scope’u olan bir token POST, PUT ve DELETE çağıramaz; bu istekler 403 döner.

Görünürlük

ViewAllTickets:Ticket iznine sahip olmayan bir kullanıcı yalnızca hastasının lead’i kendisine atanmış talepleri görür. Görünmeyen talepler listede yer almaz, tek talep isteğinde 404 döner. Lead’i olmayan bir hastanın talebi, bu izne sahip olmayan kullanıcılara görünmez. Sorumlu personel (related_person) olmak tek başına görünürlük sağlamaz.

Nesne modeli

Tüm endpoint’ler aynı talep nesnesini döner.

Alan	Tür	Açıklama
`id`	sayı	Talep kimliği.
`code`	metin	`TKT-` ile başlayan benzersiz kod. Sunucu üretir, istemci belirleyemez.
`description`	metin	Talep açıklaması. En çok 5000 karakter.
`status`	metin	`open`, `processing`, `resolved` veya `closed`.
`type`	metin veya `null`	`general`, `complaint`, `side_effect`, `request` veya `suggestion`.
`creation_type`	metin	`manuel` (personel veya API) ya da `ai_generated` (AI asistan).
`position`	metin veya `null`	Kanban sıralama işareti. En çok 255 karakter. Yalnızca güncellemede gönderilebilir.
`customer`	nesne	Hasta: `id`, `first_name`, `last_name`, `phone_number`, `email`, `is_masked`, `is_lead_stage`, `lead_id`, `record_state`.
`related_person`	nesne veya `null`	Sorumlu personel: `id`, `name`. Atanmamışsa `null`.
`record_state`	nesne	`is_read_only` ve `reason_code`. Salt okunur kayıtlarda `CUSTOMER_ERASED` veya `LEAD_NOT_ASSIGNED`.
`created_at`, `updated_at`, `deleted_at`	tarih	Zaman damgaları. Silinmiş talepler listelenmediği için `deleted_at` pratikte `null` gelir.

Hasta ve lead alanlarının ayrıntısı için Hastalar ve Lead’ler sayfalarına bakın.

related_person bir sorumlu (muhatap) belirtir, sahip değildir. Talebe atanmak talebi görme yetkisi vermez.

Satış Temsilcisi rolündeki ve ViewAllLeads:Lead izni olmayan bir kullanıcı, başka bir temsilcinin lead aşamasındaki hastasını maskeli görür (is_masked: true) ve kaydı salt okunur bulur.

Durumlar ve türler

Talebin bir öncelik alanı yoktur. Durum ve tür değerleri aşağıdadır. Etiketler panelde görünen etiketlerdir.

Durumlar

`status`	Panel etiketi	Anlam
`open`	Açık	Yeni talep, işlem bekliyor.
`processing`	İşlemde	Klinik ekibi talebi inceliyor.
`resolved`	Çözüldü	Talep çözüldü. Hastaya mesaj gidebilir.
`closed`	Kapalı	Talep tamamlandı.

Sunucu bir durum makinesi uygulamaz. PUT ile dört değerden herhangi birine, herhangi bir durumdan geçebilirsiniz; geriye dönüş de serbesttir. status göndermezseniz yeni talep open olarak açılır.

Mobil uygulama processing durumunu İşleniyor olarak gösterir. API değerleri her istemcide aynıdır.

Türler

`type`	Panel etiketi
`general`	Genel
`complaint`	Şikayet
`side_effect`	Yan Etki
`request`	İstek
`suggestion`	Öneri

Mobil uygulama request türünü Talep olarak gösterir.

Çözüldü mesajı

Bir talep resolved durumuna geçtiğinde ve talebin sorumlu personeli varsa hastaya Destek Talebi Çözüldü şablonuyla bir mesaj gider. Mesaj hastanın kanalından iletilir. Sorumlusu olmayan bir talep resolved olursa mesaj gönderilmez. Şablon metnini Mesaj Şablonları sayfasından düzenleyebilirsiniz; ayrıntı için Mesaj şablonları sayfasına bakın.

Listeleme

GET /v1/tickets sayfalı bir liste döner. Genel kurallar için Sayfalama ve Filtreleme ve sıralama sayfalarına bakın. Bu kaynağa özgü parametreler:

Parametre	Açıklama
`status`	Durum filtresi.
`type`	Tür filtresi.
`customer_id`	Hastaya göre filtre.
`lead_id`	Lead’e göre filtre. Lead sizin için görünür ve klinikte olmalı; aksi hâlde 422 döner. Hastası olmayan bir lead boş liste verir.
`related_person_id`	Sorumlu personele göre filtre.
`created_at_from`, `created_at_to`	`YYYY-MM-DD` aralığı, uçlar dahil. Klinik saat dilimine göre yorumlanır. `created_at_to`, `created_at_from` değerinden önce olamaz.
`search`	En çok 255 karakter. Talep kodunda, açıklamada, hastanın adında, soyadında ve telefonunda arar. Her sözcük önek olarak eşleşir ve tüm sözcükler birlikte aranır.
`sort_by`	`code`, `status`, `type`, `created_at`, `updated_at`. Varsayılan `created_at`.
`sort_order`	`asc` veya `desc`. Varsayılan `desc`.
`per_page`	1 ile 100 arası. Varsayılan 15.

Filtreler birlikte uygulanır. Silinmiş talepler hiçbir zaman listelenmez; trashed parametresi yok sayılır.

Hastanın adını sonradan değiştirdiyseniz, eski taleplerde arama yeni ada ancak talep bir sonraki güncellemede kaydedildikten sonra eşleşir.

Oluşturma

POST /v1/tickets isteği hastayı customer_id veya lead_id ile belirtir. İkisini birlikte göndermek 422 döner. lead_id gönderirseniz talep, lead’in hasta kaydına bağlanır; lead’in hasta kaydı yoksa Flextell oluşturur.

integer

Hasta kimliği. Klinikte olmalıdır. lead_id ile birlikte gönderilemez.

integer

Lead kimliği. Klinikte ve sizin için görünür olmalıdır. customer_id ile birlikte gönderilemez.

string

gerekli

Talep açıklaması. En çok 5000 karakter.

string

gerekli

general, complaint, side_effect, request veya suggestion.

string

varsayılan:"open"

open, processing, resolved veya closed.

Sorumlu personel. Klinikteki herhangi bir kullanıcı olabilir. Göndermezseniz sunucu atama yapar (aşağıya bakın).

curl -X POST "https://app.flextell.ai/api/v1/tickets" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 123,
    "type": "complaint",
    "description": "Ayşe Yılmaz, randevu saatinde beklediğini bildirdi."
  }'

const res = await fetch("https://app.flextell.ai/api/v1/tickets", {
  method: "POST",
  headers: {
    Authorization: "Bearer <access_token>",
    "X-Tenant": "<tenant_id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_id: 123,
    type: "complaint",
    description: "Ayşe Yılmaz, randevu saatinde beklediğini bildirdi.",
  }),
});
const { data } = await res.json();

Başarılı istek 201 ve talep nesnesini döner. Yanıt örneği:

{
  "success": true,
  "data": {
    "id": 456,
    "code": "TKT-XXXXXXXXXX",
    "description": "Ayşe Yılmaz, randevu saatinde beklediğini bildirdi.",
    "status": "open",
    "type": "complaint",
    "creation_type": "manuel",
    "related_person": { "id": 12, "name": "Örnek Asistan" }
  }
}

Otomatik atama

related_person_id göndermezseniz sunucu, klinikteki aktif Asistan rolündeki kullanıcılar arasından kapalı olmayan (closed dışındaki) en az talebi olanı seçer. resolved talepler de sayılır. Eşitlikte seçim rastgeledir. Uygun asistan yoksa talep atanmamış kalır. Talep bir kullanıcıya atandığında o kullanıcıya Yeni Destek Talebi Oluşturuldu bildirimi gider. Atanmamış talep için bildirim gitmez.

Panel formu İlgili Personel alanını zorunlu tutar ve yalnızca aktif asistanları listeler. API bu alanı zorunlu tutmaz ve klinikteki herhangi bir kullanıcıyı kabul eder.

Güncelleme ve atama

PUT /v1/tickets/{id} kısmi güncellemedir. Yalnızca gönderdiğiniz alanlar değişir.

Alan	Kural
`description`	Gönderilirse boş olamaz. En çok 5000 karakter.
`status`	Dört değerden biri. Herhangi bir durumdan geçiş kabul edilir.
`type`	Beş değerden biri.
`related_person_id`	Klinikteki bir kullanıcı. `null` göndermek atamayı kaldırır.
`position`	`null` veya en çok 255 karakter.

customer_id güncellemeyle değişmez; gönderseniz de yok sayılır. Durumu değiştirme:

curl -X PUT "https://app.flextell.ai/api/v1/tickets/456" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "processing" }'

Başka bir personele atama:

curl -X PUT "https://app.flextell.ai/api/v1/tickets/456" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{ "related_person_id": 15 }'

Atamayı kaldırmak için { "related_person_id": null } gönderin.

Bildirimler

Değişiklik	Kim bilgilendirilir
Talep bir kullanıcıya atanır	Yeni sorumlu: Size Yeni Destek Talebi Atandı.
Talep başka birine atanır veya atama kaldırılır	Önceki sorumlu: Destek Talebi Başka Birine Atandı.
Durum değişir	Sorumlu personel. Değişikliği yapan kişi sorumlunun kendisiyse bildirim gitmez.
Durum `resolved` olur	Sorumlu personel varsa hasta, Destek Talebi Çözüldü mesajını alır.

Kullanıcılar bildirim türlerini bildirim tercihlerinden kapatabilir.

Silme

DELETE /v1/tickets/{id} talebi siler. Silinen talep Geri Dönüşüm Kutusu’na gider ve hiçbir listede görünmez. Bu kaynakta geri yükleme endpoint’i yoktur; geri yükleme Geri Dönüşüm Kutusu üzerinden yapılır. Ayrıntı için Silme yaşam döngüsü ve Geri Dönüşüm Kutusu sayfalarına bakın.

curl -X DELETE "https://app.flextell.ai/api/v1/tickets/456" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

Başarılı istek 200 döner:

{
  "success": true,
  "data": { "message": "Destek talebi başarıyla silindi" }
}

Hatalar

Genel hata biçimi için Hatalar ve Hata kodları sayfalarına bakın.

Kod	HTTP	Ne zaman
`UNAUTHENTICATED`	401	Token yok veya geçersiz.
`FORBIDDEN`	403	İlgili `Ticket` izni veya scope eksik.
`LEAD_NOT_ASSIGNED`	403	Maskeli, başka bir temsilcinin lead’ine ait hastanın talebinde oluşturma, güncelleme veya silme. Yanıtta `data.assigned_user` atanan kullanıcıyı (`id`, `name`) ya da `null` verir.
`RESOURCE_NOT_FOUND`	404	Talep yok, başka klinikte veya görünürlüğünüzün dışında.
`CUSTOMER_ERASED`	409	Hastanın verileri imha edilmiş. Talep salt okunurdur; oluşturma, güncelleme ve silme reddedilir.
`VALIDATION_FAILED`	422	Geçersiz `status` veya `type`, `per_page` 100’ü aşıyor, hasta veya kullanıcı klinikte değil, `customer_id` ile `lead_id` birlikte (ya da ikisi de yok), sayısal olmayan `{id}`.
`TENANT_HEADER_REQUIRED`	400	`X-Tenant` başlığı eksik.
`TENANT_NOT_FOUND`	404	Klinik bulunamadı.
`TOO_MANY_REQUESTS`	429	Oran sınırı aşıldı. Oran sınırları sayfasına bakın.

Hastanın verileri imha edilmişse talep okunabilir kalır ve record_state.is_read_only değeri true olur. İmha süreci için Veri imha talepleri sayfasına bakın.

Güncellemede kontrol sırası şöyledir: izin, doğrulama, kaydın görünürlüğü (404), imha edilmiş hasta (409), lead kilidi (403).

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

Görünürlük

Nesne modeli

Durumlar ve türler

Durumlar

Türler

Çözüldü mesajı

Listeleme

Oluşturma

Otomatik atama

Güncelleme ve atama

Bildirimler

Silme

Hatalar

​Endpoint özeti

​Görünürlük

​Nesne modeli

​Durumlar ve türler

​Durumlar

​Türler

​Çözüldü mesajı

​Listeleme

​Oluşturma

​Otomatik atama

​Güncelleme ve atama

​Bildirimler

​Silme

​Hatalar

Endpoint özeti

Görünürlük

Nesne modeli

Durumlar ve türler

Durumlar

Türler

Çözüldü mesajı

Listeleme

Oluşturma

Otomatik atama

Güncelleme ve atama

Bildirimler

Silme

Hatalar