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

# Satış temsilcileri

> Satış temsilcilerini, müsait olmama dönemlerini, uygunluğu ve temsilci metriklerini anlatır.

Satış temsilcisi, klinikte `salesperson` rolüne sahip bir kullanıcıdır. Lead'ler temsilcilere atanır; atamayı etkileyen üç şey temsilcinin kaydında tutulur: aktif lead limiti, haftalık çalışma saatleri ve müsait olmama dönemleri. Bu sayfa temsilcileri yönetmeyi, günlük uygunluk çizelgesini ve temsilci metriklerini anlatır. Lead'lerin kendisi için [Lead'ler](/api/kaynaklar/leadler) sayfasına bakın. Panelde aynı ekranlar için [Satış temsilcileri](/panel/satis-temsilcileri) kılavuzuna bakın.

<Info>
  Her istekte `Authorization: Bearer <access_token>` ve `X-Tenant: <tenant_id>` başlıkları gerekir. Ayrıntı: [Klinikler ve X-Tenant](/api/klinikler-ve-x-tenant).
</Info>

## Endpoint özeti

Taban adres `https://app.flextell.ai/api/v1`. Okuma uç noktaları `salespeople:read`, yazma uç noktaları `salespeople:write` scope'u ister. Scope'lar hakkında: [Scope'lar](/api/kimlik-dogrulama/scopelar).

| Metot | Endpoint | Açıklama | İzin |
| - | - | - | - |
| GET | `/salespeople` | Temsilcileri listeler | `View:Salesperson` |
| POST | `/salespeople` | Temsilci oluşturur | `Create:Salesperson` |
| GET | `/salespeople/availability` | Bir günün uygunluk çizelgesini döner | `View:Salesperson` |
| GET | `/salespeople/{id}` | Tek temsilci döner | `View:Salesperson` |
| PUT | `/salespeople/{id}` | Temsilciyi günceller | `Update:Salesperson` |
| DELETE | `/salespeople/{id}` | Temsilciyi siler | `Delete:Salesperson` |
| GET | `/salespeople/{id}/deletion-relations` | Silmenin neleri etkileyeceğini gösterir | `Delete:Salesperson` |
| GET | `/salespeople/{id}/metrics` | Temsilcinin performans metriklerini döner | `View:Salesperson` |
| GET | `/salespeople/{id}/unavailable-periods` | Müsait olmama dönemlerini listeler | `View:Salesperson` |
| POST | `/salespeople/{id}/unavailable-periods` | Dönem ekler | `CreateUnavailablePeriod:Salesperson` |
| PUT | `/salespeople/{id}/unavailable-periods/{periodId}` | Dönemi günceller | `Update:Salesperson` |
| DELETE | `/salespeople/{id}/unavailable-periods/{periodId}` | Dönemi siler | `Delete:Salesperson` |

Panelde bu izinler rol editöründe **Satış Temsilcileri** grubunda görünür: **Görüntüle**, **Oluştur**, **İzin Dönemi Ekle**, **Güncelle**, **Sil**. Varsayılan rollerde bu izinlerin hepsi satış direktörü rolündedir; `salesperson` rolünün bu izinleri yoktur. İzin modeli için [İzinler ve görünürlük](/api/izinler-ve-gorunurluk) sayfasına bakın.

<Note>
  Yalnızca bu klinikte `salesperson` rolüne sahip kullanıcılar temsilci sayılır. Başka bir kullanıcının ya da başka kliniğin temsilcisinin kimliğini verirseniz `404 RESOURCE_NOT_FOUND` (`Satış temsilcisi bulunamadı`) döner.
</Note>

## Nesne modeli

| Alan | Tür | Açıklama |
| - | - | - |
| `id` | integer | Kullanıcı kimliği |
| `name`, `email` | string | Ad ve e-posta |
| `phone` | string veya null | Telefon, en fazla 20 karakter |
| `language` | array veya null | `Turkish`, `English`, `Other` değerleri |
| `avatar_url` | string veya null | Profil fotoğrafı. Yanıtta geçici (yaklaşık 6 saat geçerli) bir URL döner |
| `is_active` | boolean | Aktif mi |
| `active_lead_cap` | integer veya null | Aynı anda tutulabilecek aktif lead sayısı, 0–100. `null` ise varsayılan 50 uygulanır |
| `is_lead_cap_unlimited` | boolean | `true` ise limit uygulanmaz |
| `sales_cap` | integer veya null | Geçerli limit. Sınırsızsa `null` |
| `active_lead_count` | sayı | Yalnızca bu kliniğin aktif lead'leri sayılır |
| `work_hours` | array | Haftalık çalışma saatleri (bkz. aşağıdaki bölüm) |
| `roles` | array | Temsilcinin rolleri |
| `treatments` | array | İlgilendiği tedaviler |
| `import_source` | object veya null | İçe aktarıldığı sistem. Yalnızca tek temsilci yanıtlarında bulunur |
| `created_at`, `updated_at`, `deleted_at` | datetime | Zaman damgaları |

### Listeleme

`GET /salespeople` sayfalanır (`per_page` 1–100, `page`). Sayfalama için [Sayfalama](/api/istekler/sayfalama) sayfasına bakın.

| Parametre | Açıklama |
| - | - |
| `search` | Ad ve e-posta üzerinde alt dize araması |
| `is_active` | `true` veya `false` |
| `created_at_from`, `created_at_to` | Oluşturulma aralığı. Günler klinik saat dilimine göre alınır |
| `sort_by` | `name`, `email`, `created_at`, `updated_at`. Varsayılan `created_at` |
| `sort_order` | `asc` veya `desc`. Varsayılan `desc` |

### Temsilci oluşturma ve güncelleme

| Alan | Zorunlu | Kural |
| - | - | - |
| `name` | Oluşturmada evet | En fazla 255 karakter |
| `email` | Oluşturmada evet | Silinmemiş kullanıcılar arasında tekil olmalıdır |
| `set_password`, `password`, `password_confirmation` | Hayır | Yalnızca oluşturmada. `set_password` `true` ise `password` zorunludur (en az 8 karakter, onaylı) |
| `phone`, `language`, `avatar_url`, `is_active` | Hayır | `avatar_url` en fazla 1000 karakter |
| `active_lead_cap`, `is_lead_cap_unlimited` | Hayır | `active_lead_cap` 0–100 |
| `treatment_ids` | Hayır | Klinikteki tedavi kimlikleri. Gönderirseniz temsilcinin tedavi listesini tamamen değiştirir |
| `work_hours` | Hayır | Tam 7 satır (bkz. aşağıdaki bölüm) |

Güncellemede alanların hepsi isteğe bağlıdır ve parola alanları yoktur; bu uç nokta parola değiştirmez. Oluşturma temsilciyi kliniğe ekler ve `salesperson` rolünü verir. `set_password` `true` değilse rastgele bir parola üretilir ve temsilciye parola belirleme bağlantısı e-postayla gider. E-posta gönderilemese bile istek başarısız olmaz.

Başarılı oluşturma `201` döner. Doğrulama hataları `422` döner.

<Warning>
  `DELETE /salespeople/{id}` kullanıcı hesabını siler ve bu, kullanıcının tüm kliniklerdeki hesabını etkiler; yalnızca bu klinikteki üyeliği kaldırmaz. Temsilcinin lead'leri silinmez, `assigned_user_id` aynı kalır. Silmeden önce `GET /salespeople/{id}/deletion-relations` ile bu kliniğe ait `Randevular`, `Asistan olduğu randevular`, `Satışlar` ve `Destek talepleri` sayılarına bakın. Bu kayıtlar silinmez, kullanıcıya bağlı kalır. Silinen kayıtların yaşam döngüsü için [Silme ve yaşam döngüsü](/api/istekler/silme-yasam-dongusu) sayfasına bakın.
</Warning>

## Çalışma saatleri

`work_hours` her zaman 7 satırdır, `monday` ile `sunday` arasında günün biri başına bir satır.

| Alan | Açıklama |
| - | - |
| `day` | `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday` |
| `enabled` | Zorunlu boolean. O gün çalışılıyor mu |
| `open`, `close` | `H:i` biçiminde (`09:00`). `enabled` `true` ise zorunludur. Gece penceresi (`22:00`–`06:00`) kabul edilir |
| `day_label` | Yanıtta Türkçe gün adı (`Pazartesi` … `Pazar`). İsteklerde gönderseniz de yok sayılır |

Temsilcinin kendi saatleri yoksa yanıt kliniğin çalışma saatlerini, onlar da yoksa varsayılanı döner (Pazartesi–Cuma 06:00–15:00, hafta sonu kapalı). Klinik saatleri için [Klinik ve genel](/api/kaynaklar/klinik-ve-genel) sayfasına bakın.

## Müsait olmama dönemleri

Müsait olmama dönemi, temsilcinin izinli, raporlu ya da toplantıda olduğu bir zaman aralığıdır. Dönem sürerken temsilciye otomatik lead ataması yapılmaz.

| Alan | Zorunlu | Kural |
| - | - | - |
| `starts_at` | Evet | Başlangıç anı. Ofsetli ISO 8601 gönderin (`2026-10-20T00:00:00+03:00`) |
| `ends_at` | Evet | Bitiş anı. `starts_at` değerinden önce olamaz |
| `reason` | Hayır | En fazla 255 karakter |

Yanıtta `id`, `user_id`, `starts_at`, `ends_at`, `reason`, `created_at`, `updated_at`, `deleted_at` alanları döner. Liste sayfalanmaz ve `starts_at` değerine göre yeniden eskiye sıralıdır. Yanıt `{ "success": true, "data": [...] }` biçimindedir.

* Dönem eklemek `CreateUnavailablePeriod:Salesperson` izni ister. Bu izin `Update:Salesperson` izninden ayrıdır.
* Güncelleme tam değiştirmedir: `starts_at`, `ends_at` ve `reason` yeniden gönderilir. `reason` gönderilmezse temizlenir.
* İstek gövdesindeki `tenant_id` ve `user_id` yok sayılır. Klinik ve kullanıcı sunucuda belirlenir.
* Dönem bulunamazsa `404` döner (`Müsait olunmayan dönem bulunamadı`).
* Silme başarılıysa `Müsait olunmayan dönem başarıyla silindi` mesajı döner.

```bash theme={null}
curl -X POST "https://app.flextell.ai/api/v1/salespeople/123/unavailable-periods" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "starts_at": "2026-10-20T00:00:00+03:00",
    "ends_at": "2026-10-24T23:59:00+03:00",
    "reason": "Yıllık izin"
  }'
```

## Uygunluk

`GET /salespeople/availability` kliniğin aktif temsilcilerinin tek bir güne ait çizelgesini döner. `date` parametresi `Y-m-d` biçimindedir ve klinik saat dilimine göre yorumlanır; verilmezse bugün alınır.

```bash theme={null}
curl -G "https://app.flextell.ai/api/v1/salespeople/availability" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  --data-urlencode "date=2026-10-21"
```

```json theme={null}
{
  "success": true,
  "data": {
    "date": "2026-10-21",
    "timezone": "Europe/Istanbul",
    "salespeople": [
      {
        "id": 123,
        "name": "Ayşe Yılmaz",
        "status": "unavailable",
        "work": { "start": 540, "end": 1080 },
        "unavailable_periods": [
          {
            "id": 45,
            "start": 0,
            "end": 1440,
            "all_day": true,
            "continues_before": true,
            "continues_after": true,
            "reason": "Yıllık izin"
          }
        ]
      }
    ]
  }
}
```

Dakika değerleri klinik saat diliminde gün başlangıcından (00:00) itibaren sayılır, yani 0–1440 arasındadır. Örnekte `540` saat 09:00'dır.

| `status` | Anlamı |
| - | - |
| `unavailable` | Müsait olmama dönemleri çalışma penceresinin tamamını kapsıyor |
| `partial` | Dönemler çalışma penceresinin bir kısmını kapsıyor |
| `off` | O gün için etkin bir çalışma penceresi yok. `work` değeri `null` olur |
| `available` | Çalışma penceresiyle çakışan dönem yok |

Liste `unavailable`, `partial`, `off`, `available` sırasıyla, aynı durumda ada göre sıralanır. Gün içine sığmayan dönemler o güne kırpılır. Tüm günü kapsayan dönemde `all_day` `true` olur. Önceki ya da sonraki güne uzanan dönemlerde `continues_before` ve `continues_after` `true` olur.

## Metrikler

`GET /salespeople/{id}/metrics` temsilciye bu klinikte atanmış lead'ler üzerinden performans özetini döner.

| Parametre | Açıklama |
| - | - |
| `period` | `last_7_days`, `last_30_days` (varsayılan), `last_90_days`, `this_year`, `all`, `custom` |
| `from`, `to` | `Y-m-d`, klinik saat diliminde, uçlar dahil. `custom` ile kullanılır; `to` değeri `from` değerinden önce olamaz. İkisinden biri verilmezse o uç sınırsız kalır |

```json theme={null}
{
  "success": true,
  "data": {
    "period": "last_30_days",
    "from": "2026-09-13",
    "to": null,
    "timezone": "Europe/Istanbul",
    "currency": "TRY",
    "active_leads": 18,
    "potential_value": 245000,
    "won": 6,
    "lost": 4,
    "win_rate": 60,
    "converted_count": 5,
    "converted_value": 180000
  }
}
```

| Alan | Açıklama |
| - | - |
| `active_leads`, `potential_value` | Şu anki anlık değer. Seçilen döneme bağlı değildir |
| `won`, `lost` | Dönem içinde kazanılan ve kaybedilen lead sayısı (`won_at` ve `lost_at` tarihine göre) |
| `win_rate` | `won / (won + lost) × 100`, en yakın tam sayıya yuvarlanır. Kazanılan ve kaybedilen yoksa `0` |
| `converted_count`, `converted_value` | Dönem içinde hastaya dönüşen lead sayısı ve değeri (`converted_at` tarihine göre) |
| `currency` | Tutarların para birimi: kliniğin ana para birimi. Lead'lerin kendi kurları çevrilerek toplanır |

Kayan dönemler, klinik saatine göre N gün öncesinin gün başlangıcından başlar ve üst sınırı yoktur. `this_year` 1 Ocak'tan, `all` en baştan başlar.

<Note>
  Metrikler lead görünürlüğüne göre daraltılmaz. Temsilciye atanmış tüm lead'ler sayılır.
</Note>

## Atamaya etkisi

Otomatik lead ataması şu temsilcileri atlar: şu anda müsait olmama dönemi süren, aktif lead limitine ulaşan ve (çalışma saatine göre atama modunda) çalışma saati dışında olan ya da lead'in ilk tedavisine bağlı olmayan temsilciler. Limit yalnızca otomatik atamayı engeller; elle atama yine yapılır ve yanıtta limitin aşıldığı bildirilir. Atama endpoint'leri için [Lead'ler](/api/kaynaklar/leadler) sayfasına bakın.

## İlgili sayfalar

<CardGroup cols={2}>
  <Card title="Lead'ler" icon="funnel" href="/api/kaynaklar/leadler">
    Lead atama ve aşama geçişleri.
  </Card>

  <Card title="Tedaviler" icon="stethoscope" href="/api/kaynaklar/tedaviler">
    Temsilcinin ilgilendiği tedaviler.
  </Card>

  <Card title="Kullanıcılar, roller, davetler" icon="users" href="/api/kaynaklar/kullanicilar-roller-davetler">
    Rol ve izin yönetimi.
  </Card>
</CardGroup>


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