Satışlar

Satış, bir Hastaya sattığınız tedavi ve ürünlerin fiyatlandırılmış listesidir. Satış alacağı Hastanın cari hesabına işlenir; Tahsilatlar bu alacağa karşı kaydedilir. Bu sayfa satış kayıtlarını, kalemlerini, ödemelerini ve satış listesinin dışa aktarımını yöneten endpoint’leri anlatır. Fatura kesme faturalar kaynağındadır (Faturalar). Teklifi satışa çevirme için Teklifler sayfasına bakın. Uçtan uca akış için Satış, tahsilat ve fatura rehberi sayfasını izleyin.

Tüm istekler Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> başlıklarını taşır. Okuma endpoint’leri sales:read, yazma endpoint’leri sales:write scope’unu ister. Scope’lar için Scope’lar sayfasına bakın.

Endpoint özeti

Metot	Endpoint	Açıklama	Scope	İzin
`GET`	`/api/v1/sales`	Satışları listeler.	`sales:read`	`View:Sale`
`POST`	`/api/v1/sales`	Satış oluşturur.	`sales:write`	`Create:Sale`
`GET`	`/api/v1/sales/{id}`	Satış detayını getirir.	`sales:read`	`View:Sale`
`PUT`	`/api/v1/sales/{id}`	Satışı günceller.	`sales:write`	`Update:Sale`
`DELETE`	`/api/v1/sales/{id}`	Satışı siler.	`sales:write`	`Delete:Sale`
`GET`	`/api/v1/sales/form-metadata`	Satış formu için KDV, para birimi ve stok ayarlarını döner.	`sales:read`	`Create:Sale` veya `Update:Sale`
`POST`	`/api/v1/sales/{id}/payments`	Tahsilat veya Hastaya ödeme ekler.	`sales:write`	`Pay:Sale`
`GET`	`/api/v1/sales/{id}/transactions`	Satışın hesap hareketlerini listeler.	`sales:read`	`View:Sale`
`PUT`	`/api/v1/sales/{id}/transactions/{transactionId}`	Bir tahsilatın hesabını veya ödeme yöntemini düzeltir.	`sales:write`	`Pay:Sale`
`DELETE`	`/api/v1/sales/{id}/transactions/{transactionId}`	Satışın bir hareketini siler.	`sales:write`	`Delete:Sale`
`POST`	`/api/v1/sales/{id}/stock-deduct`	Satış kalemlerini manuel olarak stoktan düşer.	`sales:write`	`DeductStock:Sale`
`GET`	`/api/v1/sales/stats`	Satış istatistiklerini döner.	`sales:read`	`ViewAllSales:Sale`
`GET`	`/api/v1/sales/export`	Satış listesinin Excel veya PDF dışa aktarımını başlatır.	`sales:read`	`Export:Sale`

ViewAllSales:Sale iznine sahip değilseniz yalnızca kendi adınıza açılmış satışları veya atandığınız lead’e ait Hastaların satışlarını görürsünüz. Bu kapsamın dışındaki bir satış 404 RESOURCE_NOT_FOUND döner, 403 dönmez.

Satış nesnesi

Alan	Tür	Açıklama
`id`	integer	Satış kimliği.
`user_id`	integer	Satışı yapan kullanıcı. Oluştururken boş bırakırsanız isteği yapan kullanıcı atanır.
`customer_id`	integer \| null	Hasta. Hasta kalıcı olarak silinirse `null` olur.
`appointment_id`	integer \| null	Bağlı randevu.
`currency_id`	integer	Satış para birimi.
`exchange_rate`	number	Satış para biriminin baz para birimine kuru.
`status`	string	Satış durumu (bkz. Durumlar).
`sale_date`	string	Satış tarihi. Klinik saat diliminde, ofsetli ISO 8601.
`notes`	string \| null	Serbest not.
`total_price`	number	Kalemlerin toplamı.
`remaining_balance`	number	Kalan bakiye (satış para biriminde).
`payments`	object	Ödeme yöntemine göre tahsilat: `cash`, `credit_card`, `bank_account`, `other`, `total_collected`.
`record_state`	object	`is_read_only` ve `reason_code` (`CUSTOMER_ERASED` veya `LEAD_NOT_ASSIGNED`).
`customer`	object	Hasta özeti. Atanmamış lead’lerde kişisel veriler maskelenir.
`user`	object	Satışı yapan kullanıcı, `avatar_url` ile.
`currency`	object	Para birimi özeti.
`items`	array	Satış kalemleri. Listede özet, detayda tam biçimdedir.
`default_invoice_account_id`	integer \| null	Faturalarken önerilen hesap. Yalnızca detay yanıtında bulunur.
`import_source`	object \| null	Kayıt dışarıdan içe aktarıldıysa kaynak sistem. Yalnızca detay yanıtında bulunur.
`created_at`, `updated_at`, `deleted_at`	string	Zaman damgaları.

