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

# Stok Yönetimi API

> Ürün stok girişi, sayımı, düzeltmesi, depolar arası transferi ve stok hareketlerini yönetmek için endpoint'ler.

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

## Endpoint özeti

| Metot  | Endpoint                        | Açıklama                               |
| ------ | ------------------------------- | -------------------------------------- |
| `GET`  | `/api/v1/stocks/overview`       | Ürün × depo bazlı stok özetini getirir |
| `GET`  | `/api/v1/stocks/movements`      | Stok hareketlerini listeler            |
| `GET`  | `/api/v1/stocks/movements/{id}` | Tek bir stok hareketini getirir        |
| `POST` | `/api/v1/stocks/entry`          | Stok girişi (alım) oluşturur           |
| `POST` | `/api/v1/stocks/count`          | Toplu stok sayımı yapar                |
| `POST` | `/api/v1/stocks/adjustment`     | Stok düzeltmesi yapar                  |
| `POST` | `/api/v1/stocks/transfer`       | Depolar arası transfer oluşturur       |

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

## Stok kavramı

Stok yönetimi, ürünlerin depo bazında miktarlarını takip eder. Her işlem (giriş, sayım, düzeltme, transfer) bir **stok hareketi** (`StockMovement`) kaydı oluşturur.

## Stok durumu hesaplama

`GET /stocks/overview` yanıtında her ürün-depo kombinasyonu için stok durumu şu kurala göre belirlenir:

| Durum      | Koşul                                                               |
| ---------- | ------------------------------------------------------------------- |
| `critical` | `balance ≤ 0` ve kritik seviye tanımlıysa                           |
| `low`      | `0 < balance ≤ critical_stock_level`                                |
| `normal`   | Kritik seviye tanımlı değilse veya `balance > critical_stock_level` |

## İş kuralları

### Stok girişi (`POST /stocks/entry`)

<Note>
  **`type` alanı:** `full` modda `quantity` zorunludur; `partial` modda `boxes`, `inner_units` ve `base_units` zorunludur (`quantity` gönderilemez). `partial` modda bu üç alanın toplamı `> 0` olmalıdır.
</Note>

### Stok sayımı (`POST /stocks/count`)

<Note>
  **Davranış:** Ürünün o depoda daha önce hareketi yoksa **başlangıç stoğu** (`initialStock`) oluşturulur. Hareketi varsa **stok sayımı** (`stockCount`) oluşturulur ve gerekirse farkı kapatmak için otomatik bir düzeltme hareketi (`adjustmentMovement`) eklenir.
</Note>

<Warning>
  `items` dizisindeki `product_id` değerleri **tekrar edemez** (distinct).
</Warning>

### Stok düzeltmesi (`POST /stocks/adjustment`)

<Note>
  **`correction` modu:** Hedef miktarı belirtir; sistem mevcut bakiyeyle farkı hesaplar ve yalnızca fark kadar hareket oluşturur. Fark sıfırsa **hiçbir hareket oluşturulmaz**.
</Note>

<Note>
  **`in_out` modu:** `direction` alanı zorunludur (`in` veya `out`) ve `quantity > 0` olmalıdır.
</Note>

### Depolar arası transfer (`POST /stocks/transfer`)

<Warning>
  Kaynak ve hedef depo **aynı olamaz**.
</Warning>

<Warning>
  Kaynak depoda yeterli stok yoksa `InsufficientStockException` fırlatılır ve `422` döner.
</Warning>

## Yetkilendirme

### Uygulama izinleri (permissions)

| İşlem                                      | Permission              |
| ------------------------------------------ | ----------------------- |
| Listeleme (overview, movements)            | `ViewAny:StockMovement` |
| Yazma (entry, count, adjustment, transfer) | `Create:StockMovement`  |

### Token scope'ları (Passport)

| İşlem                                              | Scope          |
| -------------------------------------------------- | -------------- |
| Okuma (`overview`, `movements`)                    | `stocks:read`  |
| Yazma (`entry`, `count`, `adjustment`, `transfer`) | `stocks:write` |