Depolar ve stok

Flextell stok miktarını saklamaz, hesaplar. Bir ürünün bir depodaki bakiyesi, o ürün ve depo için kaydedilmiş hareketlerin giriş toplamı - çıkış toplamı değeridir. Hareketler eklenir, değiştirilmez ve silinmez. Bu sayfa depo kaynağını, stok durumu listesini, hareket kayıtlarını ve stoğu değiştiren dört işlemi anlatır: giriş, düzeltme, transfer ve sayım. Ürün kaynağı için Ürünler sayfasına bakın. Panelde aynı işlemleri nasıl yapacağınız için Depolar, Stoklar ve Stok hareketleri sayfalarına bakın.

Endpoint özeti

Tüm endpoint’ler X-Tenant başlığı ister. Başka kliniğe ait bir depo 404 döner. Başka kliniğe ait ürün veya depo kimliği stok yazma işlemlerinde 422 döner. Başlıklar için Başlıklar sayfasına bakın.

Metot	Endpoint	Açıklama	Scope	İzin
GET	`/warehouses`	Depoları listeler	`warehouses:read`	`View:Warehouse`
POST	`/warehouses`	Depo oluşturur	`warehouses:write`	`Create:Warehouse`
GET	`/warehouses/{id}`	Depoyu getirir	`warehouses:read`	`View:Warehouse`
PUT	`/warehouses/{id}`	Depoyu günceller	`warehouses:write`	`Update:Warehouse`
DELETE	`/warehouses/{id}`	Depoyu siler	`warehouses:write`	`Delete:Warehouse`
GET	`/stocks/overview`	Ürün ve depo bazında stok durumunu listeler	`stocks:read`	`View:StockOverview`
GET	`/stocks/movements`	Stok hareketlerini listeler	`stocks:read`	`View:StockMovement`
GET	`/stocks/movements/{id}`	Stok hareketini getirir	`stocks:read`	`View:StockMovement`
POST	`/stocks/entry`	Stok girişi kaydeder	`stocks:write`	`Create:StockMovement`
POST	`/stocks/adjustment`	Stok düzeltmesi kaydeder	`stocks:write`	`Adjust:StockMovement`
POST	`/stocks/transfer`	Depolar arası transfer yapar	`stocks:write`	`Transfer:StockMovement`
POST	`/stocks/count`	Depo bazında toplu sayım kaydeder	`stocks:write`	`Count:StockMovement`

Her stok işleminin izni ayrıdır. Create:StockMovement tek başına düzeltme, sayım veya transfer yapmaya yetmez. View:StockOverview ile View:StockMovement de birbirini kapsamaz. İzinlerin genel işleyişi için İzinler ve görünürlük sayfasına bakın.

Bu modülde “kendi kayıtlarını görme” gibi bir sahiplik kısıtı yoktur. İzni olan kullanıcı kliniğin tüm depo ve stok kayıtlarını görür.

Depolar

Depo nesnesi

Alan	Tür	Açıklama
`id`	integer	Depo kimliği.
`tenant_id`	integer	Deponun ait olduğu klinik.
`code`	string veya null	Depo kodu.
`name`	string	Depo adı.
`description`	string veya null	Açıklama.
`country`, `city`, `district`	object veya null	Ülke, şehir ve ilçe.
`postal_code`, `address`	string veya null	Posta kodu ve adres.
`latitude`, `longitude`	number veya null	Konum.
`contact_fullname`, `contact_email`, `contact_phone`	string veya null	İletişim kişisi bilgileri.
`is_active`	boolean	Deponun etkin olup olmadığı. Varsayılan `true`.
`is_default`	boolean	Varsayılan depo olup olmadığı. Varsayılan `false`.
`created_at`, `updated_at`	string	Zaman damgaları.

Listeleme

GET /warehouses sayfalı döner. Genel kurallar için Sayfalama ve Filtreleme ve sıralama sayfalarına bakın.