Liste yanıtında items her kalem için order, itemable_type, itemable_id, itemable_name, quantity ve total_price alanlarını taşır. Detay yanıtı ayrıca staff, itemable {id, name} ve assistants[].staff döner. payments alanı payment türündeki (Hastaya yapılan) ödemeleri saymaz. cash dışındaki yöntemler şöyle toplanır: credit_card ve clinic_credit_card credit_card altında, bank_account kendi altında, transfer_cash, other, private_insurance ve sgk ise other altında yer alır.

Durumlar

Değer	Etiket	Açıklama
`draft`	Taslak	Varsayılan durum. Randevudan veya tekliften oluşan satışlar taslak başlar.
`pending`	Beklemede	Siz atarsınız.
`completed`	Tamamlandı	Siz atarsınız.
`cancelled`	İptal Edildi	Siz atarsınız. İstatistiklerden ve vadesi geçmiş bakiyeden hariç tutulur. İptal edilmiş satış stoktan düşülemez.
`invoiced`	Faturalandırıldı	Gönderilen faturalar satışın tamamını karşılayınca otomatik atanır; `status` ile elle de atayabilirsiniz. Satışı kilitler.

API durumlar arasında geçiş kuralı uygulamaz; her durum değerini kabul eder. Tek istisna, invoiced olmuş bir satıştır (bkz. Faturalanmış satış kuralları).

Oluşturma ve kalemler

POST /api/v1/sales bir satış oluşturur ve 201 ile detay nesnesini döner. Tüm işlem tek bir veritabanı işleminde çalışır.

Gövde alanları

Alan	Zorunlu	Kural
`customer_id`	Evet	Kliniğe ait Hasta.
`currency_id`	Evet	Mevcut para birimi.
`exchange_rate`	Evet	Sayı, 0 veya üzeri.
`status`	Evet	`draft`, `completed`, `cancelled`, `invoiced`, `pending`.
`items`	Evet	En az 1 kalem.
`sale_date`	Hayır	Varsayılan: şimdi. Ofsetsiz tarih klinik saat diliminde okunur.
`user_id`	Hayır	Kliniğin kullanıcısı olmalı. Varsayılan: isteği yapan kullanıcı.
`appointment_id`	Hayır	Aynı Hastanın, kliniğe ait bir randevusu olmalı.
`notes`	Hayır	En çok 65535 karakter.
`is_installment_sale`, `installments`	Hayır	Taksitli satış. `is_installment_sale` `true` ise `installments` zorunludur.

Kalem alanları

Alan	Zorunlu	Kural
`staff_id`	Evet	Kliniğin kullanıcısı (kalemi uygulayan personel).
`itemable_type`	Evet	`Treatment` veya `Product`.
`itemable_id`	Evet	Kliniğe ait Tedavi veya Ürün.
`quantity`	Evet	0,0001 veya üzeri.
`unit_price`	Evet	0 veya üzeri, KDV hariç.
`tax_rate`	Evet	Tam sayı: `0`, `1`, `10` veya `20`.
`discount_amount`	Evet	0 veya üzeri.
`discount_percentage`	Evet	0 ile 100 arası.
`warehouse_id`	Hayır	Kliniğe ait Depo.
`assistants[]`	Hayır	Her biri `staff_id` (zorunlu) ve `duty` (en çok 255 karakter) alır.

