Rehber: lead akışı

Bu rehber, bir Lead’in Flextell’e girişinden hastaya dönüşmesine kadar olan yolu API çağrılarıyla gösterir. Reklam formu, CRM veya özel bir yazılımla Lead topluyorsanız aynı sırayı izleyebilirsiniz. Her uç noktanın tüm alanları için Lead’ler kaynak sayfasına bakın.

Senaryo

Web sitenizdeki bir form doldurulur. Entegrasyonunuz şu adımları izler: Örneklerde Ayşe Yılmaz adlı örnek bir kişi kullanılır. Tüm isteklerde Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> başlıkları gerekir. Başlıklar için Klinikler ve X-Tenant sayfasına bakın.

Adım	Uç nokta	Scope	İzin
Lead oluşturma	`POST /leads`	`leads:write`	`Create:Lead` (`assigned_user_id` göndermek için ayrıca `Assign:Lead`)
Aşama listesi	`GET /leads/pipeline-summary`	`leads:read`	`View:Lead`
Aşama değiştirme	`PUT /leads/{id}`	`leads:write`	`Update:Lead`
Atanabilir kullanıcılar	`GET /leads/assignable-users`	`leads:read` veya `conversations:read`	`Assign:Lead` veya `View:Conversation`
Atama	`POST /leads/{id}/assign`	`leads:write`	`Assign:Lead`
Kazanıldı	`POST /leads/{id}/won`	`leads:write`	`Update:Lead`
Dönüştürme	`POST /leads/{id}/convert`	`leads:write` ve `customers:write`	`Convert:Lead`

Bir kullanıcı, ViewAllLeads:Lead izni yoksa yalnızca kendisine atanmış Lead’leri görür. Lead’i kendi oluşturmuş olması görünürlük sağlamaz. Ayrıntılar için İzinler ve görünürlük sayfasına bakın.

Lead oluşturma

POST /api/v1/leads isteğinde hiçbir alan zorunlu değildir, ancak en azından ad ve telefon göndermeniz önerilir. phone_number sunucuda ülke kodlu rakamlara çevrilir ve kliniğin canlı Lead’leri arasında benzersiz olmalıdır. Telefonu mevcut bir hastayla eşleşirse yeni Lead o hastanın kaydına bağlanır; yinelenen kayıt oluşmaz.

curl -X POST https://app.flextell.ai/api/v1/leads \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ayşe",
    "last_name": "Yılmaz",
    "phone_number": "+90 5xx xxx xx xx",
    "email": "ayse@example.com",
    "message": "Saç ekimi hakkında bilgi almak istiyorum.",
    "source_page_url": "https://example.com/iletisim",
    "treatment_ids": [123]
  }'

const res = await fetch("https://app.flextell.ai/api/v1/leads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "X-Tenant": tenantId,
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    first_name: "Ayşe",
    last_name: "Yılmaz",
    phone_number: "+90 5xx xxx xx xx",
    treatment_ids: [123],
  }),
});
const { data: lead } = await res.json();

Yanıt 201 ile döner ve oluşan Lead’i içerir. Sonraki adımlarda kullanacağınız id değerini saklayın. Oluşturma sırasında şu kurallar işler:

pipeline_stage_id göndermezseniz Lead, aktif pipeline’ın giriş aşamasına (varsayılan kurulumda Yeni) düşer. Gönderirseniz aşama aktif pipeline’a ait olmalıdır.
expected_value göndermezseniz, seçtiğiniz tedavilerin fiyatlarının toplamı kullanılır.
assigned_user_id boş bırakılırsa ve kliniğiniz otomatik atama kullanıyorsa Lead, oluşturma anında bir satış temsilcisine atanabilir. Bu davranış kliniğinizin ayarlarına göre değişir.
Oluşturan kullanıcı Assign:Lead iznine sahip değilse ama View:Lead ve ReceiveLeads:Lead izinleri varsa (örneğin bir satış temsilcisi) Lead kendisine atanır.

