> ## 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. # Entegrasyonlar ve bağlantılar > Entegrasyon kataloğunu, entegrasyon bağlantılarını ve gelen kayıtları anlatır. Entegrasyon kataloğu, Flextell'in desteklediği servisleri listeler: Google Calendar, Gmail, Nilvera ve NES e-Fatura, WhatsApp, Telegram, Website, Zapier ve diğerleri. Katalog tüm klinikler için ortaktır. **Bağlantı** ise kliniğinize ait bir kayıttır: dış bir sistemin Flextell'e kayıt göndereceği adresi, gizli anahtarı ve alan eşlemesini tutar. Bugün yalnızca **Zapier** bağlantı oluşturmaya açıktır. Bağlantıyla gelen kayıtlar **Lead** olarak yazılır. Zapier'dan veya kendi sisteminizden kayıt gönderen entegratörler bu sayfadaki uç noktaları kullanır. Kayıt gönderme adresinin kendisi için bkz. [Gelen lead webhook'u](/api/webhooklar/gelen-lead-webhooku). Her istek `Authorization: Bearer ` ve `X-Tenant: ` başlıklarını taşır. Bkz. [Klinikler ve X-Tenant](/api/klinikler-ve-x-tenant). ## Endpoint özeti | Metot | Endpoint | Açıklama | Scope | İzin | | - | - | - | - | - | | `GET` | `/v1/integrations` | Kataloğu listeler. | `integrations:read` | `View:Integrations` | | `GET` | `/v1/integrations/{id}` | Tek entegrasyonu getirir. | `integrations:read` | `View:Integrations` | | `GET` | `/v1/integration-entities` | Bağlantıların yazabildiği kayıt türlerini, hedef alanları ve ayarları listeler. | `integrations:read` | `View:IntegrationConnection` | | `GET` | `/v1/integration-connections` | Kliniğin bağlantılarını listeler. | `integrations:read` | `View:IntegrationConnection` | | `POST` | `/v1/integration-connections` | Bağlantı oluşturur (`draft` durumunda). | `integrations:write` | `Create:IntegrationConnection` | | `GET` | `/v1/integration-connections/{id}` | Tek bağlantıyı getirir. | `integrations:read` | `View:IntegrationConnection` | | `PUT` | `/v1/integration-connections/{id}` | Ad, alan eşlemesi, kayıt kimliği yolu ve ayarları günceller. | `integrations:write` | `Update:IntegrationConnection` | | `DELETE` | `/v1/integration-connections/{id}` | Bağlantıyı siler. | `integrations:write` | `Delete:IntegrationConnection` | | `POST` | `/v1/integration-connections/{id}/activate` | Bağlantıyı etkinleştirir. | `integrations:write` | `Update:IntegrationConnection` | | `POST` | `/v1/integration-connections/{id}/pause` | Bağlantıyı duraklatır. | `integrations:write` | `Update:IntegrationConnection` | | `POST` | `/v1/integration-connections/{id}/rotate-secret` | Gizli anahtarı yeniler. | `integrations:write` | `Update:IntegrationConnection` | | `GET` | `/v1/integration-connections/{id}/source-fields` | Dış sistemin gönderdiği alanları listeler. | `integrations:read` | `View:IntegrationConnection` | | `GET` | `/v1/integration-connections/{id}/records` | Gelen kayıtları listeler. | `integrations:read` | `View:IntegrationConnection` | | `POST` | `/v1/integration-connections/{id}/records/retry` | Hatalı kayıtları yeniden dener. | `integrations:write` | `Update:IntegrationConnection` | Bu izinler yalnızca seçtiğiniz klinik (`X-Tenant`) için aranır. Başka bir kliniğin bağlantısını istediğinizde `404` alırsınız. Panel karşılığı için bkz. [Panel: Entegrasyonlar](/panel/baglantilar/entegrasyonlar). ## Entegrasyon kataloğu `GET /v1/integrations` sayfalanmaz ve ada göre sıralı döner. Pasif entegrasyonlar da listede yer alır; kullanılabilir olup olmadığını `is_active` alanından anlarsınız. | Parametre | Açıklama | | - | - | | `search` | En çok 255 karakter. Entegrasyon adında ve firma adında arar. Açıklamada ve `system_name` içinde aramaz. | | `type` | `chat`, `llm`, `calendar`, `invoice`, `email`, `crm` veya `automation`. | | `is_new` | `true` veya `false`. | Yanıttaki önemli alanlar: | Alan | Tür | Açıklama | | - | - | - | | `id` | tamsayı | Bağlantı oluştururken `integration_id` olarak kullanılır. | | `name`, `system_name` | metin | Görünen ad ve kararlı anahtar (örneğin `automation.zapier`). | | `description` | metin | Türkçe açıklama. | | `company_name`, `company_url` | metin | Sağlayıcı firma. | | `company_logo` | metin veya `null` | 5 dakika geçerli imzalı adres. | | `type` | metin | Entegrasyon türü. | | `required_fields` | liste | Kimlik bilgisi isteyen entegrasyonlarda `{key, name}` çiftleri. | | `is_new`, `is_active` | boolean | Yeni rozeti ve kullanılabilirlik. | | `is_connected` | boolean | Kliniğiniz (veya kullanıcınız) bu entegrasyona bağlı mı. Bağlantı tabanlı entegrasyonlarda en az bir `active` bağlantı gerekir; `draft` bağlantılar sayılmaz. | | `connection_method` | metin veya `null` | Bağlantı oluşturulabilen entegrasyonlarda `inbound_webhook`. | | `supported_entities` | liste | `[{value, label}]`. Zapier için `lead`. | | `connections_count` | tamsayı | Kliniğinizin silinmemiş bağlantı sayısı (her durumda). | `GET /v1/integrations/{id}` geçersiz bir `id` (`abc`, `0`, `-1`, `1.5`) için `422`, olmayan kayıt için `404` döner. ## Bağlantılar Bağlantı oluşturmak için `integration_id` olarak `connection_method` değeri dolu ve `is_active` değeri `true` olan bir entegrasyon seçin. ### Bağlantı yaşam döngüsü | Durum | Anlamı | | - | - | | `draft` | Yeni oluşturuldu. Kayıt kabul eder, işlemez. | | `active` | Gelen kayıtlar Lead'e dönüştürülür. | | `paused` | Kayıt kabul eder, işlemez. | Yeni bağlantı her zaman `draft` olarak başlar. `draft` durumuna geri dönüş yoktur. `rotate-secret` durumu değiştirmez. ### Bağlantı nesnesi | Alan | Tür | Açıklama | | - | - | - | | `id`, `name` | tamsayı, metin | Bağlantının kimliği ve adı. | | `integration` | nesne | `{id, name, system_name, company_logo}`. | | `entity` | nesne | `{value, label}`. Oluşturulduktan sonra değişmez. | | `status` | metin | `draft`, `active` veya `paused`. | | `inbound_url` | metin | Dış sistemin kayıt göndereceği adres. | | `secret` | metin veya `null` | Gizli anahtar. Yalnızca `Update:IntegrationConnection` iznine sahip olanlara döner; diğerleri `null` görür. | | `secret_header` | metin | Her zaman `X-Flextell-Secret`. | | `field_mapping` | liste | `[{source, target}]`. | | `external_id_path` | metin veya `null` | Dış sistemin kayıt kimliğini taşıyan alanın yolu. | | `settings` | nesne | Bağlantı ayarları. | | `stats` | nesne | `{pending, processed, failed, skipped}` kayıt sayıları. | | `last_received_at`, `last_processed_at` | tarih | Son kayıt alma ve işleme zamanı. | ### Listeleme `GET /v1/integration-connections` yanıtı sayfalanır. Genel kurallar için bkz. [Sayfalama](/api/istekler/sayfalama) ve [Filtreleme ve sıralama](/api/istekler/filtreleme-ve-siralama). | Parametre | Açıklama | | - | - | | `integration_id` | Entegrasyona göre filtreler. | | `entity` | `lead`. | | `status` | `draft`, `active` veya `paused`. | | `created_at_from`, `created_at_to` | Klinik saat diliminde tarih aralığı. Yalnızca tarih içeren `created_at_to` o günün tamamını kapsar. | | `sort_by` | `created_at`, `name` veya `last_received_at`. Varsayılan `created_at` (yeniden eskiye). | | `sort_order` | `asc` veya `desc`. | | `per_page`, `page` | `per_page` 1 ile 100 arasındadır, varsayılan 15. | ### Oluşturma, güncelleme ve silme `POST /v1/integration-connections` gövdesi: | Alan | Zorunlu | Açıklama | | - | - | - | | `integration_id` | Evet | Katalogdaki mevcut entegrasyon. | | `entity` | Evet | `lead`. | | `name` | Evet | En çok 255 karakter. Bağlantıları ayırt etmek için kaynak tablonun adını verebilirsiniz. | Yanıt `201` ve `draft` durumundaki bağlantıdır; `inbound_url` ve `secret` alanları dolu gelir. `PUT` isteğinde göndermediğiniz alanlar değişmez. `field_mapping` ve `settings` gönderdiğinizde saklı değerin yerine geçer (birleştirilmez). `field_mapping: []` eşlemeyi temizler. `external_id_path: null` kayıt kimliğiyle güncellemeyi kapatır. `DELETE` bağlantıyı siler: adres artık `404` döner. Bağlantıyla önceden oluşturulmuş Lead'ler silinmez. Silinen bağlantının bekleyen kayıtları hiç işlenmez. `rotate-secret` çağrısından sonra eski gizli anahtar hemen geçersiz olur. Dış sistemdeki `X-Flextell-Secret` başlık değerini yeni anahtarla güncelleyin; aksi hâlde gönderimler `401` alır. ### Etkinleştirme, duraklatma `activate`, eşlemede en az bir kimlik alanı (bir sonraki bölüme bakın) yoksa reddedilir. Çağrı tekrarlanabilir: bağlantı zaten `active` ise de bekleyen (`pending`) tüm kayıtlar yeniden işleme alınır. `pause` her durumdan çağrılabilir. ## Alan eşleme Eşleme, dış sistemin gönderdiği alanları (`source`) Flextell'in Lead alanlarına (`target`) bağlar. Akış şöyledir: `POST /v1/integration-connections` ile `draft` bağlantı açın. `inbound_url` ve `secret` değerlerini dış sisteme tanımlayın. Dış sistemden en az bir kayıt gönderin. `GET .../source-fields` çağrısı `records_count` değerini ve gelen alanları döndürür. `GET /v1/integration-entities` ile hedef alanları öğrenin, ardından `PUT` ile `field_mapping` gönderin. `POST .../activate` çağrısı bekleyen kayıtları işleme alır, sonraki kayıtlar geldikçe işlenir. ### Kaynak alanlar `GET .../source-fields`, bağlantıya gelen **son 25 kaydın** alanlarını birleştirir. Yanıt `{records_count, fields: [{path, example}]}` biçimindedir. `example` ilk dolu değerdir; en çok 200 karakter, değer boşsa `null`. İç içe nesneler nokta yoluyla yazılır (`contact.phone`), nesne listeleri sıra numarasıyla (`items.0.sku`). ### Hedef alanlar `GET /v1/integration-entities` yanıtı her kayıt türü için `fields`, `identity_fields` ve `settings` döndürür. Lead için hedef alanlar: | Grup | Anahtarlar | Etiket | | - | - | - | | `İletişim` | `full_name`, `first_name`, `last_name`, `phone_number`, `email` | Ad soyad, Ad, Soyad, Telefon, E-posta | | `İçerik` | `description`, `message`, `source_page_url`, `expected_value` | Notlar, Mesaj, Kaynak sayfa URL'si, Beklenen değer | | `Pazarlama` | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` | UTM kaynağı, ortamı, kampanyası, terimi, içeriği | | `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, reklam seti, reklam ve form adları ile kimlikleri; platform (fb/ig) | **Kimlik alanları** `full_name`, `first_name`, `last_name`, `phone_number` ve `email` alanlarıdır. Etkinleştirmek için bunlardan en az birini eşlemelisiniz. Eşleme kuralları: * `field_mapping` en çok 200 satır içerir. `source` en çok 255, `target` en çok 100 karakterdir ve `target`, `integration-entities` yanıtındaki bir anahtar olmalıdır. * Birden çok kaynak aynı hedefe eşlenirse `description` ve `message` değerleri satır sonuyla birleştirilir; diğer hedeflerde ilk dolu değer alınır. Panel aynı alana iki sütun eşlemenize izin vermez. * Ad: ayrı `first_name` ve `last_name` sütunları `full_name` sütunundan önceliklidir. `full_name` değerinin son sözcüğü soyad olur; tek sözcük ad sayılır. * Telefon numarası normalleştirilir; hiç rakam içermiyorsa veya 50 karakteri aşıyorsa atılır. E-posta küçük harfe çevrilir; geçersizse veya 255 karakteri aşıyorsa atılır. Metinler 255 karaktere kısaltılır. * `expected_value` yerel biçimleri (`1.250,50`) ve para birimi simgelerini kabul eder; anlaşılmazsa atılır. * Meta sütunlarındaki `c:`, `as:`, `ag:`, `f:` önekleri kimliklerden temizlenir. ### Kayıt kimliği yolu `external_id_path`, dış sistemin kendi kayıt kimliğini taşıyan alanın yoludur (örneğin `id`). Tanımlarsanız aynı kimlikle gelen kayıt yeni Lead açmaz, mevcut Lead'in **tüm eşlenen değerlerini** günceller. Aşama, atanan kişi ve kaynak değişmez. Tanımlamazsanız yinelenen kayıtlar yalnızca telefon veya e-posta eşleşmesiyle birleşir. ### Bağlantı ayarları `settings` alanındaki tüm anahtarlar isteğe bağlıdır. Ayarlar sonradan geçersiz olursa (aşama silindi, pipeline pasife alındı, kullanıcı artık atanamıyor) işleme sırasında sessizce varsayılana döner. | Anahtar | Etiket | Kural | | - | - | - | | `pipeline_stage_id` | Yeni kayıtların aşaması | Aktif pipeline'ın bir aşaması. Boşsa Lead giriş aşamasına düşer. | | `merged_pipeline_stage_id` | Birleştirilen kayıtların aşaması | Aktif pipeline'ın bir aşaması. | | `lead_reference_source_id` | Lead kaynağı | Kliniğinizin silinmemiş Lead kaynağı. | | `update_merged_lead_source` | Birleştirilen kayıtların kaynağını güncelle | boolean | | `assigned_user_id` | Atanan kişi | Lead atanabilen kullanıcı. Aksi hâlde `Seçilen kullanıcıya lead atanamaz.` | Lead kaynağı seçmezseniz sırasıyla şu kaynak kullanılır: Meta alanı eşlenmişse `Meta Ads`, aksi hâlde entegrasyon adıyla oluşturulan kaynak (örneğin `Zapier`). Atanan kişi boşsa kliniğin otomatik atama kuralları çalışır. ## Gelen kayıtlar Dış sistemin gönderdiği her kayıt ham hâliyle saklanır, sonra Lead'e dönüştürülür. `GET .../records` kayıtları yeniden eskiye sıralı ve sayfalı döndürür. | Parametre | Açıklama | | - | - | | `status` | `pending`, `processed`, `failed` veya `skipped`. | | `subject_id` | Yazılan kaydın kimliği. Bir Lead'in hangi bağlantıdan geldiğini bulmak için Lead kimliğini verin. | | `created_at_from`, `created_at_to` | Klinik saat diliminde tarih aralığı. | | `per_page`, `page` | `per_page` 1 ile 100 arasında, varsayılan 15. | | Alan | Açıklama | | - | - | | `id` | Kayıt kimliği. `records/retry` için kullanılır. | | `status` | `pending`, `processed`, `failed` veya `skipped`. | | `outcome` | Yalnızca `processed` kayıtlarda: `created`, `updated` veya `merged`. | | `external_id` | `external_id_path` ile okunan değer. | | `payload` | Kayıt, gönderildiği gibi. | | `error_message` | Hatalı veya atlanan kayıtlarda Türkçe açıklama, diğerlerinde `null`. | | `subject` | `{type, id, label}` veya `null`. Yazılan Lead. | | `received_at`, `processed_at` | Alınma ve son işlenme zamanı. | ### Kayıt durumları | Durum | Anlamı | | - | - | | `pending` | Alındı, işlenmeyi bekliyor. Bağlantı `active` değilse beklemeye devam eder. | | `processed` | Lead'e yazıldı. | | `failed` | İşlenemedi. Düzeltip yeniden deneyebilirsiniz. | | `skipped` | Yapılacak iş yok. Yeniden denenmez. | ### Sonuçlar | `outcome` | Ne zaman | | - | - | | `created` | Yeni Lead açıldı. | | `updated` | Aynı kayıt kimliğine bağlı Lead güncellendi. | | `merged` | Telefon, bulunamazsa e-posta eşleşmesiyle bulunan Lead'in yalnızca boş alanları dolduruldu. | Birleştirmede önce telefona, sonra e-postaya bakılır; aynı klinikteki silinmemiş ve en eski Lead seçilir. `merged_pipeline_stage_id` doluysa ve Lead hastaya dönüştürülmediyse Lead o aşamaya taşınır. ### Yeniden deneme `POST .../records/retry` yalnızca `failed` kayıtları yeniden `pending` yapar ve `{"queued": n}` döner. Gövdede `record_ids` (en çok 500 tamsayı) verirseniz yalnızca onlar denenir; vermezseniz tüm hatalı kayıtlar denenir. Başka durumdaki veya başka bağlantıdaki kimlikler sessizce yok sayılır. Bağlantı `active` değilse kayıtlar etkinleştirmeyi bekler. ### Hata mesajları | Durum | `error_message` | | - | - | | `failed` | `Kayıtta eşleştirilen ad, telefon veya e-posta alanlarının hiçbirinde değer yok.` | | `failed` | `Bu kayıt türü artık içe aktarılamıyor.` | | `failed` | `Kayıt işlenemedi. Yeniden deneyin; sorun sürerse destek ekibiyle iletişime geçin.` | | `skipped` | `Bu kaydın daha önce yazıldığı kayıt silinmiş.` | İlk mesajda eşlediğiniz sütunların değerleri boş olabilir ya da geçersiz oldukları için atılmış olabilir (geçersiz e-posta, rakamsız telefon). Eşlemeyi düzeltin ve `records/retry` çağırın. Lead detay yanıtında `integration_source` alanı Lead'in geldiği bağlantıyı gösterir: `{connection_id, connection_name, integration, external_id}`. Alan yalnızca `external_id_path` tanımlıysa dolar. ## Hatalar | Kod | HTTP | Ne zaman | | - | - | - | | `INTEGRATION_NOT_CONNECTABLE` | 422 | Seçilen entegrasyon pasif veya bağlantı kurmaya açık değil. | | `INTEGRATION_ENTITY_NOT_SUPPORTED` | 422 | `entity` değeri entegrasyonun `supported_entities` listesinde değil. | | `INTEGRATION_CONNECTION_MAPPING_INCOMPLETE` | 422 | Eşlemede kimlik alanı olmadan `activate` çağrıldı. `data.identity_fields` kimlik alanlarını listeler. | | `VALIDATION_FAILED` | 422 | Geçersiz alan, bilinmeyen `target`, başka kliniğe ait aşama veya kaynak, atanamayan kullanıcı. Ayrıntı `field_mapping.N.target` ve `settings.` gibi alan adlarıyla gelir. | | `RESOURCE_NOT_FOUND` | 404 | `Entegrasyon bulunamadı` veya `Entegrasyon bağlantısı bulunamadı`. Başka kliniğin bağlantısı için de bu hata döner. | | `FORBIDDEN` | 403 | İzin veya scope eksik. | | `TENANT_HEADER_REQUIRED` | 400 | `X-Tenant` başlığı yok. | `INTEGRATION_CONNECTION_MAPPING_INCOMPLETE` mesajı: `Bağlantıyı etkinleştirmeden önce en az bir ad, telefon veya e-posta alanını eşleştirin.` Kayıt gönderme adresinin hataları (`401`, `413`, `429` ve diğerleri) için bkz. [Gelen lead webhook'u](/api/webhooklar/gelen-lead-webhooku). Genel hata biçimi için bkz. [Hata kodları](/api/istekler/hata-kodlari). ## Örnek Zapier bağlantısı oluşturup eşleyin ve etkinleştirin. Önce kataloğdan Zapier'ın `id` değerini alın. ```bash Katalog theme={null} curl "https://app.flextell.ai/api/v1/integrations?search=Zapier" \ -H "Authorization: Bearer " \ -H "X-Tenant: " ``` ```bash Bağlantı oluşturma theme={null} curl -X POST https://app.flextell.ai/api/v1/integration-connections \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Content-Type: application/json" \ -d '{"integration_id": 123, "entity": "lead", "name": "Zapier – Web formu"}' ``` ```bash Eşleme theme={null} curl -X PUT https://app.flextell.ai/api/v1/integration-connections/456 \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Content-Type: application/json" \ -d '{ "field_mapping": [ {"source": "name", "target": "full_name"}, {"source": "phone", "target": "phone_number"} ], "external_id_path": "id" }' ``` ```bash Etkinleştirme theme={null} curl -X POST https://app.flextell.ai/api/v1/integration-connections/456/activate \ -H "Authorization: Bearer " \ -H "X-Tenant: " ``` Bu eşlemeyle gelen `{"id":"r1","name":"Ayşe Yılmaz","phone":"05xx xxx xx xx"}` kaydı yeni bir Lead olarak yazılır ve `r1` kayıt kimliği olarak saklanır. Aynı `id` ile gelen sonraki kayıt bu Lead'i günceller. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.