İki indirim birlikte uygulanır: tutar indirimi ile ara toplamın yüzdesi. Satış başlığında indirim yoktur. Kalem sırası, gönderdiğiniz sıraya göre 0’dan başlayarak verilir.

Toplamlar sunucuda hesaplanır

Sunucu kalem toplamlarını her zaman yeniden hesaplar. İstekte gönderdiğiniz sub_total, total_discount ve total_tax değerleri yok sayılır.

Değer	Formül
`sub_total`	`quantity × unit_price`
`total_discount`	`discount_amount + sub_total × discount_percentage / 100`
`total_price`	`(sub_total − total_discount) + KDV`, KDV matrahı `max(sub_total − total_discount, 0)` üzerinden `tax_rate` ile

Klinik ayarlarında kalem toplamının korunması açıksa gönderdiğiniz total_price korunur. Bu durumda fark max(0.05, 0.02 × quantity) değerini aşarsa items.N.total_price alanında 422 alırsınız. Bu ayarı GET /api/v1/sales/form-metadata yanıtındaki preserve_item_total_price alanından okuyun. form-metadata ayrıca base_currency, default_tax_rate, override_sale_tax_rate ve stock_deduction_mode alanlarını döner. KDV oranı geçersiz kılma ayarını sunucu zorlamaz; uygulamak istemcinin işidir.

Taksitli satış

installments[] içindeki her satır amount (en az 0,01), due_date ve isteğe bağlı description (en çok 255 karakter) alır. Taksit tutarlarının toplamı satış toplamına eşit olmalıdır (±0,01); aksi halde installments alanında 422 döner. Taksit planını sonradan PUT ile oluşturamaz veya değiştiremezsiniz.

Ürün setinden kalem üretme

GET /api/v1/product-sets/{id}/sale-items bir Ürün setini POST /sales kalem biçimine açar. staff_id boş gelir; göndermeden önce doldurun. Bu endpoint products:read scope’u ve View:ProductSet izni ister.

Güncelleme ve silme

PUT kısmi güncellemedir; göndermediğiniz alanlar değişmez. items gönderirseniz mevcut tüm kalemler ve yardımcı personeller silinip yeniden oluşturulur; kalem kimlikleri değişir. sale_date değişirse alacak hareketlerinin tarihi de taşınır.

Satışta tahsilat veya ödeme kaydı varsa kalemleri değiştirmek alacak hareketini güncellemez. Kalan bakiye eski toplama göre görünmeye devam eder.

DELETE satışı siler ve kalemlerini de siler. Satışa bağlı Hasta hesap hareketleri ve eşleşen kasa/banka hareketleri kalıcı olarak silinir; hesaplar bu hareketleri kaybeder.

Satış oluşturma

curl -X POST "https://app.flextell.ai/api/v1/sales" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 123,
    "currency_id": 1,
    "exchange_rate": 1,
    "status": "draft",
    "sale_date": "2026-10-12T14:30:00+03:00",
    "items": [
      {
        "staff_id": 45,
        "itemable_type": "Treatment",
        "itemable_id": 67,
        "quantity": 1,
        "unit_price": 2500,
        "tax_rate": 20,
        "discount_amount": 0,
        "discount_percentage": 10
      }
    ]
  }'

Ödemeler

POST /api/v1/sales/{id}/payments satışa Tahsilat veya Hastaya ödeme ekler. İstekte tutar sınırı yoktur: toplam tahsilat satış toplamını aşabilir, kalan bakiye 0’ın altına inmez.

Alan	Zorunlu	Açıklama
`amount`	Evet	En az 0,01.
`payment_method`	Evet	`bank_account`, `cash`, `transfer_cash`, `other`, `clinic_credit_card`, `credit_card`, `private_insurance`, `sgk`. Liste için `GET /api/v1/payment-methods`.
`type`	Hayır	`collection` (varsayılan, Tahsilat) veya `payment` (Hastaya ödeme).
`account_id`	Hayır	Kasa/banka hesabı. Verirseniz hesaba da hareket işlenir. Hesabın para birimi `currency_id` ile farklıysa hesabın para birimi geçerli olur.
`currency_id`	Hayır	Varsayılan: satış para birimi.
`exchange_rate`	Hayır	Varsayılan: satış kuru veya 1. Para birimi baz para birimiyse 1 kabul edilir.
`transaction_date`	Hayır	Varsayılan: şimdi (klinik saat dilimi).
`invoice_number`	Hayır	En çok 255 karakter.
`description`	Hayır	Açıklama.
`installment_number`	Hayır	1 veya üzeri. Taksitli satışta hangi taksite sayılacağını belirtir. `type` `payment` ise gönderilemez.

