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

# Hesaplar, işlemler ve bakiyeler

> Banka ve kasa hesaplarını, hesap hareketlerini, hasta işlemlerini, bakiyeleri ve ödeme yöntemlerini anlatır.

Flextell iki defter tutar. Birincisi kliniğin kendi **hesaplarıdır** (banka ve kasa) ve bu hesaplardaki **hesap hareketleridir**. İkincisi her Hastanın **hasta işlemleridir**: Hastanın size ne kadar borçlu olduğunu ya da ne kadar ödediğini gösterir. Bu iki defterden **bakiyeler** hesaplanır: kimin ne kadar açık borcu olduğu.

Bir Hastadan tahsilat aldığınızda ya da Hastaya ödeme yaptığınızda iki deftere de birer satır yazılır. Bu iki satır aynı `batch_uuid` değerini taşır ve **eşleştirilmiş işlem** sayılır.

Satışa bağlı ödemeler `sales` kaynağındadır ([Satışlar](/api/kaynaklar/satislar)). Uçtan uca akış için [Satış, tahsilat ve fatura rehberi](/api/rehberler/satis-tahsilat-fatura) sayfasına bakın.

<Info>
  Tüm istekler `Authorization: Bearer <access_token>` ve `X-Tenant: <tenant_id>` başlıklarını taşır. Endpoint özetindeki "İzin" sütunu "Yok" olmayan her endpoint hem scope hem izin ister; "Yok" olanlar yalnızca scope ister. Birden fazla scope listelenmişse hepsi gerekir. Scope'lar için [Scope'lar](/api/kimlik-dogrulama/scopelar) sayfasına bakın.
</Info>

## Endpoint özeti

| Metot | Endpoint | Açıklama | Scope | İzin |
| - | - | - | - | - |
| `GET` | `/api/v1/bank-accounts` | Hesapları listeler. | `bank_accounts:read` | `View:Account` |
| `POST` | `/api/v1/bank-accounts` | Hesap oluşturur. | `bank_accounts:write` | `Create:Account` |
| `GET` | `/api/v1/bank-accounts/{id}` | Hesap detayını getirir. | `bank_accounts:read` | `View:Account` |
| `PUT` | `/api/v1/bank-accounts/{id}` | Hesabı günceller. | `bank_accounts:write` | `Update:Account` |
| `DELETE` | `/api/v1/bank-accounts/{id}` | Hesabı siler. | `bank_accounts:write` | `Delete:Account` |
| `GET` | `/api/v1/bank-accounts/{accountId}/transactions` | Hesabın hareketlerini listeler. | `bank_accounts:read`, `account_transactions:read` | `View:AccountTransaction` |
| `POST` | `/api/v1/bank-accounts/{accountId}/transactions` | Hesap hareketi oluşturur. | `bank_accounts:write`, `account_transactions:write` | `Create:AccountTransaction` |
| `GET` | `/api/v1/bank-accounts/{accountId}/transactions/{transactionId}` | Tek bir hareketi getirir. | `bank_accounts:read`, `account_transactions:read` | `View:AccountTransaction` |
| `PUT` | `/api/v1/bank-accounts/{accountId}/transactions/{transactionId}` | Hareketi günceller. | `bank_accounts:write`, `account_transactions:write` | `Update:AccountTransaction` |
| `DELETE` | `/api/v1/bank-accounts/{accountId}/transactions/{transactionId}` | Hareketi siler. | `bank_accounts:write`, `account_transactions:write` | `Delete:AccountTransaction` |
| `POST` | `/api/v1/bank-accounts/{accountId}/transactions/bulk-delete` | Birden fazla hareketi siler. | `bank_accounts:write`, `account_transactions:write` | `Delete:AccountTransaction` |
| `GET` | `/api/v1/customers/{id}/transactions` | Hastanın işlemlerini listeler. | `customers:read`, `customer_transactions:read` | `View:CustomerTransaction` |
| `POST` | `/api/v1/customers/{id}/transactions` | Hasta işlemi oluşturur. | `customers:write`, `customer_transactions:write` | `Create:CustomerTransaction` |
| `GET` | `/api/v1/customers/{id}/transactions/{transactionId}` | Tek bir işlemi getirir. | `customers:read`, `customer_transactions:read` | `View:CustomerTransaction` |
| `PUT` | `/api/v1/customers/{id}/transactions/{transactionId}` | İşlemi günceller. | `customers:write`, `customer_transactions:write` | `Update:CustomerTransaction` |
| `DELETE` | `/api/v1/customers/{id}/transactions/{transactionId}` | İşlemi siler. | `customers:write`, `customer_transactions:write` | `Delete:CustomerTransaction` |
| `GET` | `/api/v1/customer-balances` | Açık bakiyesi olan Hastaları listeler. | `customers:read`, `customer_transactions:read` | `View:CustomerBalances` |
| `GET` | `/api/v1/customer-balances/{id}` | Bir Hastanın bakiyesini getirir. | `customers:read`, `customer_transactions:read` | `View:CustomerBalances` |
| `GET` | `/api/v1/customer-balances/export` | Bakiye listesinin dışa aktarımını başlatır. | `customers:read`, `customer_transactions:read` | `Export:CustomerBalances` |
| `GET` | `/api/v1/payment-methods` | Ödeme yöntemlerini listeler. | `payment_methods:read` | Yok |
| `GET` | `/api/v1/account-transaction-types` | Hesap hareketi türlerini listeler. | `account_transactions:read` | Yok |

