Stok girmek, saymak ve taşımak

API adresi https://api.siparis.app/v1. Depoları ve güncel miktarı okumak için ayrıca inventory:read kapsamı (okuma izni) gerekir; maliyetleri görmek costs:read, iç notları görmek internal_notes:read ister.

Anahtarınızı sunucuda SIPARIS_API_KEY ortam değişkeninde tutun; sohbete veya URL'ye yazmayın. Stoku eşitlemek rehberiyle var_ seçenek ve loc_ depo kimliklerini bulun. Miktarlar ondalık metindir; adetle tutulan stokta tam sayı, kg/metre/litre gibi birimlerde en çok üç ondalık hane kabul edilir.

Mal girişi

Aşağıdaki değerleri kendi deponuz ve stok kodunuzla değiştirin. Çok markalı işletmede gövdeye satış markanızın kimliğini "store":"sto_…" olarak ekleyin; tek markada ve marka sınırlı anahtarda atlanabilir. location her zaman açıkça seçilir; marka sınırlı anahtar yalnız /locations listesindeki depolara yazar.

İlk örnek için zorunlu alanlar (POST /v1/inventory/receipts):

Bütün alanlar: Stok girişi yap.

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/inventory/receipts" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: mal-girisi-20261016-001' \
  --data '{"location":"loc_1234567890abcdef1234567890abcdef","lines":[{"sku":"KUPA-MAVI","quantity":"10","unit_price":"120.00"}],"vat_included":true,"external_reference":{"id":"MAL-2026-001"}}'

Örnek HTTP 201 yanıtı (uydurma veri):

{
  "created_at": "2026-10-16T09:00:00Z",
  "id": "doc_1234567890abcdef1234567890abcdef",
  "kind": "receipt",
  "location": "loc_1234567890abcdef1234567890abcdef",
  "movements": {
    "data": [
      {
        "count_reason": null,
        "created_at": "2026-10-16T09:00:00Z",
        "currency": "TRY",
        "document": "doc_1234567890abcdef1234567890abcdef",
        "id": "mov_1234567890abcdef1234567890abcdef",
        "location": "loc_1234567890abcdef1234567890abcdef",
        "order": "ord_1234567890abcdef1234567890abcdef",
        "product": "prd_1234567890abcdef1234567890abcdef",
        "quantity_change": "-1.000",
        "reason": "sale",
        "variant": "var_1234567890abcdef1234567890abcdef",
        "variant_balance_after": "12.000"
      }
    ],
    "has_more": false,
    "next_cursor": null
  },
  "reversed_by": null,
  "reverses": null,
  "revision": 1,
  "to_location": "loc_1234567890abcdef1234567890abcdef"
}

Başarıda 201, belgenin güncel modeli ve Location: /v1/inventory/documents/doc_… gelir. ETag belgenin sürüm etiketidir. Hareketler sayfalanır; has_more=true ise next_cursor (sonraki sayfanın yer imi) ile belgeyi okumaya devam edin.

Alış fiyatı isteğe bağlıdır; yazılmazsa maliyet değiştirilmez. KDV ayrımı ürünün kayıtlı oranıyla yapılır, yeni maliyet paneldeki ağırlıklı ortalama kuralından gelir. Tedarikçi, fatura numarası ve tarihi gibi isteğe bağlı alanlar Stok girişi yap sayfasındadır.

external_reference.id kendi sisteminizdeki belge numarasıdır; API bağlantınızda (paneldeki erişim kaydı; anahtar döndürmek bunu değiştirmez) bir kez kullanılabilir. Aynı numarayla yeni işlem 409 external_reference_conflict verir. Bu alan tekrar anahtarının yerine geçmez.

Aynı isteği güvenle tekrarlayın

Her POST için Idempotency-Key (tekrar anahtarı: aynı isteği güvenle yeniden göndermek için sizin ürettiğiniz benzersiz metin) zorunludur. Yanıt kaybolduğunda aynı gövde ve varsa aynı If-Match başlığıyla (belge siz okuduktan sonra değiştiyse işlemi durduran sürüm denetimi) aynı anahtarı gönderin: iş ikinci kez uygulanmaz, belgenin güncel hali Idempotent-Replayed: true ile döner. Örneğin sonradan tersine çevrilmiş girişin tekrar yanıtında reversed_by doludur. Yeni iş veya düzeltilmiş istek için yeni anahtar kullanın.