Parametre	Açıklama
`search`	Ad, kod, açıklama ve iletişim kişisi adında arar.
`is_active`, `is_default`	Etkin veya varsayılan depolara göre süzer.
`sort_by`	`name`, `code`, `is_active`, `is_default`, `created_at`, `updated_at`. Varsayılan `created_at`.
`sort_order`	Varsayılan `desc`.
`per_page`, `page`	`per_page` 1 ile 100 arasındadır, varsayılan 15.

Oluşturma ve güncelleme

POST /warehouses için yalnızca name zorunludur. PUT /warehouses/{id} aynı alanları kabul eder ve hepsi isteğe bağlıdır.

Alan	Zorunlu	Kural
`name`	Evet	En fazla 255 karakter.
`code`	Hayır	En fazla 255 karakter. Tüm kliniklerde benzersiz olmalıdır; başka bir klinikte kullanılan kod reddedilir.
`description`	Hayır	Serbest metin.
`country_id`	Hayır	Etkin bir ülke olmalıdır.
`city_id`	Hayır	`country_id` ülkesine ait olmalıdır.
`district_id`	Hayır	`country_id` ve `city_id` değerlerine ait olmalıdır.
`postal_code`	Hayır	Yalnızca rakam, en fazla 20 karakter.
`address`	Hayır	En fazla 1000 karakter.
`latitude`, `longitude`	Hayır	Ondalık sayı.
`contact_fullname`, `contact_phone`	Hayır	İletişim kişisi adı ve telefonu.
`contact_email`	Hayır	Geçerli e-posta adresi.
`is_active`, `is_default`	Hayır	`boolean`.

Varsayılan depo

Bir depoyu is_default: true ile kaydettiğinizde klinikteki diğer depoların is_default değeri sessizce false olur. Klinikte aynı anda en fazla bir varsayılan depo bulunur.Varsayılan depo; ürün oluştururken verdiğiniz initial_stock_quantity için kullanılır. Klinikte hiç varsayılan depo yoksa Flextell Ana Depo adıyla bir tane oluşturur.

Ülke değişince il ve ilçe

Güncellemede country_id değişir ve city_id ile district_id göndermezseniz bu iki alan null olur.

Silme

DELETE /warehouses/{id} depoyu kalıcı olarak siler; geri dönüşüm kutusuna gitmez. Depodaki ürünlerin net miktarı sıfırdan büyükse işlem 422 ve WAREHOUSE_HAS_STOCK koduyla reddedilir. Mesaj: Bu depo kalan stoğu olduğu için silinemez. Önce stoğu başka depoya taşıyın veya düzeltme ile sıfırlayın. Başarılı yanıt {"message": "Depo başarıyla silindi"} gövdesini taşır.

Stok durumu

GET /stocks/overview her ürün ve depo çifti için güncel bakiyeyi döner. Listede yalnızca o depoda en az bir hareketi olan ürünler görünür. Hiç stok girişi yapılmamış bir ürün-depo çifti listede yer almaz.

Satır alanları

Alan	Tür	Açıklama
`product`	object	`{id, name}`.
`warehouse`	object	`{id, name}`.
`balance`	number	Güncel bakiye. Ürünün takip biriminde verilir.
`unit_label`	string	Bakiyenin birim etiketi.
`stock_status`	string	`normal`, `low` veya `critical`.
`critical_stock_level`	number veya null	Ürünün kritik stok seviyesi.

Yanıt yalnızca toplam balance değerini verir. “7 kutu 4 flakon 9 cc” gibi kutu dökümünü istiyorsanız ürünün paketleme alanlarından kendiniz hesaplayın.

Stok durumu değerleri

Değer	Panel etiketi	Ne zaman
`normal`	Normal	Ürünün kritik seviyesi tanımlı değil veya bakiye bu seviyenin üstünde.
`low`	Düşük	Bakiye sıfırdan büyük ve kritik seviyeye eşit ya da altında.
`critical`	Kritik	Kritik seviye tanımlıyken bakiye sıfır veya altında.