Başka bir kliniğin kaydına erişmeye çalışırsanız `404 RESOURCE_NOT_FOUND` döner.

## Genel kurallar

<AccordionGroup>
  <Accordion title="Tutarlar">
    Tutarlar yanıtta her zaman nokta ondalıklı, binlik ayırıcısız metin olarak gelir: `"1234.50"`. İstekte Türkçe biçimi de kabul edilir (`15.000,50` değeri 15000.50 olur).
  </Accordion>

  <Accordion title="Tarihler">
    `transaction_date` ofsetsiz gönderilirse klinik saat diliminde okunur. Yanıtta klinik saatinde, ofsetli ISO 8601 olarak döner (`2026-10-12T14:30:00+03:00`). `_from` ve `_to` filtreleri klinik saatine göre tam gün sınırlarıdır. Okunamayan tarih `422` döner.
  </Accordion>

  <Accordion title="Silme">
    Hesaplar ve iki tür işlem de kalıcı silinir. Silinenler Geri Dönüşüm Kutusu'na gitmez.
  </Accordion>

  <Accordion title="Doğrulama mesajları">
    Bazı doğrulama mesajları (örneğin hasta işlemindeki `payment_method`, `debit_credit_code`, `amount`, `is_installment`, `installments` alanları ve hesap güncellemedeki `currency_id`) Türkçe istekte bile İngilizce dönebilir. Mesaj metnine değil `error_code` alanına dayanın.
  </Accordion>
</AccordionGroup>

Listeler `{data, links, meta}` biçiminde döner ([Yanıt yapısı](/api/istekler/yanit-yapisi), [Sayfalama](/api/istekler/sayfalama)). `sort_by` değeri `sort_order` olmadan gönderilirse metin sütunları A'dan Z'ye, sayı ve tarih sütunları azalan sıralanır ([Filtreleme ve sıralama](/api/istekler/filtreleme-ve-siralama)).

## Hesaplar

Hesap (API adıyla `bank account`) kliniğin banka hesabı ya da kasasıdır. Her hesabın tek bir para birimi vardır.

### Hesap nesnesi

