> ## 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. # Gelen lead webhook'u > Dış sistemlerden gizli anahtarlı bir adrese kayıt göndererek otomatik lead oluşturmayı anlatır. Gelen lead webhook'u, Zapier, bir form aracı, bir reklam platformu dışa aktarımı ya da `POST` isteği atabilen herhangi bir sistemden Flextell'e **Lead** aktarmanızı sağlar. Her bağlantının kendine ait bir adresi ve gizli anahtarı vardır. Bu adrese JSON ya da form verisi gönderirsiniz; Flextell kaydı sütun eşlemenize göre Lead'e çevirir. Bu sayfa gönderen sistemin (entegratörün) bakış açısıyla yazılmıştır. Bağlantıyı panelden kurmak ve alan eşlemesini yapmak için [Gelen lead webhook'u (panel)](/panel/baglantilar/gelen-lead-webhooku) sayfasına bakın. ## Nasıl çalışır ```mermaid theme={null} flowchart LR A["Dış sistem"] -->|"POST + X-Flextell-Secret"| B["Webhook adresi"] B -->|"202 Accepted"| A B --> C["Kayıt bekleyenler arasına alınır"] C -->|"Bağlantı Aktif ise"| D["Lead oluşturulur, birleştirilir veya güncellenir"] ``` 1. Klinikte bir bağlantı oluşturursunuz. Bağlantı **Taslak** durumunda açılır ve adresi ile gizli anahtarı hazırdır. 2. Dış sisteminiz kayıtları adrese gönderir. Flextell kaydı alır ve hemen `202` ile yanıt verir. 3. Kayıt arka planda işlenir. İşleme yalnızca bağlantı **Aktif** ise yapılır. 4. Sonuç, bağlantının **Gelen Kayıtlar** listesinde ve ilgili Lead'in kartında görünür. `202` yanıtı kaydın **alındığı** anlamına gelir, Lead'in oluştuğu anlamına gelmez. Kayıt, bağlantı **Taslak** ya da **Duraklatıldı** durumundayken de kabul edilir ve bekletilir. Bağlantıyı etkinleştirdiğinizde bekleyen kayıtlar işlenir. ## Webhook adresi ve gizli anahtar Her bağlantı için şu bilgiler panelde **Bağlantı Bilgileri** sekmesinde görünür. API'den de bağlantı nesnesinde gelir. | Bilgi | Panelde | API alanı | Açıklama | | - | - | - | - | | Adres | **Gönderim Adresi (URL)** | `inbound_url` | `https://app.flextell.ai/api/v1/integrations/inbound/{uuid}` biçiminde, bağlantıya özel adres. | | Başlık adı | **Başlık Adı (Header)** | `secret_header` | Her zaman `X-Flextell-Secret`. | | Gizli anahtar | **Gizli Anahtar (Header Değeri)** | `secret` | `fxs_` ile başlayan rastgele bir değer. | * Gizli anahtarı yalnızca bağlantıyı **düzenleme** iznine (`Update:IntegrationConnection`) sahip kullanıcılar görür. Diğer kullanıcılarda API `secret: null` döndürür. * Gizli anahtarı yenilemek için panelde **Anahtarı Yenile**'yi ya da `POST /api/v1/integration-connections/{id}/rotate-secret` çağrısını kullanın. Eski anahtar **hemen** geçersiz olur. Gönderen sistemdeki başlık değerini güncellemezseniz `401` alırsınız. * Bağlantıyı silerseniz adres `404` döndürür. Silmeden önce gelen kayıtlar ve oluşan Lead'ler korunur; ancak o sırada **bekleyen** kayıtlar hiçbir zaman işlenmez. Bu adres kimlik doğrulaması gerektirmez: `Authorization` başlığı ve `X-Tenant` göndermezsiniz. Klinik, adresteki `uuid` değerinden belirlenir. Gizli anahtarı yalnızca sunucu tarafında saklayın; tarayıcıdan çalışan koda gömmeyin. Bağlantıları API'den yönetmek (oluşturma, eşleme, etkinleştirme, duraklatma) için [Entegrasyonlar](/api/kaynaklar/entegrasyonlar) kaynak rehberine bakın. Bu çağrılar `integrations:read` ve `integrations:write` scope'larını ve `X-Tenant` başlığını ister. ## İstek biçimi ```text theme={null} POST https://app.flextell.ai/api/v1/integrations/inbound/{uuid} X-Flextell-Secret: Content-Type: application/json ``` Gövde şu üç biçimden biri olabilir. | Biçim | `Content-Type` | Kaç kayıt | | - | - | - | | Tek JSON nesnesi | `application/json` | 1 | | Nesnelerden oluşan JSON dizisi | `application/json` | Dizideki nesne sayısı, en fazla 500 | | Form verisi | `application/x-www-form-urlencoded` veya `multipart/form-data` | 1 | * Sorgu dizesi (`?ad=...`) okunmaz; veriyi gövdede gönderin. * `Content-Type` JSON değilse gövde form verisi olarak okunur. * Boş gövde, `{}`, `[]`, sayı/metin listesi, liste içinde liste ya da boş bir öğe `422` ile reddedilir. * Bir istekte en fazla 500 kayıt gönderebilirsiniz. Daha fazlasında hiçbir kayıt saklanmaz (`413`). * İç içe nesneler `contact.phone` gibi nokta yollarıyla düzleştirilir. Eşlemede bu yolları kullanırsınız. ```bash Tek kayıt theme={null} curl -X POST "https://app.flextell.ai/api/v1/integrations/inbound/" \ -H "X-Flextell-Secret: fxs_" \ -H "Content-Type: application/json" \ -d '{"id":"r1","name":"Ayşe Yılmaz","phone":"05xx xxx xx xx","email":"ayse@example.com"}' ``` ```bash Toplu gönderim theme={null} curl -X POST "https://app.flextell.ai/api/v1/integrations/inbound/" \ -H "X-Flextell-Secret: fxs_" \ -H "Content-Type: application/json" \ -d '[{"id":"r1","name":"Ayşe Yılmaz","phone":"05xx xxx xx xx"},{"id":"r2","name":"Ali Veli","email":"ali@example.com"}]' ``` ```bash Form verisi theme={null} curl -X POST "https://app.flextell.ai/api/v1/integrations/inbound/" \ -H "X-Flextell-Secret: fxs_" \ --data-urlencode "name=Ayşe Yılmaz" \ --data-urlencode "phone=05xx xxx xx xx" ``` ## Lead alanları Gelen kayıttaki sütunlar bir **eşleme** ile Lead alanlarına bağlanır. Eşlemeyi panelde **Eşleştirme** adımında ya da bağlantının `field_mapping` alanında `{source, target}` çiftleri olarak tanımlarsınız (en fazla 200 satır). `target` değeri aşağıdaki anahtarlardan biri olmalıdır. Bu listeye `GET /api/v1/integration-entities` ile de ulaşırsınız. | Grup | Anahtar | Etiket | Not | | - | - | - | - | | İletişim | `full_name` | Ad soyad | Ad ve soyad sütunları ayrıysa onlar önceliklidir. Tek sütunda gelen adın son sözcüğü soyad olur. | | İletişim | `first_name`, `last_name` | Ad, Soyad | — | | İletişim | `phone_number` | Telefon | Yalnızca rakamlar tutulur. `5xxxxxxxxx` ve `0xxxxxxxxxx` biçimleri `90` ile başlayacak şekilde düzenlenir. 50 karakteri aşan değer atılır. | | İletişim | `email` | E-posta | Küçük harfe çevrilir. Geçersiz e-posta sessizce atılır. | | İçerik | `description`, `message` | Notlar, Mesaj | Aynı alana birden fazla kaynak eşlerseniz değerler alt alta birleştirilir. | | İçerik | `source_page_url` | Kaynak sayfa URL'si | 255 karaktere kısaltılır. | | İçerik | `expected_value` | Beklenen değer | `1.234,56` gibi yerel biçimleri okur. Sayı olmayan değer atılır. | | Pazarlama | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` | UTM kaynağı, UTM ortamı, UTM kampanyası, UTM terimi, UTM içeriği | Lead'in pazarlama bilgisine yazılır. | | Meta Reklamları | `meta_campaign`, `meta_campaign_id`, `meta_ad_set`, `meta_ad_set_id`, `meta_ad`, `meta_ad_id`, `meta_form`, `meta_form_id`, `meta_platform` | Meta kampanya adı, Meta kampanya kimliği, Meta reklam seti adı, Meta reklam seti kimliği, Meta reklam adı, Meta reklam kimliği, Meta form adı, Meta form kimliği, Meta platformu (fb/ig) | Kimliklerdeki `c:`, `as:`, `ag:`, `f:` önekleri temizlenir. | Metin alanları 255 karaktere kısaltılır. Eşlenmeyen sütunlar Lead'e yazılmaz; ham veri yine de kaydın **Gelen Veri** görünümünde saklanır. ### Kimlik alanı zorunluluğu Bağlantıyı etkinleştirmek için eşlemede şu beş alandan **en az biri** olmalıdır: `full_name`, `first_name`, `last_name`, `phone_number`, `email`. Aksi halde etkinleştirme `422 INTEGRATION_CONNECTION_MAPPING_INCOMPLETE` döndürür; yanıttaki `data.identity_fields` bu alanları listeler. Bir kayıtta bu alanların hiçbirinde kullanılabilir değer yoksa kayıt **Hatalı** olur. ### Kayıt kimliği ve tekrarlayan kayıtlar Gönderen sistemin kendi kayıt kimliğini (örneğin yukarıdaki `id`) bağlantının `external_id_path` alanına yazarsanız aynı kimlikle gelen kayıt yeni Lead açmaz, daha önce oluşan Lead'i **günceller**. Güncellemede eşlenen tüm değerler üzerine yazılır; Lead'in aşaması, atananı ve kaynağı değişmez. Kimlik yolu tanımlı değilse tekrarlayan kayıtlar yalnızca telefon ya da e-posta eşleşmesiyle birleşir. Yeni kayıt şu sırayla işlenir: 1. Aynı klinikte aynı **telefon**, yoksa aynı **e-posta** ile silinmemiş bir Lead varsa kayıt o Lead ile **birleştirilir**: yalnızca boş alanlar doldurulur. 2. Eşleşme yoksa **yeni Lead** oluşturulur ve ona bağlı bir hasta kaydı açılır. ### Bağlantı ayarları Bağlantının `settings` alanı Lead'in nereye düşeceğini belirler. Hepsi isteğe bağlıdır; boş bırakılan ayar varsayılanı kullanır. | Anahtar | Etiket | Boş bırakılırsa | | - | - | - | | `pipeline_stage_id` | Yeni kayıtların aşaması | Lead, aktif pipeline'ın ilk aşamasına eklenir. | | `merged_pipeline_stage_id` | Birleştirilen kayıtların aşaması | Birleştirilen Lead'in aşaması değişmez. Hastaya dönüşmüş Lead taşınmaz. | | `lead_reference_source_id` | Lead kaynağı | Meta alanları eşlenmişse `Meta Ads`, aksi halde entegrasyon adıyla (örneğin `Zapier`) bir kaynak kullanılır. | | `update_merged_lead_source` | Birleştirilen kayıtların kaynağını güncelle | Birleştirilen Lead'in kaynağı değişmez. | | `assigned_user_id` | Atanan kişi | Kliniğin otomatik atama kuralları uygulanır. | Seçilen aşama, kaynak ya da kullanıcı sonradan geçersiz olursa (örneğin pipeline pasife alınırsa) işlem hata vermez, varsayılan davranış uygulanır. Aşama seçimleri yalnızca **aktif** pipeline'a ait olabilir; bkz. [Pipeline'lar](/api/kaynaklar/pipelinelar). ## Yanıtlar ve oran sınırı Başarılı istekte yanıt `202 Accepted` olur ve kabul edilen kayıt sayısını içerir. ```json theme={null} { "success": true, "data": { "accepted": 1 } } ``` Bir istekteki tüm kayıtlar birlikte saklanır; ya hepsi kabul edilir ya hiçbiri. Taslak, duraklatılmış ve aktif bağlantılar aynı yanıtı verir. ### Oran sınırı Her bağlantı için dakikada **120 istek** gönderebilirsiniz. Sınır, bağlantının `uuid` değerine göre sayılır; aynı bağlantıya birden fazla sistemden gönderim yapsanız da toplam sayılır. Sınır aşılırsa `429 TOO_MANY_REQUESTS` alırsınız. Yanıttaki `Retry-After` başlığı beklemeniz gereken saniyeyi söyler. Genel kurallar için [Oran sınırları](/api/istekler/oran-sinirlari) sayfasına bakın. Çok sayıda kaydı tek tek göndermek yerine istek başına 500 kayda kadar dizi olarak gönderin. ## Hatalar ve yeniden deneme ### İstek hataları Bu hatalar istek aşamasında döner ve **hiçbir kayıt saklanmaz**. | Kod | HTTP | Ne zaman | | - | - | - | | `MALFORMED_JSON` | 400 | JSON gövde ayrıştırılamadı. | | `INTEGRATION_INBOUND_UNAUTHORIZED` | 401 | `X-Flextell-Secret` başlığı eksik, yanlış ya da anahtar yenilenmiş. | | `RESOURCE_NOT_FOUND` | 404 | Adres yanlış ya da bağlantı silinmiş (`Entegrasyon bağlantısı bulunamadı`). | | `INTEGRATION_INBOUND_INVALID_PAYLOAD` | 422 | Gövde boş ya da JSON nesnesi, nesne dizisi veya form verisi değil. | | `INTEGRATION_INBOUND_TOO_MANY_RECORDS` | 413 | İstekte 500'den fazla kayıt var. | | `TOO_MANY_REQUESTS` | 429 | Dakikada 120 istek aşıldı. | ### Kayıt işleme hataları Kabul edilen bir kayıt sonradan işlenemeyebilir. Bu durum `202` yanıtında görünmez; kaydın durumundan okunur. Bağlantının **Gelen Kayıtlar** sekmesinden ya da `GET /api/v1/integration-connections/{id}/records` ile izleyin. Kayıt durumları: `pending` (Bekliyor), `processed` (İşlendi), `failed` (Hatalı), `skipped` (Atlandı). İşlenen kayıtta `outcome` değeri `created`, `updated` veya `merged` olur. | Durum | `error_message` | Ne yapmalı | | - | - | - | | `failed` | `Kayıtta eşleştirilen ad, telefon veya e-posta alanlarının hiçbirinde değer yok.` | Bir kimlik sütununu eşleyin. Değerler geçersiz olduğu için atılmış olabilir (bozuk e-posta, boş ya da çok uzun telefon). | | `failed` | `Bu kayıt türü artık içe aktarılamıyor.` | Bağlantı artık bu kayıt türünü işleyemiyor. Destek ekibiyle iletişime geçin. | | `failed` | `Kayıt işlenemedi. Yeniden deneyin; sorun sürerse destek ekibiyle iletişime geçin.` | Yeniden deneyin. | | `skipped` | `Bu kaydın daha önce yazıldığı kayıt silinmiş.` | Yapılacak bir şey yok. Güncellenecek Lead silinmiş; bu kayıt yeniden denenemez. | ### Yeniden deneme * **Hatalı kayıtlar** eşlemeyi düzelttikten sonra yeniden denenir: panelde **Hatalıları Yeniden Dene** ya da satırdaki **Yeniden Dene**, API'de `POST /api/v1/integration-connections/{id}/records/retry`. Gövdedeki `record_ids` (en fazla 500) isteğe bağlıdır; vermezseniz bağlantının tüm hatalı kayıtları denenir. Yanıt `{"queued": n}` biçimindedir. Yalnızca `failed` kayıtlar etkilenir. * **Bekleyen kayıtlar** bağlantıyı etkinleştirince (`POST /api/v1/integration-connections/{id}/activate`) işlenir. * Eşlemeyi kaydetmek **işlenmiş** kayıtları yeniden işlemez. * **Gönderen taraf** `429` yanıtında `Retry-After` süresi kadar bekleyip aynı isteği yeniden göndermelidir. `401`, `404`, `413` ve `422` için isteği değiştirmeden tekrar göndermek sonuç vermez; nedeni düzeltin. Aynı kaydı yeniden gönderme ihtimaliniz varsa bağlantıda kayıt kimliği yolunu (`external_id_path`) tanımlayın. Böylece aynı kimlikli kayıt yeni Lead açmaz, mevcut Lead'i günceller. ## İlgili sayfalar Zapier kurulumu, alan eşleme ve gelen kayıtları izleme. Bağlantıları API ile yönetme. Oluşan Lead kayıtlarını okuma. 429 yanıtı ve bekleme önerileri. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.