İçe aktarma

İçe aktarma API’si, kliniğin eski yazılımındaki kayıtları Flextell’e taşır. Kliniğiniz önce bir içe aktarma kaynağı kurar ve o yazılımın API bağlantı bilgilerini girer. Sonra bir aktarım işi başlatır. Flextell kaynağın REST API’sinden kayıtları çeker ve eşleşen Flextell kayıtlarını oluşturur ya da günceller.

Bu bir CSV veya Excel yükleme özelliği değildir. Dosya göndermezsiniz. Yalnızca kaynak yazılımın API’sine bağlanırsınız.

Desteklenen kaynaklar:

Kaynak	`name`	Aktarılabilen veri türleri	Bağlantı bilgileri
Estesoft Stella	`Estesoft Stella`	13 tür: `user`, `treatment`, `room`, `product`, `customer`, `lead`, `bank_info`, `sale`, `invoice`, `accounting_transaction`, `customer_note`, `customer_file`, `appointment`	`base_url`, `username`, `password`, `api_key`
Dr.DENTES	`Dr.DENTES`	`user`, `treatment`, `customer`, `appointment`	`base_url`, `api_key`

Kaynak listesi sabittir. Kaynak ekleyemez veya silemezsiniz. Panelde aynı işlemleri Bağlantılar → İçe Aktar sayfasından yaparsınız. Bkz. İçe aktarma (panel).

Endpoint özeti

Tüm endpoint’ler https://app.flextell.ai/api/v1/import altındadır. Her istekte Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> başlıkları gerekir. Bkz. Klinikler ve X-Tenant ve scope’lar.

Metot	Endpoint	Açıklama	Scope	İzin
GET	`/v1/import/types`	Tüm veri türlerinin kataloğu (`value`, `label`, `description`)	`imports:read`	Görüntüle (İçe Aktarım)
GET	`/v1/import/sources`	Kaynakları listeler	`imports:read`	Görüntüle (İçe Aktarım)
GET	`/v1/import/sources/{id}`	Tek kaynağı getirir	`imports:read`	Görüntüle (İçe Aktarım)
POST	`/v1/import/sources/{id}/install`	Kaynağı kliniğe kurar	`imports:write`	Kur
PUT	`/v1/import/sources/{id}/install`	Kayıtlı bağlantı bilgilerini değiştirir	`imports:write`	Güncelle
DELETE	`/v1/import/sources/{id}/install`	Kaynağın kurulumunu kaldırır	`imports:write`	Kaldır
POST	`/v1/import/sources/{id}/start`	Aktarım işi başlatır	`imports:write`	Başlat
GET	`/v1/import`	Aktarım geçmişini listeler	`imports:read`	Görüntüle (İçe Aktarım)
GET	`/v1/import/{id}`	İşin ayrıntısını, toplamlarını ve tür özetini getirir	`imports:read`	İçe Aktarım Detayı
GET	`/v1/import/{id}/errors`	İşin hata kayıtlarını listeler	`imports:read`	İçe Aktarım Detayı
GET	`/v1/import/{id}/skips`	İşin atlanan kayıtlarını listeler	`imports:read`	İçe Aktarım Detayı
POST	`/v1/import/{id}/cancel`	Çalışan işi iptal eder	`imports:write`	İptal Et
GET	`/v1/import/sources/{id}/sync-states`	Kaynağın tür başına eşitleme durumunu getirir	`imports:read`	Görüntüle (İçe Aktarım)

Yetkisiz isteklere 403 FORBIDDEN, geçersiz gövdeye 422 VALIDATION_FAILED döner. Liste endpoint’leri sayfalıdır. Bkz. Sayfalama.

Hata kodları