| Alan | Tür | Açıklama |
| - | - | - |
| `id`, `tenant_id` | integer | Hesap ve klinik kimliği. |
| `name` | string | Hesap adı. |
| `account_number`, `bank_name`, `branch_name` | string \| null | Hesap numarası, banka adı, şube adı. |
| `swift`, `iban` | string \| null | Boşluklar silinir, harfler büyütülür. |
| `currency` | object | `id`, `code`, `symbol`, `name`. |
| `debit` | string | Hesaba giren toplam tutar. |
| `credit` | string | Hesaptan çıkan toplam tutar. |
| `balance` | string | `debit - credit`. Sistem hesaplar, siz göndermezsiniz. |
| `is_default` | boolean | Varsayılan hesap. |
| `is_active` | boolean | Hesap aktif mi. |
| `import_source` | object \| null | Hesap dışarıdan içe aktarıldıysa kaynak sistem (`id`, `name`, `company_logo`). Liste yanıtında bulunmaz. |
| `created_at`, `updated_at` | string | Zaman damgaları. |

`debit` ve `credit` toplamları hesabın kendi para biriminde, kur uygulanmadan hesaplanır.

### Listeleme

| Parametre | Açıklama |
| - | - |
| `search` | Ad, banka adı, IBAN ve hesap numarasında arar (en çok 255 karakter). |
| `is_active`, `is_default` | Boolean süzgeçler. |
| `currency_id` | Para birimine göre süzer. |
| `sort_by` | `name`, `is_default`, `is_active`, `created_at`, `updated_at`. Varsayılan: `created_at`, azalan. |
| `per_page` | 1 ile 100 arası. Varsayılan 15. |

### Oluşturma ve güncelleme

| Alan | Zorunlu | Kural |
| - | - | - |
| `name` | Evet | En çok 255 karakter. |
| `currency_id` | Evet | Aktif bir para birimi. Oluşturduktan sonra değiştirilemez; güncellemede gönderirseniz `422` döner. |
| `account_number`, `bank_name`, `branch_name` | Hayır | En çok 255 karakter. |
| `iban` | Hayır | En çok 34 karakter. İki harfli ülke kodu ve iki rakamla başlar. `TR` ile başlıyorsa `TR` ve 24 rakam olmalıdır. Sağlama toplamı denetlenmez. |
| `swift` | Hayır | 8 veya 11 karakter. 5. ve 6. karakter harf olmalıdır. |
| `is_default` | Hayır | Varsayılan hesap yapar. |
| `is_active` | Hayır | Varsayılan: `true`. |
| `opening_balance` | Hayır | 0 ile 9999999999999.99 arası, en çok 2 ondalık. Yalnızca oluştururken. |
| `opening_balance_direction` | Hayır | `debit` veya `credit`. Varsayılan: `debit`. Yalnızca oluştururken. |

`201` ile hesabı döner. Güncelleme kısmidir: yalnızca gönderdiğiniz alanlar değişir. Mevcut IBAN veya SWIFT değerini değiştirmeden aynen gönderirseniz geçersiz olsa bile kabul edilir.

<Note>
  `opening_balance` sıfırdan büyükse hesap oluşturulurken aynı işlemde `Açılış bakiyesi` açıklamalı bir `opening_balance` hareketi yazılır. Hesap toplamları bu hareketi zaten içerir.
</Note>

### Varsayılan hesap

Her klinikte tek bir varsayılan hesap bulunur. İlk oluşturduğunuz hesap otomatik varsayılan olur. Yeni bir hesabı `is_default: true` ile oluşturursanız ya da `PUT` ile `is_default: true` gönderirseniz önceki varsayılan hesap bu işareti kaybeder.

Aktif olmayan hesap varsayılan olamaz. `is_default: true` olan hesaba `is_active: false` göndermek ya da aktif olmayan hesabı varsayılan yapmak `422 BANK_ACCOUNT_UPDATE_BLOCKED` döner. Varsayılan hesabı pasife almadan önce başka bir hesabı varsayılan yapın.

### Silme

`DELETE /api/v1/bank-accounts/{id}` yalnızca hiç hareketi olmayan hesabı siler. Hareketi olan hesap için `422 BANK_ACCOUNT_HAS_TRANSACTIONS` döner. Önce hareketleri silin (`bulk-delete` ile `all: true` gönderebilirsiniz).

## Hesap hareketleri

Hesap hareketi, bir hesaba para girişini ya da çıkışını kaydeder. `debit` para girişi, `credit` para çıkışıdır.

### Hareket türleri

