Paraşüt API ile Ürün, Stok ve Depo Yönetimi: Stok Güncelleme, Transfer ve Fiyat Listesi

Stok Tarafındaki Kaynaklar

Güncelleme metotlarına dikkat edin: ürün, kategori ve depo PUT ile; fiyat listesi ve depo transferi ise PATCH ile güncellenir.

Ürün Kartı Oluşturma

Ürün oluşturmak için tek zorunlu alan name'dir. Pratikte code (stok kodu, SKU), vat_rate, unit, list_price ve currency alanlarını da doldurmanız gerekir. Stok sayılacak ürünlerde inventory_tracking: true gönderin.

curl -X POST "https://api.parasut.com/v4/{company_id}/products" \
  -H "Authorization: Bearer $PARASUT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "products",
      "attributes": {
        "name": "Pamuklu Tişört Siyah M",
        "code": "TS-SYH-M",
        "barcode": "8690000000000",
        "unit": "adet",
        "vat_rate": 20,
        "list_price": 450,
        "currency": "TRL",
        "buying_price": 200,
        "buying_currency": "TRL",
        "inventory_tracking": true,
        "initial_stock_count": 100
      }
    }
  }'

Şu alanlar salt okunurdur ve gönderilmez: stock_count (stok miktarı), list_price_in_trl, buying_price_in_trl, sales_invoice_details_count, purchase_invoice_details_count, sales_excise_duty_code, created_at, updated_at.

Ürünü koda göre bulma

Mükerrer ürün kartı açmamak için önce stok koduyla arayın. GET /products ucu filter[name] ve filter[code] filtrelerini, id ve name sıralamasını (varsayılan -id) kabul eder. include değerleri yalnızca inventory_levels ve category'dir; item_category geçersizdir.

curl -g "https://api.parasut.com/v4/{company_id}/products?filter[code]=TS-SYH-M&include=inventory_levels" \
  -H "Authorization: Bearer $PARASUT_TOKEN"

Elinizde birden fazla Paraşüt ürün kimliği varsa GET /products/by_ids?ids=1,2,3 ile tek istekte en fazla 50 ürün okuyabilirsiniz. Bu uç sayfalanmaz; bulunamayan kimlikler yanıtta yer almaz, hata da vermez. Bu yüzden dönen listeyi istediğiniz kimliklerle karşılaştırın.

Güncelleme, arşiv ve geçmiş

Ürün güncellemesi PUT /{company_id}/products/{id} ile yapılır; şemada name güncellemede de zorunludur. Satışı biten ürünü silmek yerine "archived": true göndermek geçmiş faturaları korur. Ürünün fiyat ve para birimi değişiklik geçmişi GET /products/{id}/history, geçtiği fatura kalemleri GET /products/{product_id}/product_invoice_history_items (en az birinin true olduğu filter[sales_invoices] / filter[purchase_bills] ile) ve irsaliye kaynaklı hareketleri GET /products/{product_id}/product_shipment_document_history_items ile okunur.

Ürün Kategorileri

Kategoriler item_categories kaynağında tutulur ve ürün, cari, çalışan, satış faturası ve gider için ortak yapıdır. Ürün kategorisi oluştururken category_type değeri Product olmalıdır. Alt kategori için parent_id verilir; bg_color ve text_color isteğe bağlıdır.

{
  "data": {
    "type": "item_categories",
    "attributes": {
      "name": "Tişörtler",
      "category_type": "Product",
      "parent_id": 12
    }
  }
}

Ürünü kategoriye bağlamanın iki yolu vardır: ürün oluştururken veya güncellerken relationships.category ilişkisini (type: item_categories, id string) göndermek ya da POST /item_categories/{id}/items/{categorizable_id} ucunu çağırmak. Bu uçta kaydın türü gönderilmez, kategorinin category_type değerinden anlaşılır. Kategoriden çıkarmak için aynı yola DELETE gönderilir; kayıt artık o kategoride değilse 409 (Kategori daha önce değiştirilmiş) döner. Bu durumda kaydı yeniden okuyun.

Depo Yönetimi

Depo oluşturmak için zorunlu alan yalnızca name'dir; address, city, district ve is_abroad isteğe bağlıdır. Liste ucu filter[name] ve filter[archived] kabul eder.

curl -X POST "https://api.parasut.com/v4/{company_id}/warehouses" \
  -H "Authorization: Bearer $PARASUT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data": {"type": "warehouses", "attributes": {"name": "İzmir Depo", "city": "İzmir", "district": "Bornova"}}}'

Kullanılmayan depoyu PATCH /warehouses/{id}/archive ile arşivleyip PATCH /warehouses/{id}/unarchive ile geri alabilirsiniz. Arşivleme şu durumlarda 422 döner:

• Depo zaten arşivlenmişse.
• Depo "Varsayılan" olarak tanımlıysa (varsayılan depo arşivlenemez).
• Depoda sıfırdan farklı stok seviyesi varsa (Stoğunda ürün bulunan depo arşivlenemez.).

