# Stok durumu

Stock modülü, Commerce ürünleri için salt okunur stok durumu sunar: listeleme sayfaları için bir toplu (batch) endpoint ve tek bir varyanta kadar inebilen bir tekil ürün endpoint'i. Her iki route da `/v1/api/stock` altında yer alır, API anahtarınızda `stock:read` scope'unu gerektirir ve mağazanız için `stock` modülünün etkin olmasını gerektirir (aksi halde `403 {"error":"Module not enabled: stock"}`).

## Stok durumu nesnesi

| Alan | Tür | Açıklama |
| --- | --- | --- |
| `product_id` | string (uuid) | Commerce ürün id'si. |
| `variant_id` | string (uuid) or null | Yalnızca tekil ürün endpoint'inde. `variant_id` query parametresini geri yansıtır; atlandığında `null`. |
| `tracked` | boolean | `stock_status` değeri `untracked` olduğunda `false`, aksi halde `true`. |
| `available` | number or null | Mağazanın aktif stok lokasyonlarındaki `quantity - reserved` toplamı, ürünün `unit` biriminde. Ağırlık, uzunluk, alan veya hacimle satılan ürünlerde ondalıklı olabilen bir JSON sayısı (örneğin `47.84`). Takip edilmiyorsa `null`. |
| `stock_status` | string | `untracked`, `in_stock`, `low_stock`, `out_of_stock`, `backorder` değerlerinden biri. |

`stock_status` şöyle türetilir:

- Ürünün `track_stock` değeri `false` (bu, tüm varyantlarını kapsar) veya aktif bir lokasyonda ürün (veya varyant) için hiç stok satırı yok: `untracked`.
- `available` 0 veya daha az: herhangi bir stok satırı ön siparişe (backorder) izin veriyorsa `backorder`, aksi halde `out_of_stock`.
- Herhangi bir stok satırı düşük stok eşiğinde veya altında: `low_stock`.
- Aksi halde: `in_stock`.

## GET /v1/api/stock/availability

Tek bir request'te en fazla 100 ürün için ürün düzeyinde toplu stok durumu. Response, bilinen her ürün id'si için bir kayıt içerir; bilinmeyen id'ler sessizce atlanır (endpoint, toplu istekteki bilinmeyen bir id için asla 404 döndürmez). Bu endpoint yalnızca ürün düzeyindedir ve varyant anahtarları içermez; varyant stok durumu için tekil ürün endpoint'ini kullanın.

### Sorgu parametreleri

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `ids` | array of string (uuid) | Evet | Ürün id'leri, tekrarlanan `ids[]=...` parametreleri olarak gönderilir. En fazla 100 kayıt; her kayıt bir UUID olmalıdır. |

```bash title="Request"
curl --globoff "https://api.borkol.com/v1/api/stock/availability?ids[]=7c1f4b2e-9a3d-4e5f-8b6c-0d1e2f3a4b5c&ids[]=8d2e5c3f-0b4e-4f6a-9c7d-1e2f3a4b5c6d" \
  -H "Authorization: Bearer {api_key}"
```

```javascript title="Request (JS)"
const params = new URLSearchParams();
for (const id of productIds) params.append("ids[]", id);
const res = await fetch(
  `https://api.borkol.com/v1/api/stock/availability?${params}`,
  { headers: { Authorization: `Bearer ${apiKey}` } },
);
const { data } = await res.json();
```

Durum: `200 OK`.

```json title="Response"
{
  "data": [
    {
      "product_id": "7c1f4b2e-9a3d-4e5f-8b6c-0d1e2f3a4b5c",
      "tracked": true,
      "available": 42,
      "stock_status": "in_stock"
    },
    {
      "product_id": "8d2e5c3f-0b4e-4f6a-9c7d-1e2f3a4b5c6d",
      "tracked": false,
      "available": null,
      "stock_status": "untracked"
    }
  ]
}
```

### Hatalar

- `422`: `ids` eksik olduğunda, 100'den fazla kayıt içerdiğinde veya herhangi bir kayıt UUID olmadığında. Kayıt bazlı hatalar anahtarlanmış hata alanları altında görünür, örneğin `errors["ids.0"]`.
- `403` `{"error":"Module not enabled: stock"}`: Stock modülü devre dışı olduğunda.
- `403` `{"message":"Invalid ability provided."}`: API anahtarında `stock:read` scope'u olmadığında.

## GET /v1/api/stock/products/{productId}

Tek bir ürünün stok durumu, isteğe bağlı olarak tek bir varyanta daraltılabilir. `variant_id` verildiğinde response yalnızca o varyantın stok satırlarını yansıtır.

### Yol parametreleri

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `productId` | string (uuid) | Evet | Bir Commerce ürün id'si. |

### Sorgu parametreleri

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `variant_id` | string (uuid) | Hayır | Hesaplamayı bu varyantın stok satırlarıyla sınırlar. Response'ta geri yansıtılır; atlandığında `null`. Bilinmeyen bir `variant_id` 404 döndürmez; yalnızca `untracked` olarak raporlanır. |

```bash title="Request"
curl "https://api.borkol.com/v1/api/stock/products/7c1f4b2e-9a3d-4e5f-8b6c-0d1e2f3a4b5c?variant_id=3a4b5c6d-7e8f-4a1b-9c2d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer {api_key}"
```

Durum: `200 OK`.

```json title="Response"
{
  "data": {
    "product_id": "7c1f4b2e-9a3d-4e5f-8b6c-0d1e2f3a4b5c",
    "variant_id": "3a4b5c6d-7e8f-4a1b-9c2d-0e1f2a3b4c5d",
    "tracked": true,
    "available": 3,
    "stock_status": "low_stock"
  }
}
```

### Hatalar

- `404`: ürün id'si bu mağazada mevcut olmadığında.
- `403`: toplu endpoint'teki gibi modül ve scope hataları.