`GET /api/v1/account-transaction-types` bu listeyi `{value, label}` çiftleriyle döner. Etiketler her zaman Türkçedir.

| `type` | Etiket | Taraf |
| - | - | - |
| `collection` | Tahsilat | `debit` (giriş), sabit. |
| `payment` | Ödeme | `credit` (çıkış), sabit. |
| `transfer` | Transfer | `direction` ile seçilir. Oluştururken varsayılan `debit`. |
| `bank_commission` | Banka Komisyonu | `credit`, sabit. |
| `opening_balance` | Açılış Bakiyesi | `direction` ile seçilir. Varsayılan `debit`. |

### Hareket nesnesi

| Alan | Tür | Açıklama |
| - | - | - |
| `id`, `tenant_id`, `account_id` | integer | Kimlikler. |
| `account` | object | `id`, `name`. |
| `batch_uuid` | string \| null | Yalnızca eşleştirilmiş işlemlerde dolu. |
| `currency_id`, `currency` | integer, object | Hesabın para birimi. |
| `exchange_rate` | number | Varsayılan 1. |
| `debit`, `credit` | string | Giriş ve çıkış tutarı. |
| `amount` | string | `debit - credit`. Para çıkışında negatiftir. |
| `transaction_date` | string | Klinik saatinde, ofsetli ISO 8601. |
| `type` | string | Hareket türü. |
| `payment_method` | string \| null | Ödeme yöntemi. |
| `description`, `invoice_number` | string \| null | Açıklama ve fatura numarası. |
| `customer` | object \| null | Eşleştirilmiş Hasta: `id`, `first_name`, `last_name`, `phone_number`, `email`, `is_masked`, `is_lead_stage`, `lead_id`, `record_state`. Hastasız harekette `null`. |
| `record_state` | object | `is_read_only` ve `reason_code`. |
| `created_at`, `updated_at` | string | Zaman damgaları. |

Hasta Geri Dönüşüm Kutusu'nda olsa bile `customer` döner. Atanmamış bir lead'in Hastasında kimlik alanları maskelenir.

### Listeleme

| Parametre | Açıklama |
| - | - |
| `search` | Açıklama ve fatura numarasında arar. |
| `type`, `payment_method`, `currency_id` | Süzgeçler. |
| `transaction_date_from`, `transaction_date_to` | Klinik saatine göre tam gün aralığı. |
| `sort_by` | `transaction_date`, `created_at`, `debit`, `credit`. Varsayılan: `transaction_date`, azalan. |
| `per_page` | En çok 100. |

### Oluşturma

| Alan | Zorunlu | Kural |
| - | - | - |
| `type` | Evet | Hareket türü. |
| `amount` | Evet | En az 0.01. |
| `transaction_date` | Evet | Ofsetsizse klinik saatinde okunur. |
| `direction` | Hayır | `debit` veya `credit`. Boşsa türün varsayılan tarafı kullanılır. |
| `payment_method` | `collection` ve `payment` için evet | Ödeme yöntemi değeri. |
| `currency_id` | Hayır | Verirseniz hesabın para birimiyle aynı olmalıdır. Varsayılan: hesabın para birimi. |
| `exchange_rate` | Hayır | 0 veya üzeri. Varsayılan 1. |
| `description` | Hayır | Serbest metin. |
| `invoice_number` | Hayır | En çok 255 karakter. |
| `customer_id` | Hayır | Kliniğe ait Hasta. |

`type` değeri `collection` veya `payment` ise ve `customer_id` gönderdiyseniz Flextell aynı `batch_uuid` ile iki satır yazar ve hesap satırını döner:

| `type` | Hasta işlemi | Hesap hareketi |
| - | - | - |
| `collection` | Hasta `credit` (borç azalır) | Hesap `debit` (para girer) |
| `payment` | Hasta `debit` (borç artar) | Hesap `credit` (para çıkar) |

`customer_id` göndermezseniz hareket yalnızca hesaba yazılır. Yanıt `201` ve hareket nesnesidir.

### Güncelleme