Aşama değiştirme

Aşama kimliklerini almak için aktif pipeline’ın özetini çekin. Yanıttaki stages dizisinde her aşamanın stage.id, stage.name, stage.is_won ve stage.is_lost alanları bulunur.

curl https://app.flextell.ai/api/v1/leads/pipeline-summary \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Accept: application/json"

Aşamayı PUT /api/v1/leads/{id} ile değiştirin:

curl -X PUT https://app.flextell.ai/api/v1/leads/123 \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"pipeline_stage_id": 45}'

Hedef aşama, aktif pipeline’ın aşaması olmalıdır.
Kayıp aşamasına taşırken lost_reason göndermeniz gerekebilir. Kayıp aşaması neden istiyorsa ve göndermezseniz LEAD_LOST_REASON_REQUIRED alırsınız. Bunun yerine POST /leads/{id}/lost da kullanabilirsiniz.
Kayıp aşamasından başka bir aşamaya taşımak Lead’i yeniden açar; kayıp nedeni ve tarihi temizlenir.
Dönüştürülmüş bir Lead’in aşaması değiştirilemez.

PUT /leads/{id} ile assigned_user_id değiştirmek yalnızca sahibi değiştirir. Açık görevler ve notlar yeni sahibe geçmez. Atama için bir sonraki bölümdeki assign uç noktasını kullanın.

Aşamaların kendisini (ekleme, sıralama, aktif pipeline’ı değiştirme) yönetmek için Pipeline’lar sayfasına bakın.

Atama

Önce Lead’i alabilecek kullanıcıları listeleyin. Yanıtta yalnızca ReceiveLeads:Lead iznine sahip, kliniğin aktif kullanıcıları yer alır; email alanı yalnızca Assign:Lead iznine sahip çağıranlara döner.

curl "https://app.flextell.ai/api/v1/leads/assignable-users?search=Mehmet" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Accept: application/json"

Sonra atamayı yapın:

curl -X POST https://app.flextell.ai/api/v1/leads/123/assign \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"assigned_user_id": 7, "task_action": "transfer"}'

task_action, Lead’in açık görevlerine ne olacağını belirler:

Değer	Etki
`transfer` (varsayılan)	Açık görevler yeni sahibe geçer. Lead’in notları, hastanın sorumlusu ve hastanın teklifleri de yeni sahibe geçer.
`close`	Açık görevler tamamlanmış sayılır.
`keep`	Görevler eski sahipte kalır ama pasife alınır.

Yanıt lead ve cap_exceeded alanlarını içerir. Yeni sahip AutoAssignLeads:Lead iznine sahipse ve kliniğindeki aktif Lead sayısı sınırına ulaşmışsa cap_exceeded true olur. Atama yine de yapılır; yanıt yalnızca uyarır. Birden çok Lead’i tek seferde atamak için POST /leads/bulk-assign kullanılır. Panelden atama için Atama sayfasına bakın.

Kazanıldı ve dönüştürme

Dönüştürme yalnızca kazanıldı aşamasındaki Lead’lerde çalışır. Önce Lead’i kazanıldı olarak işaretleyin:

curl -X POST https://app.flextell.ai/api/v1/leads/123/won \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Accept: application/json"

Ardından hastaya dönüştürün. Bu istek leads:write ve customers:write scope’larının ikisini birden ister.

curl -X POST https://app.flextell.ai/api/v1/leads/123/convert \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{}'

Yanıt, dönüşümün nasıl sonuçlandığını gösteren bir result alanı, oluşan veya eşleşen customer kaydını ve güncel lead kaydını içerir.

`result`	Anlamı
`created_new`	Yeni hasta oluşturuldu.
`matched_existing`	Telefon eşleştiği için var olan hastaya bağlandı.