Kod	HTTP	Ne zaman
`IMPORT_SOURCE_INACTIVE`	422	Aktif olmayan kaynağı kurmaya veya başlatmaya çalıştınız.
`IMPORT_SOURCE_ALREADY_INSTALLED`	422	Kaynak bu klinik için zaten kurulu.
`IMPORT_SOURCE_NOT_INSTALLED`	422	Kurulu olmayan kaynakta güncelleme, kaldırma veya başlatma denediniz.
`IMPORT_SOURCE_OAUTH_NOT_SUPPORTED`	422	OAuth gerektiren kaynak API üzerinden kurulamaz.
`IMPORT_TYPE_NOT_AVAILABLE`	422	`types` içinde kaynağın sunmadığı bir tür var.
`IMPORT_JOB_ALREADY_RUNNING`	409	Aynı kaynak için `Bekliyor` veya `İşleniyor` durumunda bir iş var.
`IMPORT_JOB_NOT_CANCELLABLE`	422	İş zaten `Tamamlandı`, `Başarısız` veya `İptal Edildi`.
`IMPORT_START_FAILED`	422	İş oluşturulurken beklenmeyen bir hata oluştu. İleti genel kalır.
`RESOURCE_NOT_FOUND`	404	Kaynak veya iş bulunamadı. Başka bir kliniğin işi de 404 döner.

Kaynaklar ve kurulum

Kaynakları listeleme

GET /v1/import/sources varsayılan olarak yalnızca aktif kaynakları döner.

Parametre	Açıklama
`search`	En çok 255 karakter.
`is_active`	Pasif kaynakları görmek için `false` verin.
`is_installed`	Yalnızca sizin klinik için kurulu olanlar (`true`) veya olmayanlar (`false`).
`sort_by`	`name` (varsayılan), `system_name`, `company_name`, `created_at`, `updated_at`.
`sort_order`	`asc` (varsayılan) veya `desc`.
`created_at_from`, `created_at_to`	Oluşturulma tarihi aralığı.

Sıralama kuralları için bkz. Filtreleme ve sıralama. Kaynak nesnesinin kurulum ve başlatma için önemli alanları:

Alan	Tür	Açıklama
`is_installed`, `installed_at`	boolean, tarih	Kaynak bu klinik için kurulu mu.
`available_types[]`	nesne dizisi	Başlatabileceğiniz türler: `value`, `label`, `description`, `supports_delta`.
`required_fields[]`	nesne dizisi	Kurulumda gereken alanlar: `key`, `label`, `type` (`url`, `text`, `password`), `required`, `is_configured`.
`modes[]`	nesne dizisi	`delta` (Sadece değişenler) ve `full` (Tam içe aktarma). `supported` ile desteklenip desteklenmediğini gösterir.
`options[]`	nesne dizisi	Başlatma seçenekleri. Yalnızca `skip_files_without_visit` vardır ve yalnızca `customer_file` sunan kaynakta (Stella) görünür.
`last_import_job`, `running_import_job`	nesne veya `null`	Bu kliniğin son ve çalışan işi.

GET /v1/import/types sabit katalogu döner ve bir kaynağın neyi sunduğunu söylemez. Başlatılabilir türler için kaynağın available_types alanına bakın.

Kurulum

POST /v1/import/sources/{id}/install gövdesinde fields nesnesi zorunludur. Kaynağın required_fields listesindeki her anahtar zorunlu bir metindir (en çok 1000 karakter). Listede olmayan anahtarlar sessizce yok sayılır. Başarılı kurulum 201 döner.

curl -X POST "https://app.flextell.ai/api/v1/import/sources/123/install" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "base_url": "https://<kaynak-adresi>",
      "username": "<kullanici_adi>",
      "password": "<sifre>",
      "api_key": "<api_key>"
    }
  }'

Kurulum bağlantıyı denemez. Yanlış bilgiler ancak bir iş çalışınca ortaya çıkar ve iş Başarısız olur. Bilgileri PUT .../install ile düzeltebilirsiniz.

Bağlantı bilgileri şifreli saklanır. API değerleri hiçbir zaman geri vermez. Yalnızca is_configured alanı bir değerin kayıtlı olup olmadığını söyler.
PUT .../install bilgileri birleştirmez, tamamen değiştirir. Tüm required_fields anahtarlarını yeniden göndermelisiniz.
DELETE .../install bağlantı bilgilerini siler. Aktarım geçmişini, eşitleme durumunu ve aktarılan kayıtları silmez. Çalışan bir işi de iptal etmez. Kaynağı sonra yeniden kurarsanız önceki eşleşmeler korunur ve yeniden aktarım kayıtları çoğaltmaz, günceller.
Dr.DENTES için önce Dr.DENTES’ten API erişimi ve adresi almanız gerekir. Flextell sunucusunun IP adresini de Dr.DENTES API izin listesine ekletmelisiniz.

