Pipeline'lar ve aşamalar

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 sayfasına bakın. Panelde aynı işlemler Pipeline’lar sayfasından yapılır; bkz. Pipeline’lar.

Her istekte Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> başlıkları gerekir. Başlık için Klinikler ve X-Tenant, izin ve görünürlük kuralları için İzinler ve görünürlük sayfasına bakın.

Endpoint özeti

Pipeline’ı okuyan endpoint’ler pipelines:read, değiştirenler pipelines:write scope’u ister. Scope’lar için Scope’lar 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 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.

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.

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.

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ı"}'

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();

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.

string

gerekli

Aşama adı, en çok 255 karakter.

string

gerekli

Onaltılık renk kodu: #abc veya #aabbcc biçimi.

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

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.

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.

integer[]

gerekli

Pipeline’ın özel aşama kimlikleri, en az bir öğe. Özel olmayan veya bu pipeline’a ait olmayan kimlik doğrulama hatası (422) verir.

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.

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]}'

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.

object[]

Aşama eşleştirme listesi. İsteğe bağlıdır.

integer

gerekli

Şu an aktif olan pipeline’ın bir aşaması. Her kimlik yalnızca bir kez kullanılabilir.

integer

gerekli

Aktif edilecek pipeline’ın bir aşaması. Kaybedildi aşaması hedef olarak seçilemez.

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.

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}
    ]
  }'

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.

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.

integer

Aynı pipeline’daki başka bir aşama. Aşamada Lead varsa zorunludur. Silinen aşamanın kendisi olamaz.

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.

curl

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ü). 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 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.

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.

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

Pipeline'lar ve aşamalar

Endpoint özeti

Nesne modeli

Pipeline

Aşama

Pipeline oluşturma

Aşamalar

Aşama ekleme

Aşama güncelleme

Aşamaları sıralama

Aşamaları listeleme

Aktif etme

Aşama silme ve taşıma

Pipeline silme

Hata kodları

İlgili sayfalar

Lead'ler

Pipeline'lar (panel)

​Endpoint özeti

​Nesne modeli

​Pipeline

​Aşama

​Pipeline oluşturma

​Aşamalar

​Aşama ekleme

​Aşama güncelleme

​Aşamaları sıralama

​Aşamaları listeleme

​Aktif etme

​Aşama silme ve taşıma

​Pipeline silme

​Hata kodları

​İlgili sayfalar

Lead'ler

Pipeline'lar (panel)

Endpoint özeti

Nesne modeli

Pipeline

Aşama

Pipeline oluşturma

Aşamalar

Aşama ekleme

Aşama güncelleme

Aşamaları sıralama

Aşamaları listeleme

Aktif etme

Aşama silme ve taşıma

Pipeline silme

Hata kodları

İlgili sayfalar