Entegrasyonlar ve bağlantılar

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. Her istek Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> başlıklarını taşır. Bkz. 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.

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 ve Filtreleme ve sıralama.

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:

Bağlantıyı oluşturun

POST /v1/integration-connections ile draft bağlantı açın. inbound_url ve secret değerlerini dış sisteme tanımlayın.

Örnek kayıt gönderin

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.

Alanları eşleyin

GET /v1/integration-entities ile hedef alanları öğrenin, ardından PUT ile field_mapping gönderin.

Etkinleştirin

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.<anahtar>` 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. Genel hata biçimi için bkz. Hata kodları.

Örnek

Zapier bağlantısı oluşturup eşleyin ve etkinleştirin. Önce kataloğdan Zapier’ın id değerini alın.

curl "https://app.flextell.ai/api/v1/integrations?search=Zapier" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

curl -X POST https://app.flextell.ai/api/v1/integration-connections \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{"integration_id": 123, "entity": "lead", "name": "Zapier – Web formu"}'

curl -X PUT https://app.flextell.ai/api/v1/integration-connections/456 \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "field_mapping": [
      {"source": "name", "target": "full_name"},
      {"source": "phone", "target": "phone_number"}
    ],
    "external_id_path": "id"
  }'

curl -X POST https://app.flextell.ai/api/v1/integration-connections/456/activate \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

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.

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

Entegrasyonlar ve bağlantılar

Endpoint özeti

Entegrasyon kataloğu

Bağlantılar

Bağlantı yaşam döngüsü

Bağlantı nesnesi

Listeleme

Oluşturma, güncelleme ve silme

Etkinleştirme, duraklatma

Alan eşleme

Kaynak alanlar

Hedef alanlar

Kayıt kimliği yolu

Bağlantı ayarları

Gelen kayıtlar

Kayıt durumları

Sonuçlar

Yeniden deneme

Hata mesajları

Hatalar

Örnek

​Endpoint özeti

​Entegrasyon kataloğu

​Bağlantılar

​Bağlantı yaşam döngüsü

​Bağlantı nesnesi

​Listeleme

​Oluşturma, güncelleme ve silme

​Etkinleştirme, duraklatma

​Alan eşleme

​Kaynak alanlar

​Hedef alanlar

​Kayıt kimliği yolu

​Bağlantı ayarları

​Gelen kayıtlar

​Kayıt durumları

​Sonuçlar

​Yeniden deneme

​Hata mesajları

​Hatalar

​Örnek

Endpoint özeti

Entegrasyon kataloğu

Bağlantılar

Bağlantı yaşam döngüsü

Bağlantı nesnesi

Listeleme

Oluşturma, güncelleme ve silme

Etkinleştirme, duraklatma

Alan eşleme

Kaynak alanlar

Hedef alanlar

Kayıt kimliği yolu

Bağlantı ayarları

Gelen kayıtlar

Kayıt durumları

Sonuçlar

Yeniden deneme

Hata mesajları

Hatalar

Örnek