Dönüştürme tekrarlanabilir. Zaten dönüştürülmüş bir Lead için istek, aynı hastayı matched_existing ile döndürür.
Lead’in notları ve dosyaları hastaya kopyalanır. Görevler kopyalanmaz; hastanın kaydında Lead üzerinden görünür.
Geri alma (hastayı yeniden Lead yapma) yoktur.
Elinizde belirli bir hasta kaydı varsa existing_customer_id göndererek Lead’i o hastaya bağlayabilirsiniz. API ile oluşturulan Lead’lerin çoğunda gerekmez.
Dönüşümden sonra Lead’in sahibi sabitlenir; assign çağrısı reddedilir.

Kliniğiniz otomatik dönüştürme kullanıyorsa Lead, randevu veya satış oluşturulduğunda kendiliğinden hastaya dönüşebilir. Bu durumda convert çağrısına gerek kalmaz. Dönüşmemiş bir Lead için fatura veya tahsilat işlemi oluşturmak (satış otomatik dönüştürme tetikleyicisi değilse satış da) LEAD_FINANCIAL_BLOCKED (422) hatası verir; önce Lead’i dönüştürün.

Panel karşılığı için Hastaya dönüştürme sayfasına, dönüşen kaydın hasta tarafı için Hastalar sayfasına bakın.

Hata durumları

Hata gövdesi {"success": false, "error_code": "...", "message": "..."} biçimindedir. Genel kurallar için Hata kodları sayfasına bakın.

Kod	HTTP	Ne zaman
`TENANT_HEADER_REQUIRED`	400	`X-Tenant` başlığı gönderilmedi.
`FORBIDDEN`	403	Token’da gereken scope ya da kullanıcıda gereken izin yok.
`LEAD_NOT_ASSIGNED`	403	Lead başka bir kullanıcıya atanmış ve çağıranın `ViewAllLeads:Lead` izni yok. Yanıttaki `data.assigned_user`, sahibin `{id, name}` bilgisini ya da `null` döndürür.
`RESOURCE_NOT_FOUND`	404	Lead yok, silinmiş ya da başka bir kliniğe ait.
`CUSTOMER_ERASED`	409	Lead’in hastasının verileri imha edilmiş; kayıt salt okunurdur.
`LEAD_NOT_CONVERTIBLE`	422	`convert` çağrıldı ama Lead kazanıldı aşamasında değil. Önce `won` çağırın.
`LEAD_ALREADY_CONVERTED`	422	Dönüştürülmüş Lead’de aşama değiştirme, `lost` veya `assign` denendi.
`LEAD_LOST_REASON_REQUIRED`	422	Neden isteyen kayıp aşamasına `lost_reason` olmadan taşındı.
`LEAD_NO_WON_STAGE`	422	Aktif pipeline’da kazanıldı aşaması yok.
`LEAD_NO_LOST_STAGE`	422	Aktif pipeline’da kaybedildi aşaması yok.
`VALIDATION_FAILED`	422	Alan hatası. Örneğin telefon başka bir Lead’de kayıtlı, `assigned_user_id` Lead alamayan bir kullanıcı ya da `pipeline_stage_id` aktif pipeline’a ait değil. Ayrıntı `errors` içinde gelir.

LEAD_NOT_ASSIGNED alırsanız Lead’i yeniden denemek yerine data.assigned_user ile sahibini bulun ve gerekirse Lead’i çağıran kullanıcıya atatın ya da kullanıcıya ViewAllLeads:Lead izni verin.

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

Rehber: lead akışı

Senaryo

Lead oluşturma

Aşama değiştirme

Atama

Kazanıldı ve dönüştürme

Hata durumları

​Senaryo

​Lead oluşturma

​Aşama değiştirme

​Atama

​Kazanıldı ve dönüştürme

​Hata durumları

Senaryo

Lead oluşturma

Aşama değiştirme

Atama

Kazanıldı ve dönüştürme

Hata durumları