> ## 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.

# İçe aktarma

> İçe aktarma kaynaklarını kurmayı, aktarım işi başlatmayı ve ilerlemeyi, hataları ve atlananları okumayı anlatır.

İç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.

<Note>
  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.
</Note>

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)](/panel/baglantilar/ice-aktarma).

## 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](/api/klinikler-ve-x-tenant) ve [scope'lar](/api/kimlik-dogrulama/scopelar).

| 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](/api/istekler/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](/api/istekler/filtreleme-ve-siralama).

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. |

<Info>
  `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.
</Info>

### 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.

```bash theme={null}
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>"
    }
  }'
```

<Warning>
  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.
</Warning>

* 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. |

```bash theme={null}
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ı](/api/istekler/oran-sinirlari).

```bash theme={null}
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](#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. |

```mermaid theme={null}
flowchart LR
  A[Bekliyor] --> B[İşleniyor]
  B --> C[Tamamlandı]
  B --> D[Başarısız]
  A --> E[İptal Edildi]
  B --> E
```

<Warning>
  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.
</Warning>

İş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.

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

### 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ı. |

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

## İlgili sayfalar

<CardGroup cols={2}>
  <Card title="İçe aktarma (panel)" icon="plug" href="/panel/baglantilar/ice-aktarma">
    Aynı işlemleri panelde yapın.
  </Card>

  <Card title="Scope'lar" icon="key" href="/api/kimlik-dogrulama/scopelar">
    `imports:read` ve `imports:write` scope'ları.
  </Card>

  <Card title="İzinler ve görünürlük" icon="shield" href="/api/izinler-ve-gorunurluk">
    İçe aktarma izinlerinin rollere dağılımı.
  </Card>

  <Card title="Hata kodları" icon="triangle-alert" href="/api/istekler/hata-kodlari">
    Ortak hata kodları ve yanıt biçimi.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.