installment_number verirseniz satışın taksit planı olmalı, numara planda bulunmalı ve o taksite bağlı tahsilatlar taksit tutarını aşmamalıdır. Taksit seçimi taksitli satışta bile zorunlu değildir. Yanıt sale_id, remaining_balance ve oluşan transaction nesnesini içerir.

Tahsilat ekleme

curl -X POST "https://app.flextell.ai/api/v1/sales/123/payments" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "payment_method": "cash",
    "type": "collection"
  }'

Hesap hareketleri

GET /sales/{id}/transactions satışın tüm hareketlerini sayfalı döner. Filtreler: search (açıklama ve fatura numarası), type (sale, sale_invoice, collection, payment, opening_balance, purchase_invoice). sort_by değerleri: transaction_date (varsayılan), created_at, debit, credit, due_date, invoice_number, amount, account. sort_order varsayılanı desc. Yanıtın meta.collections_by_account alanı, filtreden bağımsız olarak satışın tüm tahsilatlarını hesaba göre gruplar. PUT /sales/{id}/transactions/{transactionId} yalnızca collection türündeki bir hareketin account_id veya payment_method değerini değiştirir; tutar, tarih ve fatura numarası değişmez. En az birini gönderin. Hesap kliniğe ait, aktif ve tahsilatla aynı para biriminde olmalıdır. DELETE /sales/{id}/transactions/{transactionId} herhangi bir hareketi siler; Pay:Sale değil Delete:Sale ister. delete_related_transactions varsayılan olarak true olup eşleşen kasa/banka hareketini de siler. false gönderirseniz hesap hareketi yerinde kalır. Yanıt güncel remaining_balance değerini içerir. Hesaplar için Hesaplar ve işlemler sayfasına bakın.

Stoktan düşme

POST /sales/{id}/stock-deduct yalnızca klinikte stok düşme modu Hiçbir Zaman (Manuel) (never) ise çalışır. Diğer modlarda stok otomatik düşer ve endpoint 422 STOCK_DEDUCTION_DISABLED döner. Düşme satış başına bir kez yapılır. Stok kuralları için Depolar ve stok sayfasına bakın.

İstatistikler ve dışa aktarma

Liste filtreleri

GET /api/v1/sales genel sayfalama (per_page 1–100, varsayılan 15) ve filtreleme ve sıralama kurallarını kullanır. Bu kaynağa özgü filtreler:

Parametre	Açıklama
`search`	Hasta adında tam metin arama (en çok 255 karakter).
`customer_id`, `user_id`, `currency_id`	Kimliğe göre filtre.
`status`	Durum değeri.
`has_remaining_balance`	`true`: kalan bakiye 0,01’den büyük. `false`: 0,01 veya altı.
`total_price_min`, `total_price_max`	Kalem toplamı aralığı. Kur ile ölçeklenmez.
`sale_date_from`, `sale_date_to`, `created_at_from`, `created_at_to`	Tarih aralığı. Sınırlar klinik saat diliminde gün başı ve sonu olarak okunur.
`sort_by`	`sale_date` (varsayılan), `created_at`, `updated_at`, `status`, `total_price`, `balance`.
`sort_order`	Varsayılan `desc`.

Yanıtın meta.totals alanı filtreye uyan tüm satışların para birimine göre toplamını verir: currency_id, currency_code, sales, collections, balance, overdue. Farklı para birimleri birbirine çevrilmez. Her satışın bakiyesi 0’a sabitlenir; fazla ödenmiş bir satış başka satışın borcunu azaltmaz. meta.timezone kliniğin saat dilimini verir.

İstatistikler

GET /api/v1/sales/stats klinik genelindeki özeti döner ve ViewAllSales:Sale ister. View:Sale yetmez. days parametresi 2–90 arasıdır (varsayılan 7).