Filtreler

Parametre	Açıklama
`warehouse_id`	Tek bir depoya göre süzer.
`product_ids[]`	En fazla 100 ürün kimliği. Her biri klinikteki bir ürün olmalıdır.
`brand_id`	Markaya göre süzer.
`base_unit_code_id`	Temel birime göre süzer. `base_unit` adıyla da gönderebilirsiniz.
`stock_status`	`normal`, `low` veya `critical`.
`sort_by`	`product_name` (varsayılan), `warehouse_name`, `balance`, `stock_status`, `critical_stock_level`.
`sort_order`	Varsayılan `asc`. `stock_status` artan sırada `normal`, `low`, `critical` şeklinde dizilir.
`per_page`, `page`	Sayfalama.

Stok hareketleri

Her stok değişikliği bir hareket kaydı bırakır. Satış, fatura iptali, transfer, düzeltme ve sayım da hareket üretir.

Hareket nesnesi

Alan	Tür	Açıklama
`id`	integer	Hareket kimliği.
`product`	object	`{id, name}`. `name` markayla birleşik tam addır.
`warehouse`	object	`{id, name}`.
`type`	string	Hareket türü. Aşağıdaki tabloya bakın.
`direction`	string	`in` (Giriş) veya `out` (Çıkış).
`quantity`	number	Her zaman pozitiftir; yönü `direction` belirler.
`unit_label`	string	Miktarın birimi.
`reference`	string veya null	Kaynağı gösteren Türkçe etiket.
`user`	object	`{id, name}`. İşlemi yapan kullanıcı.
`notes`	string veya null	Not.
`effective_at`	string	Hareketin bakiyeye dahil olduğu an.
`created_at`, `updated_at`	string	Zaman damgaları.

reference değeri Fatura #<belge no>, Satış #<id>, Transfer #<id>, Sayım #<id> veya Seans #<id> biçimindedir. Kaynağı olmayan harekette null döner.

Hareket türleri

`type`	Panel etiketi	Yön	Nasıl oluşur
`purchase`	Satın Alma	Giriş	`POST /stocks/entry`.
`sale`	Satış	Çıkış	Satışın stoktan düşmesi. Zamanı kliniğin Stok Düşürme Modu ayarına bağlıdır.
`sale_return`	Satış İadesi	Giriş	Fatura iptal edilince o faturanın satış hareketleri geri alınır.
`transfer`	Transfer	Kaynakta çıkış, hedefte giriş	`POST /stocks/transfer`.
`adjustment`	Düzeltme	Giriş veya çıkış	`POST /stocks/adjustment`.
`count`	Sayım	Giriş veya çıkış	`POST /stocks/count`, fark sıfırdan farklıysa.
`initial_stock`	Başlangıç Stoğu	Giriş	Ürün oluştururken `initial_stock_quantity` verilmesi veya depoda hiç hareketi olmayan ürünün sayılması.

type süzgecinde usage, usage_return ve waste değerleri de geçerlidir.

Listeleme

GET /stocks/movements sayfalı döner.

Parametre	Açıklama
`search`	Not metninde arar.
`product_id`, `warehouse_id`	Ürüne veya depoya göre süzer.
`type`, `direction`	Hareket türüne veya yönüne göre süzer.
`effective_at_from`, `effective_at_to`	Tarih aralığı. Tarihler kliniğin saat dilimine göre yorumlanır; bitiş günü dahildir.
`sort_by`	`effective_at` (varsayılan), `quantity`, `type`, `direction`, `created_at`.
`sort_order`	Varsayılan `desc`.
`per_page`, `page`	Sayfalama.

Hareket güncelleme veya silme endpoint’i yoktur. Yanlış bir kaydı düzeltmek için ters yönde yeni bir hareket oluşturun; bunun için POST /stocks/adjustment kullanın.

