Meslekler ve etiketler

Etiketler ve meslekler, kliniğinizin hasta kayıtlarını sınıflandırmak için kullandığı iki küçük liste kaynağıdır. Etiket, renkli bir işarettir ve hastalara, randevulara ve sohbetlere atanabilir. Meslek ise hasta kaydındaki Meslek alanının seçenek listesidir. Her iki kaynak da klinik bazlıdır: X-Tenant başlığıyla hangi kliniğin listesini yönettiğinizi belirtirsiniz (bkz. Klinikler ve X-Tenant). Panelde aynı listeler Hastalar → Etiketler ve Hastalar → Meslekler altında yönetilir; bkz. Etiketler ve Meslekler.

Endpoint özeti

Tüm yollar https://app.flextell.ai/api/v1 altındadır.

Metot	Endpoint	Açıklama	Scope	İzin
`GET`	`/tags`	Etiketleri listeler	`tags:read`	`View:Tag`
`POST`	`/tags`	Etiket oluşturur	`tags:write`	`Create:Tag`
`GET`	`/tags/{id}`	Tek etiketi getirir	`tags:read`	`View:Tag`
`PUT`	`/tags/{id}`	Etiketi günceller	`tags:write`	`Update:Tag`
`DELETE`	`/tags/{id}`	Etiketi siler	`tags:write`	`Delete:Tag`
`GET`	`/occupations`	Sistem kataloğunu ve kliniğin kendi mesleklerini listeler	`occupations:read`	`View:Occupation`
`POST`	`/occupations`	Meslek oluşturur	`occupations:write`	`Create:Occupation`
`GET`	`/occupations/{id}`	Tek mesleği getirir	`occupations:read`	`View:Occupation`
`PUT`	`/occupations/{id}`	Mesleği günceller	`occupations:write`	`Update:Occupation`
`DELETE`	`/occupations/{id}`	Mesleği siler	`occupations:write`	`Delete:Occupation`

İzin etiketleri rol editöründe Etiketler ve Meslekler gruplarında; Görüntüle, Oluştur, Güncelle ve Sil olarak görünür. Scope ve izin ayrımı için bkz. Scope’lar ve İzinler ve görünürlük.

Etiket uçları kurulum tamamlanmadan 428 SETUP_REQUIRED döner. Meslek uçları kurulum sırasında da çalışır. Ayrıntı için bkz. Erişim kilitleri.

Etiketler

Nesne modeli

Alan	Tür	Açıklama
`id`	integer	Etiket kimliği.
`tenant_id`	integer	Etiketin ait olduğu klinik.
`name`	string	Etiket adı. En çok 255 karakter. Kliniğinizde silinmemiş etiketler arasında benzersiz olmalıdır.
`color`	string	`#RRGGBB` biçiminde renk, örneğin `#6b7280`.
`created_at`, `updated_at`, `deleted_at`	string \| null	ISO 8601 zaman damgaları.

Etiket nesnesi hasta sayısı (customers_count) içermez.

Listeleme

Parametre	Açıklama
`search`	Ada göre arama, en çok 255 karakter. Arama varsa sonuçlar önce eşleşme sırasına, sonra `sort_by` değerine göre sıralanır.
`per_page`	Sayfa başına kayıt, 1–100 arası. Varsayılan 15.
`page`	Sayfa numarası.
`sort_by`	`name`, `created_at` veya `updated_at`. Varsayılan `created_at`.
`sort_order`	`asc` veya `desc`. Varsayılan `desc`.

Sayfalama ve sıralama kuralları için bkz. Sayfalama ve Filtreleme ve sıralama.

Oluşturma ve güncelleme

POST /tags için name ve color zorunludur. PUT /tags/{id} kısmi güncelleme kabul eder; yalnızca değiştirmek istediğiniz alanı gönderin.

Alan	Zorunlu	Kural
`name`	Oluştururken evet	En çok 255 karakter. Kliniğinizde silinmemiş başka bir etiketle aynı olamaz. Başka bir klinikte aynı ad kullanılabilir.
`color`	Oluştururken evet	`^#[0-9A-Fa-f]{6}$` desenine uymalıdır. `red`, `#fff` ve `ABCDEF` reddedilir.