Alan	Açıklama
`currency_symbol`, `days`	Klinik para birimi simgesi ve istenen gün sayısı.
`sales_amount`	Satış tutarı (baz para birimi). İptal edilenler hariç.
`sales_count`	Satış adedi. İptal edilenler hariç.
`collections_amount`	Tahsilat tutarı (baz para birimi).
`overdue_balance`	Vadesi geçmiş bakiye (baz para birimi). İptal edilenler hariç.

sales_amount, sales_count ve collections_amount aynı yapıdadır: labels[] (gg.aa biçimi), data[], current (bugün), previous (dün) ve change_percentage. Dün değeri 0 ise change_percentage null döner. Seriler klinik saat diliminde bugünde biter. Yanıt 5 dakikaya kadar önbellekten gelebilir.

Dışa aktarma

GET /api/v1/sales/export liste filtrelerinin tümünü kabul eder ve ek olarak format alır: excel (varsayılan) veya pdf. Dışa aktarma her zaman asenkrondur. İstek 202 döner:

{
  "message": "Satış dışa aktarma işi kuyruğa alındı. Hazır olduğunda indirme bağlantısı bildirimle gönderilecek.",
  "format": "excel"
}

Dosya hazır olunca kullanıcıya bildirimle indirme bağlantısı gelir. Bağlantı 24 saat geçerlidir. Süresi dolan bağlantı için GET /api/v1/notifications/system/{id}/download-url ile yenisini alın; bu da Export:Sale izni ister. Dosya, aynı filtrelerle listenin döndüreceği satırları içerir ve ViewAllSales kapsamınıza uyar. Tablo sıralaması yansımaz; satırlar sale_date azalan sırayla gelir. Dosya dili klinik diline göre belirlenir, Accept-Language başlığına göre değil.

Dışa aktarma sınırı klinik ve kullanıcı başına saatte 10 istektir. Aşarsanız 429 ve Retry-After başlığı alırsınız. Genel sınırlar için Oran sınırları sayfasına bakın.

Her iki biçimde de kalem başına bir satır bulunur; satış düzeyindeki hücreler satışın ilk satırında yer alır. Sütunlar: Tarih, Danışan No, Danışan, Kimlik/Pasaport No, Ülke, Personel, Yardımcı Personel, İçerik, Adet, Tutar, Toplam, Tahsilat, Bakiye. Excel dosyasında ayrıca Kur ve Not sütunları bulunur. PDF dosyası Genel Özet, Satış Detayları ve Özet Tablolar bölümlerinden oluşur. Farklı para birimleri toplanmaz, yan yana gösterilir.

Faturalanmış satış kuralları

Durumu invoiced olan satış kilitlidir.

PUT yalnızca notes alanını kabul eder. customer_id, currency_id, exchange_rate, status, user_id veya items gönderirseniz sale alanında 422 alırsınız.
DELETE 422 SALE_INVOICED döner: Bu satış faturalandırıldığı için artık silinemez.

Faturalama için ek olarak CreateDocument:Sale ve Create:Invoice izinleri gerekir. Ayrıntı için Faturalar sayfasına bakın.

Hata kodları

Tüm satış endpoint’leri ortak olarak 401 UNAUTHENTICATED, 403 FORBIDDEN, 422 VALIDATION_FAILED ve 429 TOO_MANY_REQUESTS dönebilir. Genel liste için Hata kodları sayfasına bakın.