Sayımda expected neden zorunlu?

quantity rafta saydığınız yeni miktardır. expected, saymaya başlamadan önce /inventory/levels?variant=var_…&location=loc_… yanıtında okuduğunuz aynı deponun miktarıdır; arada satış yapılırsa eski miktarın üzerine yazılmasını önler. Stok seviyesindeki revision (sürüm numarası) yalnız o seviyeye aittir; stok hareketi ürünün sürümünü değiştirmez.

İlk örnek için zorunlu alanlar (POST /v1/inventory/counts):

Bütün alanlar: Stok sayımı yap.

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/inventory/counts" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: stok-sayimi-20261016-001' \
  --data '{"location":"loc_1234567890abcdef1234567890abcdef","lines":[{"sku":"KUPA-MAVI","quantity":"12","expected":"10"}],"reason":"count_diff"}'

expected uyuşmazsa hiçbir satır yazılmaz: 409 stock_changed, ilk hata yanıtında current_quantity güncel miktarı verir. Stoğu tekrar okuyun, sayımı değerlendirin ve yeni anahtarla gönderin. Stok sayılmıyorsa expected yine zorunludur: açıkça null gönderin. Gizli geçmiş bakiye gösterilmez; ilk sayım panelle aynı şekilde sayımı başlatır. Sipariş üzerine hazırlanan ürünün stoğu sayılmaz.

Miktar zaten aynıysa ortak sayım servisi belge açmaz; 200 {"changed":false} döner. Sayılmayan stokta “0 var” sayımı da sayımı başlatır. Bu belgesiz başarı tekrarlandığında işlem yeniden uygulanmaz.

Fire veya kayıp

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/inventory/write_offs" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: stok-kaybi-20261016-001' \
  --data '{"location":"loc_1234567890abcdef1234567890abcdef","lines":[{"sku":"KUPA-MAVI","quantity":"1"}],"reason":"broken"}'

Miktar pozitif yazılır; servis stoktan düşer. broken hasarlı/kırık, lost kayıp, other diğer nedendir; other için note zorunludur. Giyim ve aksesuarda defective, fitting, sample; gıda ve kozmetikte expired de kullanılabilir. Panelin sektör listesi geçerlidir. Sayılmayan stoktan fire düşülmez; önce sayım yapılır.

Depolar arasında taşıma

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/inventory/transfers" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: stok-tasima-20261016-001' \
  --data '{"location":"loc_1234567890abcdef1234567890abcdef","to_location":"loc_abcdef1234567890abcdef1234567890","lines":[{"sku":"KUPA-MAVI","quantity":"3"}]}'

Kaynak ve hedef farklı, açık ve anahtarın erişebildiği depolar olmalıdır. Kaynakta yeterli miktar yoksa insufficient_stock döner; kısmi taşıma yapılmaz. Toplam stok ve ortalama maliyet değişmez.

Yanlış belgeyi tersine çevirin

Önce belgeyi okuyup ETag değerini alın. Aşağıdaki belge kimliğini ve If-Match değerini kendi yanıtınızla değiştirin.

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/inventory/documents/doc_1234567890abcdef1234567890abcdef/reverse" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: stok-ters-kayit-20261016-001' \
  -H 'If-Match: "1"' \
  --data '{}'

Mal girişi ve fire bir kez tersine çevrilebilir. Eski belge ve hareketler korunur; yeni belge 201 ve Location ile gelir. Ters belge reverses, özgün belge reversed_by alanıyla bağlanır. Mal satılmışsa ve ters kayıt yeni stok açığı yaratacaksa işlem reddedilir. Ortalama maliyet geçmişe döndürülmez. Sayım yeni sayımla, taşıma ters yönde yeni taşımayla düzeltilir.

inventory.document_created ve inventory.document_reversed belgeyi, inventory.level_changed depo bakiyesini bildirir. Olayları okumak events:read ve inventory:read ister. Not, tedarikçi ve maliyet olay yüküne girmez.

Sık hatalar

Bütün alanlar ve yanıt örnekleri her ucun sayfasında: Stok girişi yap, Stok sayımı yap, Fire ve kayıp yaz, Depolar arası taşı, Stok belgesini geri al. Okuma ve sürekli takip stok eşitleme rehberinde.