Kurala uymayan istek 422 VALIDATION_FAILED döner; hata ilgili alan adıyla (name, color) gelir.

Etiketi kayda bağlama

Etiketler kendi uçlarından değil, bağlanacakları kaynağın uçlarından atanır.

Hedef	Nasıl
Hasta	`PUT /customers/{id}` gövdesinde `tags` dizisi (etiket kimlikleri). Dizi mevcut etiket kümesinin tamamını değiştirir; boş dizi etiketleri temizler; alanı hiç göndermezseniz etiketler değişmez. Başka kliniğe ait bir kimlik `422` döner.
Hasta listesi	`GET /customers?tags[]=1&tags[]=2` bu etiketlerden herhangi birini taşıyan hastaları getirir.
Sohbet	`PUT /conversations/{id}/tags`. Bkz. Sohbetler.

Hasta alanları için bkz. Hastalar.

Meslekler

Nesne modeli

Alan	Tür	Açıklama
`id`	integer	Meslek kimliği.
`tenant_id`	integer \| null	Sistem kataloğundaki kayıtlarda `null`; kliniğe ait kayıtlarda klinik kimliği.
`name`	string	Meslek adı. Her zaman büyük harfle saklanır (aşağıya bakın).
`is_global`	boolean	`true` ise kayıt tüm kliniklerde görünen sistem kataloğundandır ve salt okunurdur.
`is_active`	boolean	Hasta kaydında seçilebilir mi. Varsayılan `true`.
`customers_count`	integer	Yalnızca listede gelir. Kliniğinizin silinmemiş hastalarından bu mesleği taşıyanların sayısı.
`created_at`, `updated_at`, `deleted_at`	string \| null	ISO 8601 zaman damgaları.

Meslek adları yazarken Türkçe kurallarla büyük harfe çevrilir (i → İ, ı → I). Diş Hekimi olarak gönderirseniz DİŞ HEKİMİ olarak saklanır ve öyle döner. Arama terimi de aynı şekilde normalleştirilir; arama yaparken büyük/küçük harfe dikkat etmeniz gerekmez.

Listeleme

GET /occupations sistem kataloğunu ve kliniğin kendi mesleklerini birlikte döndürür. Hangisini istediğinizi is_global ile seçin.

Parametre	Açıklama
`search`	Ada göre arama.
`is_active`	`true` veya `false`. Aktif ya da pasif meslekleri süzer.
`is_global`	`true` yalnızca sistem kataloğunu, `false` yalnızca kliniğin kendi mesleklerini getirir.
`created_at_from`, `created_at_to`	Oluşturulma tarihi aralığı. Tarihler kliniğin saat dilimine göre gün başı ve gün sonu olarak okunur.
`per_page`, `page`	Sayfalama. `per_page` 1–100 arası, varsayılan 15.
`sort_by`	`name`, `customers_count`, `created_at` veya `updated_at`. Varsayılan `name`.
`sort_order`	`asc` veya `desc`. Varsayılan `asc`.

Oluşturma ve güncelleme

Alan	Zorunlu	Kural
`name`	Oluştururken evet	En çok 255 karakter. Büyük harfe çevrildikten sonra kliniğinizdeki diğer mesleklerle aynı olamaz (büyük/küçük harf farkı sayılmaz).
`is_active`	Hayır	Varsayılan `true`. Mesleği listeden kaldırmadan seçilemez yapmak için `false` gönderin.

Meslekle hasta kaydı

Hasta oluştururken ya da güncellerken occupation_id gönderin. Meslek aktif ve silinmemiş olmalı; sistem kataloğundan ya da kliniğinizin kendi mesleklerinden biri olmalıdır. Aksi hâlde 422 döner. Hasta yanıtında occupation_id ile birlikte büyük harfli occupation_name gelir. Hastaları meslekle süzmek için GET /customers?occupation_id=... kullanın.