Stok girişi

POST /stocks/entry bir ürünü bir depoya purchase hareketiyle ekler. Yanıt 201 ve oluşan hareketi döner.

Alan	Zorunlu	Kural
`product_id`	Evet	Klinikteki bir ürün.
`warehouse_id`	Evet	Klinikteki bir depo.
`type`	Evet	`full` veya `partial`.
`quantity`	`full` ise evet	0,0001 ile 9999999999,9999 arası, en fazla 4 ondalık. `partial` ile gönderilemez.
`boxes`	`partial` ise evet	0 ile 9999999999 arası tam sayı.
`inner_units`	`partial` ise evet	0 ile 9999999999 arası tam sayı.
`base_units`	`partial` ise evet	0 ile üst sınır arası, en fazla 4 ondalık.
`notes`	Hayır	En fazla 65535 karakter.

full girişte toplam miktarı ürünün takip biriminde verirsiniz. partial girişte miktarı kutu, iç birim ve temel birim olarak ayrı ayrı verirsiniz; Flextell bunları ürünün stock_tracking_mode değerine göre toplar. partial girişte üç alanı da göndermelisiniz ve hesaplanan toplam sıfırdan büyük olmalıdır.

`stock_tracking_mode`	Takip birimi	`partial` toplamı
`base_unit`	Temel birim (örn. mL)	`boxes × inner_unit_count × base_unit_per_inner + inner_units × base_unit_per_inner + base_units`
`inner_unit`	İç birim (örn. flakon)	`boxes × inner_unit_count + inner_units`. `base_units` yok sayılır.
`direct_unit`	Doğrudan adet	`boxes × inner_unit_count + base_units`. `inner_units` yok sayılır.

Örnek: bir kutuda 5 flakon, bir flakonda 10 cc olan base_unit ürün için 7 kutu, 4 flakon ve 9 cc girişi 399 cc eder.

curl -X POST "https://app.flextell.ai/api/v1/stocks/entry" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 123,
    "warehouse_id": 5,
    "type": "full",
    "quantity": 120,
    "notes": "Mart siparişi"
  }'

curl -X POST "https://app.flextell.ai/api/v1/stocks/entry" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 123,
    "warehouse_id": 5,
    "type": "partial",
    "boxes": 7,
    "inner_units": 4,
    "base_units": 9
  }'

Stok düzeltme

POST /stocks/adjustment bakiyeyi elle değiştirir. İki modu vardır. Yanıt 201 ve {"movement": ...} döner.

Alan	Zorunlu	Kural
`product_id`, `warehouse_id`	Evet	Klinikteki ürün ve depo.
`mode`	Evet	`in_out` veya `correction`.
`direction`	`in_out` ise evet	`in` veya `out`.
`quantity`	Evet	0 ile üst sınır arası, en fazla 4 ondalık. `in_out` modunda en az 0,0001.
`counted_quantity`	Hayır	`correction` modunda `quantity` yerine kullanılabilir.
`notes`	Hayır	En fazla 65535 karakter.

in_out: Bakiyeye quantity kadar ekler veya düşer. Bakiyeden fazla çıkış INSUFFICIENT_STOCK ile reddedilir.
correction: Bakiyeyi quantity değerine eşitler. 0 verebilirsiniz. Flextell farkı tek bir adjustment hareketi olarak yazar. Bakiye zaten bu değerdeyse hiçbir şey yazılmaz ve yanıt 201 olup movement değeri null gelir.

curl -X POST "https://app.flextell.ai/api/v1/stocks/adjustment" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 123,
    "warehouse_id": 5,
    "mode": "in_out",
    "direction": "out",
    "quantity": 3,
    "notes": "Hasarlı ürün"
  }'

Transfer

POST /stocks/transfer bir ürünü iki depo arasında taşır. Flextell bir transfer kaydı ve iki transfer hareketi oluşturur: kaynakta çıkış, hedefte giriş. İkisi de aynı effective_at değerini taşır. Yanıt 201 ve transfer nesnesini döner.

