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

# Pipeline'lar ve aşamalar

> Pipeline ve aşamaları oluşturmayı, sıralamayı, aktif etmeyi ve aşama silmeyi anlatır.

Pipeline, kliniğin Lead'leri hangi aşamalardan geçirdiğini tanımlar. Bu sayfa, pipeline ve aşamaları yöneten `/pipelines` endpoint'lerini anlatır. Lead'lerin kendisi için [Lead'ler](/api/kaynaklar/leadler) sayfasına bakın. Panelde aynı işlemler **Pipeline'lar** sayfasından yapılır; bkz. [Pipeline'lar](/panel/pipelinelar).

<Info>
  Her istekte `Authorization: Bearer <access_token>` ve `X-Tenant: <tenant_id>` başlıkları gerekir. Başlık için [Klinikler ve X-Tenant](/api/klinikler-ve-x-tenant), izin ve görünürlük kuralları için [İzinler ve görünürlük](/api/izinler-ve-gorunurluk) sayfasına bakın.
</Info>

## Endpoint özeti

Pipeline'ı okuyan endpoint'ler `pipelines:read`, değiştirenler `pipelines:write` scope'u ister. Scope'lar için [Scope'lar](/api/kimlik-dogrulama/scopelar) sayfasına bakın. Kullanıcının ayrıca tabloda yazılı izne sahip olması gerekir.

| Metot | Endpoint | Açıklama | Scope | İzin |
| - | - | - | - | - |
| `GET` | `/api/v1/pipelines` | Pipeline'ları listeler. | `pipelines:read` | `View:Pipeline` |
| `POST` | `/api/v1/pipelines` | Pipeline oluşturur. | `pipelines:write` | `Create:Pipeline` |
| `GET` | `/api/v1/pipelines/{id}` | Tek pipeline'ı aşamalarıyla getirir. | `pipelines:read` | `View:Pipeline` |
| `PUT` | `/api/v1/pipelines/{id}` | Pipeline adını günceller. | `pipelines:write` | `Update:Pipeline` |
| `DELETE` | `/api/v1/pipelines/{id}` | Pipeline'ı siler. | `pipelines:write` | `Delete:Pipeline` |
| `POST` | `/api/v1/pipelines/{id}/activate` | Pipeline'ı aktif eder. | `pipelines:write` | `Activate:Pipeline` |
| `GET` | `/api/v1/pipelines/{id}/stages` | Pipeline'ın aşamalarını listeler. | `pipelines:read` | `View:Pipeline` |
| `POST` | `/api/v1/pipelines/{id}/stages` | Özel aşama ekler. | `pipelines:write` | `Update:Pipeline` |
| `PUT` | `/api/v1/pipelines/{id}/stages/{stageId}` | Aşamanın adını veya rengini günceller. | `pipelines:write` | `Update:Pipeline` |
| `POST` | `/api/v1/pipelines/{id}/stages/reorder` | Özel aşamaları yeniden sıralar. | `pipelines:write` | `Update:Pipeline` |
| `DELETE` | `/api/v1/pipelines/{id}/stages/{stageId}` | Aşamayı siler. | `pipelines:write` | `Update:Pipeline` |

Listeleme endpoint'i şu sorgu parametrelerini alır. Sayfalama için [Sayfalama](/api/istekler/sayfalama) sayfasına bakın.

| Parametre | Açıklama |
| - | - |
| `is_active` | Aktif (`1`) veya pasif (`0`) pipeline'lara göre süzer. |
| `created_at_from`, `created_at_to` | Oluşturulma tarihi aralığı (klinik saat dilimi). |
| `per_page` | Sayfa başına kayıt, 1–100. |
| `page` | Sayfa numarası. |

Sonuçta aktif pipeline önce gelir, ardından pipeline'lar ada göre sıralanır.

## Nesne modeli

### Pipeline

| Alan | Tür | Açıklama |
| - | - | - |
| `id` | integer | Pipeline kimliği. |
| `tenant_id` | integer | Pipeline'ın ait olduğu klinik. |
| `name` | string | Pipeline adı. Kliniğin silinmemiş pipeline'ları arasında benzersizdir. |
| `is_active` | boolean | Kliniğin aktif pipeline'ı mı. |
| `stages` | array | Pipeline'ın aşamaları (aşağıdaki nesne). |
| `created_at`, `updated_at` | string | Oluşturulma ve güncellenme zamanı. |

### Aşama

| Alan | Tür | Açıklama |
| - | - | - |
| `id` | integer | Aşama kimliği. |
| `name` | string | Aşama adı. |
| `slug` | string | Addan otomatik üretilir; aynı pipeline içinde benzersizdir (çakışmada `-2`, `-3` eklenir). Yeniden adlandırmada değişmez. |
| `color` | string | Onaltılık renk kodu, örneğin `#3b82f6`. |
| `sort_order` | integer | Aşamanın pano sırası. |
| `is_won` | boolean | Kazanıldı aşaması. |
| `is_lost` | boolean | Kaybedildi aşaması. |
| `is_locked` | boolean | Kilitli aşama: giriş, kazanıldı ve kaybedildi aşamaları. |
| `requires_lost_reason` | boolean | Bu aşamaya taşırken kayıp nedeni zorunlu mu. |

`is_won`, `is_lost`, `is_locked` ve `requires_lost_reason` değerlerini API ile değiştiremezsiniz. İsteğe eklerseniz sunucu bu alanları yok sayar.

<Note>
  Her pipeline'da üç kilitli aşama bulunur: giriş aşaması, kazanıldı aşaması ve kaybedildi aşaması. Aradaki aşamalar özel aşamadır. Özel aşamalar her zaman giriş ile kazanıldı/kaybedildi aşamalarının arasında kalır.
</Note>

Yeni kliniklere `Varsayılan Pipeline` adlı pipeline şu aşamalarla gelir:

| Ad | Renk | Tür |
| - | - | - |
| `Yeni` | `#3b82f6` | Kilitli, giriş |
| `İletişim kuruldu` | `#8b5cf6` | Özel |
| `Cevap yok` | `#f59e0b` | Özel |
| `Detaylar Alındı` | `#10b981` | Özel |
| `Teklif Gönderildi` | `#6366f1` | Özel |
| `Kapandı – Kazanıldı` | `#16a34a` | Kilitli, kazanıldı |
| `Kapandı – Kaybedildi` | `#ef4444` | Kilitli, kaybedildi, kayıp nedeni zorunlu |

## Pipeline oluşturma

`POST /api/v1/pipelines` isteği yalnızca `name` alanını alır (zorunlu, en çok 255 karakter, kliniğinizde benzersiz). Yanıt `201` ile pipeline'ı ve üç kilitli aşamasını döner.

* Kliniğin aktif pipeline'ı yoksa yeni pipeline otomatik aktif olur.
* Kliniğin aktif pipeline'ı varsa yeni pipeline pasif oluşur.
* Pipeline yalnızca üç kilitli aşamayla gelir. Özel aşamaları ayrıca ekleyin.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://app.flextell.ai/api/v1/pipelines" \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Tenant: <tenant_id>" \
    -H "Content-Type: application/json" \
    -d '{"name": "İmplant satış hattı"}'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://app.flextell.ai/api/v1/pipelines", {
    method: "POST",
    headers: {
      Authorization: "Bearer <access_token>",
      "X-Tenant": "<tenant_id>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "İmplant satış hattı" }),
  });
  const pipeline = await res.json();
  ```
</CodeGroup>

`PUT /api/v1/pipelines/{id}` aynı kuralla yalnızca `name` alanını günceller.

## Aşamalar

### Aşama ekleme

`POST /api/v1/pipelines/{id}/stages` özel bir aşama ekler.

<ParamField body="name" type="string" required>
  Aşama adı, en çok 255 karakter.
</ParamField>

<ParamField body="color" type="string" required>
  Onaltılık renk kodu: `#abc` veya `#aabbcc` biçimi.