Silme kuralları

	Etiket	Meslek
Silme türü	Yumuşak silme. Kayıt listelerden ve `GET` uçlarından kalkar; `404` döner.	Yumuşak silme. Aynı davranış.
Geri alma	Yok. API’de geri yükleme veya kalıcı silme ucu yoktur.	Yok.
Geri Dönüşüm Kutusu	Etiketler Geri Dönüşüm Kutusu’nda görünmez.	Meslekler Geri Dönüşüm Kutusu’nda görünmez.
Silinebilen kayıtlar	Kliniğinizin tüm etiketleri.	Yalnızca kliniğin kendi meslekleri. Sistem kataloğundaki (`is_global: true`) kayıtları silemez ve güncelleyemezsiniz; bu uçlar `404 RESOURCE_NOT_FOUND` döner.
Başarılı yanıt	`200`, `Etiket başarıyla silindi`	`200`, `Meslek başarıyla silindi`

Silinen etiket ve meslek API’den geri getirilemez. Mesleği yalnızca seçim listesinden çıkarmak istiyorsanız silmek yerine PUT /occupations/{id} ile is_active değerini false yapın.

Genel silme davranışı için bkz. Silme ve yaşam döngüsü.

Hata kodları

Kod	HTTP	Ne zaman
`UNAUTHENTICATED`	401	Token eksik ya da geçersiz.
`FORBIDDEN`	403	Token’da scope ya da kullanıcıda izin yok.
`TENANT_HEADER_REQUIRED`	400	`X-Tenant` başlığı gönderilmedi.
`TENANT_NOT_FOUND`	404	Klinik bulunamadı ya da kullanıcı o kliniğin üyesi değil.
`RESOURCE_NOT_FOUND`	404	Kayıt yok, silinmiş, başka kliniğe ait ya da (meslekte) sistem kataloğunda. Mesaj: `Etiket bulunamadı` / `Meslek bulunamadı`.
`VALIDATION_FAILED`	422	Ad tekrarlanıyor, `color` biçimi geçersiz ya da zorunlu alan eksik.
`SETUP_REQUIRED`	428	Klinik kurulumu tamamlanmadan etiket ucu çağrıldı.

Tüm hata kodları için bkz. Hata kodları.

Örnekler

curl "https://app.flextell.ai/api/v1/tags?search=vip&sort_by=name&sort_order=asc" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

curl -X POST "https://app.flextell.ai/api/v1/tags" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{"name": "VIP", "color": "#6b7280"}'

curl -X POST "https://app.flextell.ai/api/v1/occupations" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Diş Hekimi", "is_active": true}'

curl -X PUT "https://app.flextell.ai/api/v1/occupations/123" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

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

Etiket oluşturma yanıtı (201) şu alanları taşır:

{
  "success": true,
  "data": {
    "id": 123,
    "tenant_id": 45,
    "name": "VIP",
    "color": "#6b7280",
    "created_at": "2026-10-12T14:30:00+03:00",
    "updated_at": "2026-10-12T14:30:00+03:00",
    "deleted_at": null
  }
}

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

Meslekler ve etiketler

Endpoint özeti

Etiketler

Nesne modeli

Listeleme

Oluşturma ve güncelleme

Etiketi kayda bağlama

Meslekler

Nesne modeli

Listeleme

Oluşturma ve güncelleme

Meslekle hasta kaydı

Silme kuralları

Hata kodları

Örnekler

​Endpoint özeti

​Etiketler

​Nesne modeli

​Listeleme

​Oluşturma ve güncelleme

​Etiketi kayda bağlama

​Meslekler

​Nesne modeli

​Listeleme

​Oluşturma ve güncelleme

​Meslekle hasta kaydı

​Silme kuralları

​Hata kodları

​Örnekler

Endpoint özeti

Etiketler

Nesne modeli

Listeleme

Oluşturma ve güncelleme

Etiketi kayda bağlama

Meslekler

Nesne modeli

Listeleme

Oluşturma ve güncelleme

Meslekle hasta kaydı

Silme kuralları

Hata kodları

Örnekler