Alan	Zorunlu	Kural
`product_id`	Evet	Klinikteki bir ürün.
`source_warehouse_id`	Evet	Kaynak depo.
`destination_warehouse_id`	Evet	Hedef depo. Kaynaktan farklı olmalıdır.
`quantity`	Evet	0,0001 ile üst sınır arası.
`notes`	Hayır	Not.

Transfer nesnesi şu alanları taşır: id, product, source_warehouse, destination_warehouse, quantity, unit_label, user, notes, transferred_at, source_movement, destination_movement, movements[], created_at, updated_at. Kaynak depodaki bakiye yetmezse 422 ve INSUFFICIENT_STOCK döner. Hedefteki bakiye üst sınırı aşacaksa işlem tamamen geri alınır. Transferler için ayrı liste veya detay endpoint’i yoktur. Transferleri GET /stocks/movements?type=transfer ile izleyin; reference alanında Transfer #<id> görürsünüz.

curl -X POST "https://app.flextell.ai/api/v1/stocks/transfer" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 123,
    "source_warehouse_id": 5,
    "destination_warehouse_id": 6,
    "quantity": 20
  }'

Sayım

POST /stocks/count tek bir depodaki birçok ürünü tek istekte sayar. Flextell sayılan miktarı sistemdeki bakiyeyle karşılaştırır ve farkı hareket olarak yazar.

Alan	Zorunlu	Kural
`warehouse_id`	Evet	Sayılan depo.
`items`	Evet	1 ile 500 satır.
`items.*.product_id`	Evet	Klinikteki bir ürün. Aynı ürünü iki satırda göndermeyin.
`items..boxes`, `items..inner_units`, `items.*.base_units`	Hayır	Sayılan miktar. Toplama kuralı stok girişindeki `partial` ile aynıdır.
`notes`	Hayır	Not.

Sayım miktarını yalnızca boxes, inner_units ve base_units ile verirsiniz. counted_quantity ve üst düzeyde product_id kabul edilmez. items.*.counted_quantity gönderirseniz The counted_quantity field is not supported. Use the partial fields instead. hatası alırsınız. Her satır şu kurallarla işlenir:

Üç miktar alanı da yoksa, null ise veya boşsa satır atlanır. Açık 0 değeri sayılır.
Ürünün o depoda hiç hareketi yoksa ve sayılan miktar 0’dan büyükse tek bir initial_stock hareketi yazılır. Sayım kaydı oluşmaz ve yanıtta count değeri null olur.
Diğer durumlarda sayım kaydı oluşur. Fark sıfırdan farklıysa bir count hareketi yazılır: fark pozitifse giriş, negatifse çıkış.

Yanıt 201 olur ve items dizisi döner. Her öğe {count, movement} biçimindedir. Önce başlangıç stoğu satırları, sonra sayım satırları gelir; sıra isteğinizdeki sıra değildir. Sayım kaydı counted_quantity, system_quantity ve difference (sayılan eksi sistemdeki miktar) alanlarını taşır.

Sayım tek bir işlemdir. Bir satır hata verirse tüm sayım geri alınır ve hiçbir hareket yazılmaz. Hata items.{i}.* anahtarlarıyla hangi satırın sorunlu olduğunu gösterir.

Sayımlar için ayrı liste endpoint’i yoktur. Sonuçları GET /stocks/movements?type=count ile görün; reference alanında Sayım #<id> yazar.

curl -X POST "https://app.flextell.ai/api/v1/stocks/count" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "warehouse_id": 5,
    "notes": "Aylık sayım",
    "items": [
      { "product_id": 123, "boxes": 2, "inner_units": 3, "base_units": 0 },
      { "product_id": 124, "boxes": 0, "inner_units": 0, "base_units": 0 }
    ]
  }'