</ParamField>

Yanıt `201` ile yeni aşamayı döner. Aşama özel, kilitsiz ve kazanıldı/kaybedildi değildir.

<Warning>
  API yeni aşamanın `sort_order` değerini belirlemez; değer `0` olarak başlar. Aşamayı panoda istediğiniz yere koymak için ekledikten sonra `reorder` çağrısı yapın.
</Warning>

### Aşama güncelleme

`PUT /api/v1/pipelines/{id}/stages/{stageId}` isteğinde `name` ve `color` alanlarından göndermek istediklerinizi yollayın.

Kilitli aşamalarda yalnızca `color` değişir. Kilitli aşamaya `name` gönderirseniz istek `422` ve `PIPELINE_STAGE_LOCKED` koduyla reddedilir; hiçbir alan değişmez.

### Aşamaları sıralama

`POST /api/v1/pipelines/{id}/stages/reorder` isteğine özel aşamaların kimliklerini istediğiniz sırayla verin.

<ParamField body="order" type="integer[]" required>
  Pipeline'ın özel aşama kimlikleri, en az bir öğe. Özel olmayan veya bu pipeline'a ait olmayan kimlik doğrulama hatası (`422`) verir.
</ParamField>

Sunucu `sort_order` değerlerini `0..n` olarak yeniden yazar. Giriş aşaması her zaman ilk, kazanıldı ve kaybedildi aşamaları her zaman son sırada kalır. Yanıt, `success` alanı ve güncel aşama listesiyle gelir.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://app.flextell.ai/api/v1/pipelines/123/stages/reorder" \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Tenant: <tenant_id>" \
    -H "Content-Type: application/json" \
    -d '{"order": [305, 303, 304]}'
  ```
</CodeGroup>

### Aşamaları listeleme

`GET /api/v1/pipelines/{id}/stages` aşamaları sayfalamadan, `{"data": [...]}` biçiminde döner.

## Aktif etme

Bir klinikte aynı anda tek bir pipeline aktiftir. Lead'ler her zaman aktif pipeline'ın aşamalarında durur. `POST /api/v1/pipelines/{id}/activate` bu pipeline'ı aktif eder, diğerini pasifleştirir ve Lead'leri yeni pipeline'ın aşamalarına taşır.

<ParamField body="stage_mapping" type="object[]">
  Aşama eşleştirme listesi. İsteğe bağlıdır.
</ParamField>

<ParamField body="stage_mapping[].source_stage_id" type="integer" required>
  Şu an aktif olan pipeline'ın bir aşaması. Her kimlik yalnızca bir kez kullanılabilir.
</ParamField>

<ParamField body="stage_mapping[].target_stage_id" type="integer" required>
  Aktif edilecek pipeline'ın bir aşaması. Kaybedildi aşaması hedef olarak seçilemez.
</ParamField>

Taşıma kuralları:

| Lead'in mevcut aşaması | Yeni aşaması |
| - | - |
| Herhangi bir kazanıldı aşaması | Yeni pipeline'ın kazanıldı aşaması |
| Herhangi bir kaybedildi aşaması | Yeni pipeline'ın kaybedildi aşaması |
| `stage_mapping` içinde eşleştirilmiş özel aşama | Seçtiğiniz hedef aşama |
| Eşleştirilmemiş veya aşamasız | Yeni pipeline'ın giriş aşaması |

* Taşıma istek içinde, eşzamanlı yapılır. Dönüştürülmüş ve silinmiş Lead'ler de taşınır.
* Yeni kaybedildi aşaması kayıp nedeni istiyorsa ve oraya inecek bir Lead'in kayıp nedeni boşsa tüm işlem geri alınır ve `422` ile `LEAD_LOST_REASON_REQUIRED` döner. Hiçbir Lead taşınmaz.
* Zaten aktif olan pipeline'ı tekrar aktif etmek bir işlem yapmaz; Lead'ler taşınmaz.
* Taşınan her Lead için etkinlik geçmişine `pipeline_activation_remap` kaydı düşer.
* Yanıt, `is_active: true` olan pipeline'dır.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://app.flextell.ai/api/v1/pipelines/456/activate" \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Tenant: <tenant_id>" \
    -H "Content-Type: application/json" \
    -d '{
      "stage_mapping": [
        {"source_stage_id": 101, "target_stage_id": 405},
        {"source_stage_id": 102, "target_stage_id": 406}
      ]
    }'
  ```