Aktarım işi

POST /v1/import/sources/{id}/start hemen 201 döner ve işi arka planda çalıştırır. İş pending durumunda başlar.

Alan	Zorunlu	Açıklama
`types`	Evet	En az bir veri türü. Aynı tür tekrarlanırsa tek sayılır. Her tür kaynağın `available_types` listesinde olmalı.
`mode`	Hayır	`delta` (varsayılan) veya `full`.
`options.skip_files_without_visit`	Hayır	`true` ise son ziyareti olmayan hastaların dosyaları atlanır. Yalnızca `types` içinde `customer_file` varken kullanılabilir.

curl -X POST "https://app.flextell.ai/api/v1/import/sources/123/start" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "types": ["user", "treatment", "customer", "appointment"],
    "mode": "full"
  }'

Aynı klinik ve kaynak için aynı anda yalnızca bir iş çalışabilir. Bekliyor veya İşleniyor durumundaki bir iş varken yeniden başlatırsanız 409 IMPORT_JOB_ALREADY_RUNNING alırsınız.

Çalışma sırası

Türler, seçim sırasına bakılmaksızın sabit bir sırayla ve tek tek çalışır. Böylece bağımlı kayıtlar kaynaklarından sonra gelir.

Sıra	Tür	Etiket
1	`user`	Kullanıcı
2	`treatment`	Tedavi
3	`product`	Ürün
4	`room`	Oda
5	`customer`	Hasta
6	`lead`	Lead
7	`customer_note`	Hasta Notu
8	`appointment`	Randevu
9	`bank_info`	Banka Hesabı
10	`sale`	Satış
11	`invoice`	Fatura
12	`accounting_transaction`	Muhasebe İşlemi
13	`customer_file`	Hasta Dosyaları

Hasta notu, randevu, satış, fatura ve muhasebe işlemi kayıtları ilgili hastanın aktarılmış olmasına bağlıdır. Hasta türünü bu türlerden önce veya aynı işte seçin.

İlerlemeyi okuma

İçe aktarma bildirim, webhook veya gerçek zamanlı olay göndermez. İlerlemeyi GET /v1/import/{id} ile sorgulayın. Sorgu aralığını makul tutun. Bkz. Oran sınırları.

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

Yanıt import_job, aggregate ve type_summary alanlarını içerir.

Alan	Açıklama
`status`, `status_label`	İş durumu. Bkz. Durumlar.
`total_records`, `processed_records`	Toplam ve işlenen kayıt sayısı.
`successful_records`, `failed_records`, `skipped_records`	Başarılı, hatalı ve atlanan kayıt sayısı. İşlenen = başarılı + hatalı + atlanan.
`progress_percentage`	İşlenen / toplam, yüzde olarak.
`throughput`, `eta_seconds`, `elapsed_seconds`	Hız, tahmini kalan süre ve geçen süre. Hız hesaplanamıyorsa `eta_seconds` `null` olur.
`errors_count`, `skips_count`	Alt işler dahil hata ve atlanan sayısı.
`can_be_cancelled`	İş iptal edilebilir mi.
`is_stalled`	İş `İşleniyor` durumunda ve 5 dakikadan uzun süredir etkinlik yok.
`error_message`	İş başarısız olduysa nedeni.
`children[]`, `type_summary[]`	Her veri türü için ayrı bir alt iş ve özet.

aggregate, alt işlerin toplamıdır.
customer_file türünde processed_records ve total_records hastaları, başarılı, hatalı ve atlanan sayıları dosyaları sayar.
Alt iş numarasıyla sorgularsanız yanıt ana işi döner. Başka kliniğin işi 404 verir.

Geçmiş

GET /v1/import yalnızca ana işleri listeler.

