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

# Satışlar API

> Klinikteki tedavi ve ürün satışlarını, ödeme işlemlerini ve stok düşümlerini yönetmek için endpoint'ler.

<Note>
  Tüm isteklerde `X-Tenant` header'ı **zorunludur**. İşlemler yalnızca belirtilen tenant'a ait satışlar ile sınırlandırılmıştır.
</Note>

## Endpoint özeti

| Metot    | Endpoint                          | Açıklama                           |
| -------- | --------------------------------- | ---------------------------------- |
| `GET`    | `/api/v1/sales`                   | Satışları filtreli olarak listeler |
| `GET`    | `/api/v1/sales/{id}`              | Tek bir satışı detaylı getirir     |
| `POST`   | `/api/v1/sales`                   | Yeni satış oluşturur               |
| `PUT`    | `/api/v1/sales/{id}`              | Satışı günceller                   |
| `DELETE` | `/api/v1/sales/{id}`              | Satışı soft delete eder            |
| `DELETE` | `/api/v1/sales/{id}/force`        | Satışı kalıcı olarak siler         |
| `POST`   | `/api/v1/sales/{id}/payments`     | Satışa ödeme ekler                 |
| `POST`   | `/api/v1/sales/{id}/stock-deduct` | Satış için stok düşümü yapar       |

<Tip>
  Tüm parametreler, alanlar ve örnek istek/yanıtlar için **[API Referansı](/api-reference)** sekmesine bakın.
</Tip>

## Satış kavramı

Satış, bir müşteriye sunulan tedavi veya ürün kalemlerini, uygulanan iskontoları, KDV'yi ve ödeme durumunu bir arada tutan finansal kayıttır. Her satır kalemi (`items`) bir tedavi (`Treatment`) veya ürün (`Product`) olabilir.

## İş kuralları

<Note>
  **Hesaplanan alanlar:** `sub_total`, `total_discount`, `total_tax`, `total_price` alanları **sunucu tarafında hesaplanır**. İstek gövdesinde gönderilseler dahi yok sayılır.
</Note>

<Warning>
  **`invoiced` durumundaki satış:** Satış `invoiced` statüsündeyse yalnızca `notes` alanı güncellenebilir; diğer alanlara yapılan güncelleme reddedilir.
</Warning>

<Warning>
  **`items` güncellemesi:** `PUT` isteğinde `items` gönderilirse mevcut satır kalemleri **tamamen silinip** yeni gönderilen kalemlerle değiştirilir.
</Warning>

<Note>
  **Ödeme varsa işlem:** Satışta taksit veya ödeme kaydı mevcutsa `PUT` isteği `updateOrCreateSaleTransaction()` çağırmaz.
</Note>

## Ödeme ekleme (`POST /sales/{id}/payments`)

Satışa yeni bir ödeme/tahsilat kaydı ekler.

Yanıt `{ sale_id, remaining_balance, transaction }` yapısında döner.

## Stok düşümü (`POST /sales/{id}/stock-deduct`)

<Warning>
  **Yalnızca manuel modda çalışır:** Stok düşümü yalnızca tenant ayarlarında `StockDeductionMode::Never` seçiliyse kullanılabilir. Otomatik modda `422` döner.
</Warning>

<Warning>
  Aşağıdaki durumlarda da `422` döner:

  * Satış `cancelled` statüsündeyse
  * Stok daha önce bu satış için zaten düşüldüyse
  * Satışta `Product` tipi kalem yoksa
</Warning>

## Yetkilendirme

### Uygulama izinleri (permissions)

| İşlem                       | Permission         |
| --------------------------- | ------------------ |
| Listeleme                   | `ViewAny:Sale`     |
| Detay / Tek gösterme        | `View:Sale`        |
| Oluşturma                   | `Create:Sale`      |
| Güncelleme                  | `Update:Sale`      |
| Silme (soft delete)         | `Delete:Sale`      |
| Kalıcı silme (force delete) | `ForceDelete:Sale` |

### Token scope'ları (Passport)

| İşlem                                                                           | Scope         |
| ------------------------------------------------------------------------------- | ------------- |
| Okuma (`index`, `show`)                                                         | `sales:read`  |
| Yazma (`store`, `update`, `destroy`, `forceDelete`, `payments`, `stock-deduct`) | `sales:write` |