</CodeGroup>

<Tip>
  Etkinleştirmeden önce eski pipeline'ın özel aşamalarının her birini yeni pipeline'da bir hedefe eşleyin. Eşleştirmediğiniz aşamalardaki Lead'ler giriş aşamasına düşer.
</Tip>

## Aşama silme ve taşıma

`DELETE /api/v1/pipelines/{id}/stages/{stageId}` özel bir aşamayı siler. Aşamada Lead varsa Lead'lerin gideceği aşamayı `target_stage_id` ile bildirin.

<ParamField body="target_stage_id" type="integer">
  Aynı pipeline'daki başka bir aşama. Aşamada Lead varsa zorunludur. Silinen aşamanın kendisi olamaz.
</ParamField>

* Kilitli aşama silinemez (`PIPELINE_STAGE_LOCKED`).
* Aşamada Lead varsa ve `target_stage_id` yoksa istek `PIPELINE_STAGE_HAS_LEADS` ile reddedilir.
* `target_stage_id` verilirse aşamadaki tüm Lead'ler (silinmişler dahil) tek işlemde hedef aşamaya taşınır, ardından aşama silinir.
* Hedef kazanıldı aşamasıysa `won_at` damgalanır ve kayıp bilgisi temizlenir. Hedef açık bir aşamaysa kazanıldı ve kayıp bilgisi temizlenir.
* Hedef kayıp nedeni isteyen bir kaybedildi aşamasıysa ve taşınacak bir Lead'in kayıp nedeni boşsa istek `LEAD_LOST_REASON_REQUIRED` ile reddedilir.