Parametre	Açıklama
`status`	`pending`, `processing`, `completed`, `failed`, `cancelled`.
`import_source_id`, `user_id`	Kaynağa veya başlatan kullanıcıya göre süzer.
`started_at_from`, `started_at_to`	Başlangıç tarihi aralığı.
`created_at_from`, `created_at_to`	Oluşturulma tarihi aralığı. `_to` değeri `_from` değerinden önce olamaz.
`sort_by`	`created_at` (varsayılan), `started_at`, `completed_at`, `status`, `total_records`, `processed_records`.
`sort_order`	`desc` (varsayılan) veya `asc`.

Metin araması yoktur. Tarih süzgeçleri klinik saat dilimine göre yorumlanır.

İptal

POST /v1/import/{id}/cancel ana işi ve bekleyen alt işleri iptal eder. İptal geri almaz. Şu an işlenen sayfa tamamlanır ve o ana kadar aktarılan kayıtlar kalır. Tamamlanmış, başarısız veya iptal edilmiş iş için 422 IMPORT_JOB_NOT_CANCELLABLE döner.

Durumlar

`status`	`status_label`	Anlamı
`pending`	Bekliyor	İş oluşturuldu, henüz başlamadı. Sırası gelmemiş alt işler de bu durumdadır.
`processing`	İşleniyor	Çalışıyor.
`completed`	Tamamlandı	Hiçbir alt iş bekleyen veya çalışan durumda değil.
`failed`	Başarısız	Ölümcül bir hata oluştu. Neden `error_message` içindedir.
`cancelled`	İptal Edildi	Bir kullanıcı iptal etti.

Bir alt iş Başarısız olsa bile ana iş Tamamlandı olabilir. Yalnızca status alanına güvenmeyin. failed_records ve type_summary[].status değerlerini de kontrol edin.

İşleniyor durumundaki bir işte 15 dakikadan uzun süre etkinlik olmazsa Flextell işi Başarısız yapar. Tamamlanmış, başarısız veya iptal edilmiş bir iş yeniden başlamaz. Yeni bir iş başlatmanız gerekir.

Hatalar ve atlananlar

Satır düzeyindeki sorunlar işi durdurmaz. Flextell sorunlu kaydı kaydeder ve sıradaki kayıtla devam eder. Bu kayıtlar iki ayrı listede toplanır ve alt işler dahil tüm işi kapsar.

Panelde hata ve atlanan kayıt ekranı yoktur. Bu listelere yalnızca API ile ulaşırsınız.

Hatalar

GET /v1/import/{id}/errors

Parametre	Açıklama
`error_type`	Tam eşleşme. Değerler: `import` (satır işlenemedi), `api` (kaynak API çağrısı başarısız).
`created_at_from`, `created_at_to`	Tarih aralığı.
`sort_order`	`created_at` üzerinden, varsayılan `desc`.
`per_page`, `page`	`per_page` 1 ile 100 arası.

Her kayıt: id, import_job_id, error_type, error_message, row_data (kaynaktaki ham satır), created_at.

Atlananlar

GET /v1/import/{id}/skips

Parametre	Açıklama
`reason`	Tam eşleşme, aşağıdaki kodlardan biri.
`model_type`	Tam eşleşme. Atlanan kaydın Flextell’deki model türü.
`created_at_from`, `created_at_to`, `sort_order`, `per_page`, `page`	Hatalarla aynı.

Her kayıt: id, import_job_id, external_id (kaynaktaki kayıt kimliği), model_type, reason, data (ham satır), created_at.

`reason`	Kaynak	Anlamı
`missing_phone`	Stella hasta	Yeni hastanın telefonu yok.
`customer_not_found`	Stella hasta notu, fatura, muhasebe işlemi	Hasta daha önce aktarılmamış. `customer` türünü çalıştırın.
`empty_note_content`	Stella hasta notu	Not metni boş.
`missing_customer_mapping`	Stella randevu, satış; Dr.DENTES randevu	Hasta eşleşmedi veya kaynaktan alınamadı.
`account_not_found`	Stella muhasebe işlemi	Hesap eşleşmesi yok.
`customer_id_missing`	Stella fatura	Faturada hasta kimliği yok.
`stella_record_unreachable_5xx`	Stella fatura	Stella o dilim için 5xx döndü.
`missing_url`	Stella dosya	Dosyanın adresi yok.
`no_recorded_visit`	Stella dosya	`skip_files_without_visit` açıkken hastanın ziyareti yok.
`missing_email`, `missing_name`	Dr.DENTES hekim	Hekimin e-postası veya adı yok.
`missing_patient`	Dr.DENTES randevu	Hasta kartı yok ve randevuda telefon yok.

