> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Meslekler ve etiketler

> Meslek ve etiket listelerini API ile yönetmeyi anlatır.

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](/api/klinikler-ve-x-tenant)). Panelde aynı listeler **Hastalar → Etiketler** ve **Hastalar → Meslekler** altında yönetilir; bkz. [Etiketler](/panel/hastalar/etiketler) ve [Meslekler](/panel/hastalar/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](/api/kimlik-dogrulama/scopelar) ve [İzinler ve görünürlük](/api/izinler-ve-gorunurluk).

<Note>
  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](/api/istekler/erisim-kilitleri).
</Note>

## 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](/api/istekler/sayfalama) ve [Filtreleme ve sıralama](/api/istekler/filtreleme-ve-siralama).

### 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](/api/kaynaklar/sohbetler). |

Hasta alanları için bkz. [Hastalar](/api/kaynaklar/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ı. |

<Info>
  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.
</Info>

### 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` |

<Warning>
  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.
</Warning>

Genel silme davranışı için bkz. [Silme ve yaşam döngüsü](/api/istekler/silme-yasam-dongusu).

## 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ı](/api/istekler/hata-kodlari).

## Örnekler

<CodeGroup>
  ```bash Etiketleri listele theme={null}
  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>"
  ```

  ```bash Etiket oluştur theme={null}
  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"}'
  ```

  ```bash Meslek oluştur theme={null}
  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}'
  ```

  ```bash Mesleği pasife al theme={null}
  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}'
  ```

  ```bash Etiket sil theme={null}
  curl -X DELETE "https://app.flextell.ai/api/v1/tags/123" \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Tenant: <tenant_id>"
  ```
</CodeGroup>

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

```json theme={null}
{
  "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
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.