Depo Bazında Stok Seviyesi

Bir ürünün hangi depoda kaç adet olduğunu iki yönden okuyabilirsiniz:

• GET /products/{product_id}/inventory_levels: ürünün tüm depolardaki seviyeleri.
• GET /warehouses/{warehouse_id}/inventory_levels: bir deponun tüm ürünlerdeki seviyeleri. Burada filter[archived] deponun arşiv durumuna bakar ve varsayılanı false'tur; depo bulunamazsa 404 yerine boş liste döner.

İki uç da filter[warehouses.name], filter[has_stock] ve filter[stock_count] filtrelerini, id ve stock_count sıralamasını ve product, warehouse include değerlerini kabul eder. Depo uçlu listede filter[stock_count][gt]=0 gibi operatörler de belgelenmiştir. Seviye kaydında stock_count salt okunurdur; initial_stock_count ve critical_stock_count alanları da yer alır.

curl -g "https://api.parasut.com/v4/{company_id}/warehouses/7/inventory_levels?filter[has_stock]=true&include=product&page[size]=25" \
  -H "Authorization: Bearer $PARASUT_TOKEN"

Ürün kaydındaki salt okunur stock_count (Stok Miktarı) alanı da okunabilir. E-ticaret sitesine stok yansıtırken hangi deponun satışa açık olduğunu kendi tarafınızda belirleyip ilgili depo seviyelerini toplamak daha kontrollü bir yöntemdir.

Sayım Sonucunu İşlemek: stock_updates

Fiziksel sayım yaptınız ya da başka bir sistemdeki stok sayısını Paraşüt'e yansıtmak istiyorsunuz. Bunun için POST /{company_id}/stock_updates kullanılır. Her kalem (stock_update_details) bir ürün ve depo için yeni toplam miktarı (new_total_inventory, zorunlu) taşır. Eski miktar (old_total_inventory) salt okunurdur ve yanıtta gelir. Bu uç fark değil, yeni toplamı alır.

curl -X POST "https://api.parasut.com/v4/{company_id}/stock_updates?include=details" \
  -H "Authorization: Bearer $PARASUT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "stock_updates",
      "relationships": {
        "details": {
          "data": [
            {
              "type": "stock_update_details",
              "attributes": { "new_total_inventory": 87 },
              "relationships": {
                "product": { "data": { "type": "products", "id": "1001" } },
                "warehouse": { "data": { "type": "warehouses", "id": "7" } }
              }
            }
          ]
        }
      }
    }
  }'

Başarılı istek 201 döner. Oluşan kaydı ve kalemlerini GET /stock_updates/{id}?include=details,details.product,details.warehouse ile okuyabilirsiniz. Belgelenen uçlar yalnızca oluşturma ve görüntülemedir; stok güncellemeleri için liste, düzenleme veya silme ucu belgede yer almaz.

Stok Hareketlerini Okumak

GET /{company_id}/stock_movements tüm stok hareketlerini listeler ve yalnızca okuma ucudur. Belgeye göre her irsaliye oluşturulurken stok hareketi oluşur; ayrıca irsaliyeli satış faturası veya irsaliyeli alış faturası oluşturulduğunda stok takibi yapılan ürün içeren her kalem için otomatik bir hareket doğar. Sıralama id ve date ile yapılır; include değerleri product, source, contact ve warehouse'dur. source ilişkisi hareketin irsaliyeden mi (shipment_documents), satış fatura kaleminden mi (sales_invoice_details) yoksa alış fatura kaleminden mi (purchase_bill_details) geldiğini gösterir.

Satış faturasında kaleme relationships.warehouse vererek stoğun hangi depodan düşeceğini belirtebilirsiniz. İrsaliye ve e-İrsaliye akışını Paraşüt API irsaliye ve e-İrsaliye, fatura kalemlerini Paraşüt API ile fatura kesme yazısında anlattık.

Depolar Arası Transfer

Bir depodan diğerine ürün aktarmak için POST /{company_id}/warehouse_transfers kullanılır. Kurallar:

• outflow_warehouse (çıkış) ve inflow_warehouse (giriş) ilişkileri zorunludur ve aynı depo olamaz (Giriş ve çıkış deposu aynı olamaz.).
• En az bir kalem (warehouse_transfer_details) gerekir; her kalemde quantity zorunludur.
• issue_date (düzenlenme) ve shipment_date (fiili sevk) zorunludur. Bu iki alan şemada diğer tarihlerden farklı olarak date-time biçimindedir.
• Her kalem için bir çıkış ve bir giriş stok hareketi oluşur; kalemdeki ürünlerin stok takibi açılır, arşivdeyseler arşivden çıkarılır.
• Firmada stok entegrasyonunun açık olması gerekir. Başka firmaya ait depo ya da ürün 404 döner.