Yeniden aktarım davranışı

Kaynaktaki her kayıt Flextell kaydıyla eşlenir. Yeniden aktarımda eşleşen kayıt güncellenir, eşleşmeyen oluşturulur ya da doğal anahtarla bulunur.
Telefon numarası başka bir hastada kullanılıyorsa yeni hasta telefonsuz kaydedilir ve numara adres alanına Telefon No: ... olarak eklenir.
Stella’dan gelen tedaviler fiyat 0 ve pasif olarak yazılır. Yeniden aktarım bu alanları yine bu değerlere döndürür.
Aktarılan kayıtların detay yanıtında import_source (id, name, company_logo) alanı bulunur. Panel bu alanla İçe Aktarılmış Kayıt bilgisini gösterir.

Eşitleme

Sadece değişenler (delta) modu, son aktarımdan sonra kaynakta değişen kayıtları getirir. Tam içe aktarma (full) süzgeç uygulamadan tüm kayıtları yeniden tarar.

Stella’da yalnızca customer, appointment, sale, customer_note, accounting_transaction ve invoice türleri delta destekler. Diğer türler her zaman tam okunur. Kaynak nesnesindeki available_types[].supports_delta bunu türe göre gösterir.
Dr.DENTES hiçbir türde delta desteklemez. Her çalışma tam eşitlemedir. Kayıtlar eşleştiği için yinelenmez.

GET /v1/import/sources/{id}/sync-states yalnızca sizin kliniğinizin eşitleme durumunu, type sırasına göre döner. Yalnızca delta destekleyen türler için kayıt oluşur.

Alan	Tür	Açıklama
`type`, `type_label`	metin	Veri türü ve etiketi.
`last_synced_at`	tarih	Türün en son tamamlandığı zaman.
`last_synced_max_modified_at`	tarih	Kaynakta görülen en yeni değişiklik zamanı. Yalnızca ileri gider. Sonraki `delta` çalışması buradan devam eder.
`last_synced_record_count`	sayı	Son tamamlanan çalışmada başarılı kayıt sayısı.

Her kaydı yeniden taramak istediğinizde mode değerini full verin. Eşleşmiş kayıtlar yinelenmez, güncellenir.

İlgili sayfalar

İçe aktarma (panel)

Aynı işlemleri panelde yapın.

Scope'lar

imports:read ve imports:write scope’ları.

İzinler ve görünürlük

İçe aktarma izinlerinin rollere dağılımı.

Hata kodları

Ortak hata kodları ve yanıt biçimi.

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

Endpoint özeti

Hata kodları

Kaynaklar ve kurulum

Kaynakları listeleme

Kurulum

Aktarım işi

Çalışma sırası

İlerlemeyi okuma

Geçmiş

İptal

Durumlar

Hatalar ve atlananlar

Hatalar

Atlananlar

Yeniden aktarım davranışı

Eşitleme

İlgili sayfalar

İçe aktarma (panel)

Scope'lar

İzinler ve görünürlük

Hata kodları

​Endpoint özeti

​Hata kodları

​Kaynaklar ve kurulum

​Kaynakları listeleme

​Kurulum

​Aktarım işi

​Çalışma sırası

​İlerlemeyi okuma

​Geçmiş

​İptal

​Durumlar

​Hatalar ve atlananlar

​Hatalar

​Atlananlar

​Yeniden aktarım davranışı

​Eşitleme

​İlgili sayfalar

İçe aktarma (panel)

Scope'lar

İzinler ve görünürlük

Hata kodları

Endpoint özeti

Hata kodları

Kaynaklar ve kurulum

Kaynakları listeleme

Kurulum

Aktarım işi

Çalışma sırası

İlerlemeyi okuma

Geçmiş

İptal

Durumlar

Hatalar ve atlananlar

Hatalar

Atlananlar

Yeniden aktarım davranışı

Eşitleme

İlgili sayfalar