Kod	HTTP	Ne zaman
`RESOURCE_NOT_FOUND`	404	Satış yok veya görünürlük kapsamınızın dışında: `Satış bulunamadı`.
`SALE_NO_CUSTOMER`	422	Hastası silinmiş (`customer_id` `null`) satışa ödeme eklenirken: `Bu satış için hasta bulunamadı.`
`PAYMENT_ADD_FAILED`	422	Ödeme kaydedilirken beklenmeyen hata oluştuğunda.
`SALE_INVOICED`	422	Faturalanmış satış silinirken.
`SALE_CANCELLED`	422	İptal edilmiş satış stoktan düşülürken: `Bu satış iptal edildiği için stoktan düşülemez.`
`SALE_NOTHING_TO_DEDUCT`	422	Satışta ürün kalemi yokken stoktan düşülürken.
`SALE_ALREADY_DEDUCTED`	422	Stok bu satış için zaten düşülmüşse.
`STOCK_DEDUCTION_DISABLED`	422	Klinikte manuel stok düşme kapalıyken. Bu kontrol satış aramasından önce yapılır.
`INSUFFICIENT_STOCK`	422	Stok yetersizse: `Yetersiz stok: <ürün> (Depo No: <depo>)`.
`SALE_TRANSACTION_NOT_COLLECTION`	422	Tahsilat olmayan bir hareketi düzeltmeye çalışırken.
`LEAD_FINANCIAL_BLOCKED`	422	Lead aşamasındaki bir Hasta için satış oluştururken veya satışı başka Hastaya taşırken. Kliniğin otomatik dönüşüm modu Satış oluşturulduğunda ise lead önce Hastaya dönüştürülür ve satış devam eder.
`LEAD_NOT_ASSIGNED`	403	Başka bir temsilciye atanmış veya atanmamış lead’in satışında yazma yaparken. `data.assigned_user` `{id, name}` veya `null` döner.
`CUSTOMER_ERASED`	409	Verisi imha edilmiş Hastanın satışında yazma yaparken (stoktan düşme hariç).

Ödeme doğrulama hataları 422 ile alan düzeyinde döner: Bu satışın taksit planı yok., Taksit numarası 1 ile :max arasında olmalıdır., :number. taksite girilen toplam ödeme taksit tutarını aşamaz., Seçilen hesap bu işletmeye ait değil., Seçilen hesap aktif değil..

İzinler

İzin	Etiket	Neyi açar
`View:Sale`	Görüntüle	Liste, detay ve hareketler.
`ViewAllSales:Sale`	Tümünü Görüntüle	Kliniğin tüm satışları ve `GET /sales/stats`.
`Create:Sale`	Oluştur	Satış oluşturma, `form-metadata`.
`Update:Sale`	Güncelle	Satış güncelleme, `form-metadata`.
`Delete:Sale`	Sil	Satış ve satış hareketi silme.
`Pay:Sale`	Öde	Ödeme ekleme, tahsilat düzeltme.
`CreateDocument:Sale`	Fatura/Belge Oluştur	Satıştan fatura kesme (`Create:Invoice` ile birlikte).
`DeductStock:Sale`	Stok Düş	Manuel stoktan düşme.
`Export:Sale`	Dışa Aktar	Dışa aktarma ve indirme bağlantısını yenileme.

Görünürlük kuralları için İzinler ve görünürlük sayfasına bakın.

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

Satış nesnesi

Durumlar

Oluşturma ve kalemler

Gövde alanları

Kalem alanları

Toplamlar sunucuda hesaplanır

Taksitli satış

Ürün setinden kalem üretme

Güncelleme ve silme

Ödemeler

Hesap hareketleri

Stoktan düşme

İstatistikler ve dışa aktarma

Liste filtreleri

İstatistikler

Dışa aktarma

Faturalanmış satış kuralları

Hata kodları

İzinler

​Endpoint özeti

​Satış nesnesi

​Durumlar

​Oluşturma ve kalemler

​Gövde alanları

​Kalem alanları

​Toplamlar sunucuda hesaplanır

​Taksitli satış

​Ürün setinden kalem üretme

​Güncelleme ve silme

​Ödemeler

​Hesap hareketleri

​Stoktan düşme

​İstatistikler ve dışa aktarma

​Liste filtreleri

​İstatistikler

​Dışa aktarma

​Faturalanmış satış kuralları

​Hata kodları

​İzinler

Endpoint özeti

Satış nesnesi

Durumlar

Oluşturma ve kalemler

Gövde alanları

Kalem alanları

Toplamlar sunucuda hesaplanır

Taksitli satış

Ürün setinden kalem üretme

Güncelleme ve silme

Ödemeler

Hesap hareketleri

Stoktan düşme

İstatistikler ve dışa aktarma

Liste filtreleri

İstatistikler

Dışa aktarma

Faturalanmış satış kuralları

Hata kodları

İzinler