`PUT` kısmidir. `amount` ile `debit` ya da `credit` birlikte gönderilemez. `amount` gönderirseniz tutar `direction` tarafına, yeni `type` değerinin sabit tarafına ya da mevcut tarafa yazılır. Yalnızca `direction` değiştirirseniz mevcut tutar öbür tarafa taşınır. `type` değerini `transfer` veya `opening_balance` yaparsanız mevcut taraf korunur.

<Warning>
  Eşleştirilmiş bir harekette yalnızca `description`, `invoice_number`, `payment_method` ve `transaction_date` değişir; değişiklik Hastanın satırına da yansır. Başka bir alan (`amount`, `direction`, `type`, `debit` dahil) göndermek `422 PAIRED_TRANSACTION_IMMUTABLE` döner. Tutarı düzeltmek için hareketi silip yeniden oluşturun.
</Warning>

### Silme

`DELETE` isteğinde `delete_related_transactions` parametresi varsayılan olarak `true`'dur: aynı `batch_uuid` değerini taşıyan Hasta satırları da silinir. `false` gönderirseniz Hasta satırı kalır ve Hastanın bakiyesi hesapla uyuşmaz.

`POST .../transactions/bulk-delete` ile tek istekte silme yapılır. İki biçimden birini gönderin:

| Alan | Açıklama |
| - | - |
| `transaction_ids` | 1 ile 100 arası farklı kimlik. Hepsi bu hesaba ait olmalıdır. |
| `all` | `true` ise hesabın tüm hareketleri silinir. `transaction_ids` ile birlikte gönderilemez. |

Yanıt `{success, data: {deleted_count}}` olur. İşlem ya hepsi ya hiçbiri çalışır: seçimden biri verileri imha edilmiş bir Hastayla ya da size atanmamış bir lead ile eşleşiyorsa hiçbir hareket silinmez ve `422 ACCOUNT_TRANSACTION_NOT_DELETABLE` yanıtının `data.transaction_ids` alanı reddedilen kimlikleri listeler. Eşleştirilmiş Hasta satırları seçimle birlikte silinir.

## Hasta işlemleri

Hasta işlemi, Hastanın cari hesabındaki satırdır. Hastanın bakış açısıyla yazılır: `debit` Hastanın borcunu artırır (satış, Hastaya ödeme), `credit` azaltır (tahsilat, alış fişi).

### İşlem türleri

| `type` | Etiket | Oluşturulduğu taraf |
| - | - | - |
| `sale_invoice` | Satış Faturası | `debit`. Taksitlendirilebilir. |
| `sale` | Satış | `debit` |
| `collection` | Tahsilat | `credit` |
| `purchase_invoice` | Alış Fiş/Fatura | `credit` |
| `payment` | Ödeme | `debit` (Hastaya yapılan iade gibi) |
| `opening_balance` | Açılış Bakiyesi | `debit_credit_code` belirler. Varsayılan `debit`. |

### İşlem nesnesi

| Alan | Tür | Açıklama |
| - | - | - |
| `id`, `tenant_id`, `customer_id` | integer | Kimlikler. |
| `batch_uuid` | string | Eşleştirilmiş satırları ve taksit kardeşlerini gruplar. |
| `account_id`, `account` | integer, object | Kullanılan hesap (`id`, `name`). Hesapsız işlemde `null`. |
| `sale_id` | integer \| null | İşlem bir satıştan geliyorsa satış kimliği. |
| `currency_id`, `currency` | integer, object | Para birimi. |
| `exchange_rate` | number | Baz para birimine kur. |
| `debit`, `credit`, `amount` | string | `amount` = `debit - credit`. |
| `transaction_date` | string | Klinik saatinde, ofsetli ISO 8601. |
| `type`, `payment_method` | string | İşlem türü ve ödeme yöntemi. |
| `description`, `invoice_number` | string \| null | Açıklama ve fatura numarası. |
| `is_installment` | boolean | Taksit satırı mı. |
| `due_date` | string \| null | Vade tarihi, `Y-m-d`. |
| `installment_number`, `total_installments` | integer | Taksit sırası ve sayısı. |
| `record_state` | object | `is_read_only`, `reason_code`. |
| `created_at`, `updated_at` | string | Zaman damgaları. |