Miktar sınırları

Tüm stok miktarları en fazla 9999999999,9999 olabilir ve en fazla 4 ondalık basamak taşır. boxes ve inner_units sıfır veya pozitif tam sayı olmalıdır. Giriş ve transfer miktarı en az 0,0001’dir. Sonuçtaki bakiye sınırı aşıyorsa istek reddedilir; hata quantity, boxes veya items.{i}.boxes alanı üzerinde bir doğrulama hatası olarak döner. Stok yazma işlemlerinin tamamı tek işlem olarak çalışır. Hata olursa hiçbir hareket kalmaz.

Hata kodları

Genel hata biçimi için Hatalar ve Hata kodları sayfalarına bakın.

Kod	HTTP	Ne zaman
`INSUFFICIENT_STOCK`	422	Düzeltmede çıkış, transfer veya satıştan düşme bakiyeyi aşıyor. Mesaj: `Yetersiz stok: <ürün> (Depo No: <id>)`.
`STOCK_QUANTITY_LIMIT_EXCEEDED`	422	Sonuçtaki bakiye izin verilen üst sınırı aşıyor. Stok endpoint’leri bunu standart bir doğrulama hatası olarak döner.
`WAREHOUSE_HAS_STOCK`	422	Net stoğu sıfırdan büyük bir depo siliniyor.
`RESOURCE_NOT_FOUND`	404	Depo veya hareket bulunamadı ya da başka kliniğe ait.
`VALIDATION_FAILED`	422	Alan doğrulaması başarısız.
`FORBIDDEN`	403	Gerekli izin yok.

Stok yazma işlemlerinde şu doğrulama mesajları İngilizce gelir: The product does not belong to the tenant., The warehouse does not belong to the tenant., The boxes field must be empty when a full stock entry is selected., The quantity field must be empty when a partial stock entry is selected., The partial fields must produce a total stock quantity greater than 0.

Satış ve stok ilişkisi

Satışların stoktan düşmesi kliniğin Stok Düşürme Modu ayarına bağlıdır:

Mod	Etiket	Ne zaman düşer
`on_invoice`	Fatura Kesildiğinde	Fatura oluşturulduğunda. Varsayılan moddur.
`on_mark`	Faturalandırıldı İşaretlendiğinde	Satış faturalandırıldı olarak işaretlendiğinde.
`never`	Hiçbir Zaman (Manuel)	Yalnızca `POST /sales/{id}/stock-deduct` çağrısıyla.

Satış kaleminde warehouse_id yoksa varsayılan depo kullanılır. Düşürme mantığı ve ilgili hata kodları için Satışlar 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

Depolar

Depo nesnesi

Listeleme

Oluşturma ve güncelleme

Silme

Stok durumu

Satır alanları

Stok durumu değerleri

Filtreler

Stok hareketleri

Hareket nesnesi

Hareket türleri

Listeleme

Stok girişi

Stok düzeltme

Transfer

Sayım

Miktar sınırları

Hata kodları

Satış ve stok ilişkisi

​Endpoint özeti

​Depolar

​Depo nesnesi

​Listeleme

​Oluşturma ve güncelleme

​Silme

​Stok durumu

​Satır alanları

​Stok durumu değerleri

​Filtreler

​Stok hareketleri

​Hareket nesnesi

​Hareket türleri

​Listeleme

​Stok girişi

​Stok düzeltme

​Transfer

​Sayım

​Miktar sınırları

​Hata kodları

​Satış ve stok ilişkisi

Endpoint özeti

Depolar

Depo nesnesi

Listeleme

Oluşturma ve güncelleme

Silme

Stok durumu

Satır alanları

Stok durumu değerleri

Filtreler

Stok hareketleri

Hareket nesnesi

Hareket türleri

Listeleme

Stok girişi

Stok düzeltme

Transfer

Sayım

Miktar sınırları

Hata kodları

Satış ve stok ilişkisi