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

# Potansiyel Müşteriler API

> Kliniğe ilgi gösteren potansiyel müşterileri ve lead statülerini yönetmek, müşteriye dönüştürmek için endpoint'ler.

<Note>
  Tüm isteklerde `X-Tenant` header'ı **zorunludur**. İşlemler yalnızca belirtilen tenant'a ait lead kayıtları ile sınırlandırılmıştır.
</Note>

## Endpoint özeti

### Lead statüleri

| Metot    | Endpoint                      | Açıklama                                   |
| -------- | ----------------------------- | ------------------------------------------ |
| `GET`    | `/api/v1/leads/statuses`      | Tenant'a ait tüm lead statülerini listeler |
| `POST`   | `/api/v1/leads/statuses`      | Yeni lead statüsü oluşturur                |
| `PUT`    | `/api/v1/leads/statuses/{id}` | Lead statüsünü günceller                   |
| `DELETE` | `/api/v1/leads/statuses/{id}` | Lead statüsünü siler                       |

### Lead CRUD

| Metot    | Endpoint                     | Açıklama                           |
| -------- | ---------------------------- | ---------------------------------- |
| `GET`    | `/api/v1/leads`              | Lead'leri filtreli olarak listeler |
| `GET`    | `/api/v1/leads/{id}`         | Tek bir lead'i detaylı getirir     |
| `POST`   | `/api/v1/leads`              | Yeni lead oluşturur                |
| `PUT`    | `/api/v1/leads/{id}`         | Lead'i kısmi günceller             |
| `DELETE` | `/api/v1/leads/{id}`         | Lead'i siler                       |
| `POST`   | `/api/v1/leads/{id}/convert` | Lead'i müşteriye dönüştürür        |

<Tip>
  Tüm parametreler, alanlar ve örnek istek/yanıtlar için **[API Referansı](/api-reference)** sekmesine bakın.
</Tip>

## Lead kavramı

Lead, kliniğe ilgi gösteren ancak henüz hasta kaydı oluşturulmamış **potansiyel müşteriyi** temsil eder. Bir lead; iletişim bilgileri, kaynak, atanmış kullanıcı, statü ve dönüşüm durumu ile yönetilir.

Lead statüleri tenant bazında özelleştirilebilir. Her statü; renk, sıralama, varsayılan (`is_default`) ve terminal (`is_terminal`) işaretleri ile yapılandırılabilir.

## İş kuralları

<Note>
  **`phone_number` normalizasyonu:** Girilen telefon numarası sistem tarafından otomatik olarak normalize edilir. Tenant içinde benzersiz olmalıdır.
</Note>

<Warning>
  **Statü benzersizliği:** `POST /leads/statuses` ile oluşturulan statü adı (`name`) tenant içinde **benzersiz** olmalıdır.
</Warning>

<Note>
  **`is_terminal`:** Terminal olarak işaretlenen statüler lead akışının son adımını temsil eder (örn. "Kaybedildi", "Dönüştürüldü").
</Note>

## Lead → Müşteri dönüşümü (`POST /leads/{id}/convert`)

<Tip>
  `existing_customer_id` gönderilirse lead **mevcut bir müşteriyle** ilişkilendirilir; gönderilmezse sistem otomatik olarak **yeni bir müşteri kaydı** oluşturur.
</Tip>

Yanıt `{ result, customer, lead }` yapısında döner.

## Yetkilendirme

### Uygulama izinleri (permissions)

| İşlem                | Permission     |
| -------------------- | -------------- |
| Listeleme            | `ViewAny:Lead` |
| Detay / Tek gösterme | `View:Lead`    |
| Oluşturma            | `Create:Lead`  |
| Güncelleme           | `Update:Lead`  |
| Silme                | `Delete:Lead`  |

### Token scope'ları (Passport)

| İşlem                                                           | Scope         |
| --------------------------------------------------------------- | ------------- |
| Okuma (`index`, `show`, `statuses`)                             | `leads:read`  |
| Yazma (`store`, `update`, `destroy`, `convert`, statü yönetimi) | `leads:write` |