```bash curl theme={null}
curl -X DELETE "https://app.flextell.ai/api/v1/pipelines/123/stages/304" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{"target_stage_id": 303}'
```

### Pipeline silme

`DELETE /api/v1/pipelines/{id}` pipeline'ı siler (yumuşak silme; genel kurallar için [Silme yaşam döngüsü](/api/istekler/silme-yasam-dongusu)). Aktif pipeline silinemez. Aşamalarında Lead bulunan pipeline da silinemez; önce Lead'leri başka pipeline'a taşıyın, yani başka bir pipeline'ı aktif edin.

## Hata kodları

Hata biçimi için [Hatalar](/api/istekler/hatalar) sayfasına bakın.

| Kod | HTTP | Ne zaman |
| - | - | - |
| `PIPELINE_ACTIVE_DELETE_BLOCKED` | 422 | Aktif pipeline silinmek istendi. |
| `PIPELINE_STAGE_LOCKED` | 422 | Kilitli aşama silinmek veya yeniden adlandırılmak istendi. |
| `PIPELINE_STAGE_HAS_LEADS` | 422 | Lead içeren aşama hedefsiz silinmek istendi; ya da aşamalarında Lead bulunan pipeline silinmek istendi. |
| `LEAD_LOST_REASON_REQUIRED` | 422 | Aktif etme veya aşama silme, kayıp nedeni boş Lead'leri kayıp nedeni isteyen aşamaya taşıyacak. `errors.lost_reason` alanı gelir. |
| `VALIDATION_FAILED` | 422 | Geçersiz alan: yinelenen pipeline adı, özel olmayan sıralama kimliği, silinecek aşamanın kendisi veya başka pipeline'daki aşama `target_stage_id` olarak verildi. |
| `RESOURCE_NOT_FOUND` | 404 | Pipeline veya aşama bulunamadı ya da kliniğinize ait değil. |

<Note>
  `PIPELINE_STAGE_LOCKED` kilitli aşamayı yeniden adlandırmaya çalıştığınızda da döner. Yanıt iletisi yalnızca silinemeyeceğini söyler.
</Note>

## İlgili sayfalar

<CardGroup cols={2}>
  <Card title="Lead'ler" icon="user-plus" href="/api/kaynaklar/leadler">
    Lead'leri aşamalara taşıma, kazanıldı ve kaybedildi işaretleme.
  </Card>

  <Card title="Pipeline'lar (panel)" icon="git-branch" href="/panel/pipelinelar">
    Aynı işlemlerin panelden yapılışı.
  </Card>
</CardGroup>


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