### Listeleme

`search` açıklama ve fatura numarasında alt metin olarak arar. `type` ve `currency_id` süzer. `sort_by` değerleri: `transaction_date` (varsayılan, azalan), `created_at`, `debit`, `credit`, `due_date`, `invoice_number`, `amount`, `account`. `amount` sıralaması `debit - credit` farkına, `account` hesap adına göredir.

### Oluşturma

| Alan | Zorunlu | Kural |
| - | - | - |
| `type` | Evet | İşlem türü. |
| `transaction_date` | Evet | Ofsetsizse klinik saatinde okunur. |
| `amount` | Evet (taksit listesi yoksa) | En az 0.01. |
| `payment_method` | `collection` ve `payment` için evet | Ödeme yöntemi değeri. |
| `debit_credit_code` | `opening_balance` için evet | Yön. |
| `account_id` | Hayır | Kliniğin hesabı. Verirseniz eşleştirilmiş hesap hareketi de yazılır. |
| `currency_id`, `exchange_rate` | Hayır | Bkz. kurallar aşağıda. |
| `description`, `invoice_number` | Hayır | Serbest metin. |
| `is_installment`, `installments`, `installment_count`, `first_due_date` | Hayır | Yalnızca `sale_invoice`. Bkz. [Taksitler](#taksitler). |

`201` ile işlemi döner. `account_id` verdiğinizde `currency_id` hesabın para biriminden farklıysa Flextell hata vermez, para birimini hesabınkiyle değiştirir (hesap hareketi endpoint'inden farklı olarak). Hesap vermezseniz para birimi serbesttir. Para birimi göndermezseniz hesabın, hesap da yoksa kliniğin baz para birimi kullanılır. Baz para biriminde `exchange_rate` 1'e sabitlenir.

Lead aşamasındaki bir kayda mali işlem yazılamaz. Önce lead'i Hastaya dönüştürün ([Leadler](/api/kaynaklar/leadler)).

### Taksitler

Taksit yalnızca `sale_invoice` için kullanılır; başka türde `is_installment` göndermek `422` döner. İki yol vardır:

* **Açık liste:** `installments` içinde en az 2 öğe gönderin, her biri `amount`, `due_date` ve isteğe bağlı `description` taşır.
* **Otomatik:** `installment_count` (2 ile 12), `first_due_date` ve `amount` gönderin. Tutar eşit bölünür, son taksit kuruş farkını alır (100 / 3 için 33.33, 33.33, 33.34). Vadeler `first_due_date` tarihinden başlayarak aylıktır.

Her taksit ayrı bir `debit` satırıdır; hepsi tek `batch_uuid` paylaşır ve `installment_number` 1'den başlar. Yanıt yalnızca birinci taksiti döner.

### Güncelleme ve silme

`PUT` ile `type`, `debit`, `credit`, `currency_id`, `exchange_rate`, `transaction_date`, `due_date`, `description` ve `invoice_number` değişir. `amount` ve `payment_method` kabul edilmez.

Hesap hareketiyle eşleştirilmiş bir işlemde yalnızca `description`, `invoice_number` ve `transaction_date` değişir; değişiklik hesap satırına kopyalanır. Diğer alanlar `422 PAIRED_TRANSACTION_IMMUTABLE` döner. Eşleştirilmemiş işlemde her alan düzenlenebilir. `type` değiştirmek tutarları öbür tarafa taşımaz.

`DELETE` işleminde `delete_related_transactions` varsayılan `true`'dur ve aynı `batch_uuid` içindeki hesap satırları silinir; hesap toplamları güncellenir. Kardeş taksit satırları silinmez.

## Bakiyeler

Bakiye listesi, açık borcu olan Hastaları gösterir.

### Hesaplama

Bir Hastanın `outstanding_balance` değeri, tüm işlemlerinin `(debit - credit) × kur` toplamıdır. Kur 0 veya negatifse 1 sayılır. Para birimi boş olan eski satırlar baz para birimi sayılır. Liste yalnızca bakiyesi en az 0.01 olan Hastaları içerir; borcu kapanmış ya da alacaklı Hastalar listede yer almaz. Lead aşamasındaki kayıtlar hiç listelenmez.

`ViewAllCustomers:Customer` iznine sahip değilseniz yalnızca erişebildiğiniz Hastaların bakiyelerini görürsünüz ([İzinler ve görünürlük](/api/izinler-ve-gorunurluk)).

### Listeleme

| Parametre | Açıklama |
| - | - |
| `search` | Hasta adı, e-posta ve telefonda arar. |
| `balance_min`, `balance_max` | Bakiye aralığı. `balance_max`, `balance_min` değerinden küçük olamaz. |
| `latest_transaction_at_from`, `latest_transaction_at_to` | Son işlem tarihi aralığı (klinik saatine göre tam gün). |
| `sort` | `balance` (varsayılan, azalan), `latest_transaction_at` (azalan), `customer` (ad ve soyad, artan). |
| `direction` | `asc` veya `desc`. |
| `per_page` | En çok 100. |

<Note>
  Bu endpoint `sort_by` ve `sort_order` yerine `sort` ve `direction` kullanır.
</Note>

### Bakiye nesnesi

| Alan | Tür | Açıklama |
| - | - | - |
| `customer_id` | integer | Hasta kimliği. |
| `customer` | string | Hastanın adı ve soyadı. |
| `email`, `phone` | string \| null | İletişim bilgisi. |
| `latest_transaction_at` | string | Son mali işlemin zamanı. |
| `outstanding_balance` | string | Baz para biriminde açık bakiye. Negatif değer Hastanın alacağıdır. |
| `overdue_balance` | string | Vadesi geçmiş bakiye. Yalnızca detay yanıtında bulunur. |
| `currency_code` | string | Klinik baz para birimi. |
| `currency_balances` | array | Para birimine göre kırılım: `currency_code`, `currency_symbol`, `amount`, `base_amount`, `effective_exchange_rate`. Baz para birimi önce, yabancı para birimleri alfabetik gelir. |
| `record_state` | object | `is_read_only`, `reason_code`. |

Liste yanıtının `meta.totals` alanı filtreye uyan tüm satırların toplamını verir: `currency_code`, `outstanding_balance` ve `currency_balances`. Yabancı para birimi satırları yalnızca net bakiyesinin tamamı o tek para biriminde olan Hastaları sayar; karışık para birimli Hastalar yalnızca baz toplama girer.

`GET /api/v1/customer-balances/{id}` görebildiğiniz her Hasta için çalışır; açık bakiyesi olmayan Hasta için `outstanding_balance` `"0.00"`, `currency_balances` boş döner. `overdue_balance`, iptal edilmemiş her satış için ayrı hesaplanır: vadesi gelmiş satış borcundan tahsilatlar düşülür ve yalnızca pozitif net değerler toplanır. Fazla ödenmiş bir satış diğerlerinin borcunu azaltmaz.

### Dışa aktarma

`GET /api/v1/customer-balances/export` listedeki süzgeçleri kabul eder ve `format` parametresi alır: `excel` (varsayılan) veya `pdf`. `csv` gönderirseniz `422` döner. Dosya hemen dönmez. İstek `202` döner ve dosya hazır olunca indirme bağlantısı bildirimle gelir ([Bildirimler](/api/kaynaklar/bildirimler)).

Dışa aktarma `Export:CustomerBalances` ister; `View:CustomerBalances` gerekmez. Dışa aktarma isteği klinik ve kullanıcı başına saatte 10 ile sınırlıdır; aşarsanız `429` alırsınız ([Oran sınırları](/api/istekler/oran-sinirlari)).

## Ödeme yöntemleri

`GET /api/v1/payment-methods` yalnızca `payment_methods:read` scope'u ister, izin gerektirmez. Yanıt `{success, data: [{value, label}]}` biçimindedir ve sekiz satır içerir. `payment_method` alanlarına `value` değerini yazın.

| `value` | Etiket |
| - | - |
| `bank_account` | Banka Hesabı |
| `cash` | Nakit |
| `transfer_cash` | Devir Kasa |
| `other` | Diğer |
| `clinic_credit_card` | Kliniğe Ait Kredi Kartı |
| `credit_card` | Kredi Kartı |
| `private_insurance` | Özel Sigorta |
| `sgk` | SGK |

## Hata kodları

Genel hata yapısı için [Hatalar](/api/istekler/hatalar) ve [Hata kodları](/api/istekler/hata-kodlari) sayfalarına bakın.

| Kod | HTTP | Ne zaman |
| - | - | - |
| `VALIDATION_FAILED` | 422 | Alan doğrulaması başarısız. |
| `RESOURCE_NOT_FOUND` | 404 | Kayıt yok ya da başka bir kliniğe ait. |
| `BANK_ACCOUNT_UPDATE_BLOCKED` | 422 | Hesap hem varsayılan hem pasif olacak. |
| `BANK_ACCOUNT_HAS_TRANSACTIONS` | 422 | Hareketi olan hesap silinmek istendi. |
| `PAIRED_TRANSACTION_IMMUTABLE` | 422 | Eşleştirilmiş işlemin düzenlenemeyen bir alanı gönderildi. |
| `ACCOUNT_TRANSACTION_NOT_DELETABLE` | 422 | Toplu silmede seçimden en az biri silinemiyor. `data.transaction_ids` reddedilenleri listeler. |
| `TRANSACTION_CREATE_FAILED` | 422 | İşlem oluşturulurken beklenmeyen bir hata oluştu. |
| `CUSTOMER_ERASED` | 409 | İşlem, verileri imha edilmiş bir Hastaya ya da ona eşleşmiş bir satıra dokunuyor. Hiçbir değişiklik yapılmaz ([Veri imha talepleri](/api/kaynaklar/veri-imha-talepleri)). |
| `LEAD_NOT_ASSIGNED` | 403 | İşlem, size atanmamış bir lead'in Hastasına yazıyor. `data.assigned_user` atanan kullanıcıyı (`id`, `name`) ya da `null` döner. |

## Örnekler

<CodeGroup>
  ```bash Hesap oluşturma theme={null}
  curl -X POST "https://app.flextell.ai/api/v1/bank-accounts" \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Tenant: <tenant_id>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Ana TL Hesabı",
      "currency_id": 1,
      "bank_name": "Örnek Bank",
      "iban": "TR00 0000 0000 0000 0000 0000 00",
      "is_default": true,
      "opening_balance": 5000,
      "opening_balance_direction": "debit"
    }'
  ```

  ```bash Tahsilat kaydetme theme={null}
  curl -X POST "https://app.flextell.ai/api/v1/bank-accounts/12/transactions" \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Tenant: <tenant_id>" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "collection",
      "amount": 2500,
      "transaction_date": "2026-10-12T14:30:00+03:00",
      "payment_method": "bank_account",
      "description": "Tedavi ön ödemesi",
      "customer_id": 123
    }'
  ```

  ```bash Açık bakiyeleri listeleme theme={null}
  curl -G "https://app.flextell.ai/api/v1/customer-balances" \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Tenant: <tenant_id>" \
    --data-urlencode "balance_min=1000" \
    --data-urlencode "sort=latest_transaction_at" \
    --data-urlencode "direction=desc"
  ```
</CodeGroup>

Tahsilat isteği iki satır yazar: Ayşe Yılmaz'ın (`123`) cari hesabında 2500 `credit`, `12` numaralı hesapta 2500 `debit`. Yanıt, hesap satırını Hastanın özetiyle birlikte döner.

```json Bakiye detayı (kısaltılmış) theme={null}
{
  "success": true,
  "data": {
    "customer_id": 123,
    "customer": "Ayşe Yılmaz",
    "outstanding_balance": "4200.00",
    "overdue_balance": "1500.00",
    "currency_code": "TRY"
  }
}
```


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