{
  "data": {
    "type": "warehouse_transfers",
    "attributes": {
      "description": "İstanbul deposundan İzmir deposuna sevk",
      "issue_date": "2026-11-03T09:00:00+03:00",
      "shipment_date": "2026-11-03T14:00:00+03:00"
    },
    "relationships": {
      "outflow_warehouse": { "data": { "type": "warehouses", "id": "5" } },
      "inflow_warehouse": { "data": { "type": "warehouses", "id": "7" } },
      "details": {
        "data": [
          {
            "type": "warehouse_transfer_details",
            "attributes": { "quantity": 20 },
            "relationships": { "product": { "data": { "type": "products", "id": "1001" } } }
          }
        ]
      }
    }
  }
}

Güncelleme PATCH /warehouse_transfers/{id} ile yapılır ve gövde oluşturma ile aynıdır. Önemli fark: details dizisinde yer almayan mevcut kalemler stok hareketleriyle birlikte silinir. Bir kalemi korumak için onu id'siyle birlikte tekrar göndermelisiniz; yeni kalemde id gönderilmez. DELETE ise transferi, kalemlerini, stok hareketlerini ve bağlı irsaliyeyi birlikte siler.

Liste ucu filter[issue_date] (eq, lt, gt, gteq, lteq, not_eq operatörleriyle), filter[query], filter[outflow_warehouse] ve filter[inflow_warehouse] filtrelerini alır. details ve tags listede include edilemez, tekil kayıtta kullanılabilir.

Fiyat Listeleri

Bayi ya da kurumsal müşteriler için indirimli fiyat kurgusu price_lists ile yapılır. name (firma içinde tekil) ve item_type zorunludur. item_type üç değer alır:

{
  "data": {
    "type": "price_lists",
    "attributes": { "name": "Bayi Listesi 2026", "item_type": "custom" },
    "relationships": {
      "details": {
        "data": [
          {
            "type": "price_list_details",
            "attributes": { "discount_percentage": 15 },
            "relationships": { "product": { "data": { "type": "products", "id": "1001" } } }
          }
        ]
      }
    }
  }
}

Fiyat listesi PATCH /price_lists/{id} ile güncellenir. details gönderildiğinde dizide olmayan mevcut kalemler silinir, data: [] tüm kalemleri kaldırır; details hiç gönderilmezse kalemler değişmez. Bir ürüne listenin uyguladığı indirimi öğrenmek için GET /price_lists/{id}/product_discounts?filter[product_ids]=1001,1002 kullanılır; liste ürüne uygulanmıyorsa 0 döner. Fiyat listesi uçlarında sayfa boyutu 10000'e kadar çıkabilir.

E-ticaret Stok Eşitleme İçin Pratik Akış

• Ürün eşlemesini kurun: sitenizdeki SKU ile Paraşüt code alanını eşleştirin ve Paraşüt ürün id'sini kendi veritabanınızda saklayın.
• Satışta stok hareketinin oluşması için irsaliye ya da irsaliyeli fatura (shipment_included) kullanın ve kalemlere doğru depoyu (warehouse) bağlayın.
• Sayım ya da harici stok farklarını stock_updates ile yeni toplam olarak işleyin.
• Siteye yansıtacağınız stoğu inventory_levels üzerinden düzenli aralıklarla okuyun; zamanlanmış görev kurmak için cron job rehberine bakabilirsiniz.
• Ürün değişikliklerini product webhook event'leriyle izleyin ama yine de periyodik eşitleme yapın; webhook teslimatı garanti değildir.
• Listelerde page[size] değerini 25 ile sınırlı tutun ve 429 yanıtlarında bekleyin; ayrıntılar hata kodları ve rate limit yazısında.

Sık Sorulan Sorular

Paraşüt API ile stok miktarını doğrudan yazabilir miyim?

Ürün ve depo seviyesindeki stock_count salt okunurdur. Stok miktarını değiştirmek için stock_updates ucuna ürün ve depo için yeni toplamı (new_total_inventory) gönderirsiniz. İrsaliyeler ve irsaliyeli satış/alış faturaları da stok hareketi oluşturur.

Hizmet satıyorum, stok takibi gerekir mi?

Hayır. Hizmet kalemlerinde inventory_tracking alanını göndermeyebilir ya da false bırakabilirsiniz. Ürün kartı yine de fatura kalemlerinde kullanılabilir.

Depo transferi için webhook alabilir miyim?

Hayır. Belgeye göre depo transferleri için webhook yoktur ve transferden doğan stok hareketleri için de stock_movement event'i gönderilmez. Transferleri GET /warehouse_transfers ile tarih filtresi kullanarak izleyin.

Ürünü silmek mi, arşivlemek mi daha doğru?

Geçmiş faturalarda kullanılmış ürünlerde arşivlemek (archived: true) daha güvenlidir. DELETE /products/{id} başarıda 204 döner; kullanılmış ürünlerde nasıl davrandığını belge ayrıca açıklamaz.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Paraşüt entegrasyonu genel rehberi · Cari hesap ve müşteri oluşturma · Paraşüt API ile fatura kesme · İrsaliye ve e-İrsaliye · E-ticaret siparişini Paraşüt'e aktarma · Trendyol entegrasyonu API rehberi · CSV ve JSON dönüşümü