Ürün eklemek ve güncellemek

API adresi https://api.siparis.app/v1. Okuma için products:read, maliyeti yanıtta görmek için ayrıca costs:read gerekir; yazma kapsamı (izni) okuma izni vermez.

Anahtarı sunucunuzdaki SIPARIS_API_KEY ortam değişkeninde tutun. Örnekler bash ve curl ile çalışır. Her yeni işte yeni Idempotency-Key (tekrar anahtarı: aynı isteği güvenle yeniden göndermek için sizin ürettiğiniz benzersiz metin) kullanın. Yanıt kaybolursa aynı gövde ve aynı anahtarla tekrarlayın: iş ikinci kez uygulanmaz, Idempotent-Replayed: true ile kaydın güncel hali döner.

Basit ürün ekleyin

Tek markada ve marka sınırlı anahtarda hedef marka atlanabilir. Çok markalı işletmede store: "sto_…" veya stores: ["sto_…", "sto_…"] gönderin; kimlikleri GET /stores ile bulun. Marka sınırlı anahtar başka markaya yazamaz. İki marka kavramını karıştırmayın: store (sto_) sizin satış markanızdır, brand (brd_) ürünün üretici markasıdır.

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

Bütün alanlar: Ürün oluştur.

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/products" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: urun-20261016-001' \
  --data '{"name":"Seramik Kupa","description":"300 ml seramik kupa","unit":"adet","tax_rate":"20","price":"120.00","sku":"KUPA-001","opening_stock":"10","external_reference":{"id":"ERP-KUPA-001"}}'

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

{
  "archived": false,
  "brand": "brd_1234567890abcdef1234567890abcdef",
  "code": "KUPA-001",
  "compare_price": "150.00",
  "created_at": "2026-10-16T09:00:00Z",
  "currency": "TRY",
  "description": "Seramik kupa, 300 ml.",
  "id": "prd_1234567890abcdef1234567890abcdef",
  "images": [
    "https://example.com/kupa.jpg"
  ],
  "kind": "standard",
  "made_to_order": false,
  "maximum_quantity": "100.000",
  "minimum_quantity": "1.000",
  "name": "Seramik Kupa",
  "pool_unit": "adet",
  "preparation": "3 iş günü",
  "price": "120.00",
  "quantity_step": "1.000",
  "short_description": "Seramik kupa",
  "slug": "ornek-kupa",
  "status": "active",
  "tax_rate": "20.00",
  "tax_status": "standard",
  "unit": "adet",
  "updated_at": "2026-10-16T09:00:00Z"
}

Yanıtta 201, prd_ ürün kimliği, varsayılan var_ seçeneği, Location ve ETag (sürüm etiketi) gelir. Para TRY cinsinden ondalık metindir. categories ve brand yalnız mevcut kayıtları bağlar; kategori ve ürün markası oluşturmak için Kategori, ürün markası ve kupon yazmak rehberine bakın.

external_reference.id kendi sisteminizdeki ürün kimliğidir; API bağlantınızda (paneldeki erişim kaydı, grt_; anahtar döndürmek bunu değiştirmez) ve kaynak türünde bir kez kullanılabilir. Aynı dış kimlikle ikinci ürün 409 external_reference_conflict verir.

Görseller URL ile verilir; dosya yükleme bu uçta henüz yoktur. Birim, KDV, satış durumu ve fiyat doğrulamaları panelle aynıdır; fiyatsız ürün için status: "draft" kullanın. Bütün alanlar Ürün oluştur sayfasındadır.

Seçenekli ürün ekleyin

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/products" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: urun-20261016-002' \
  --data '{"name":"Renkli Kupa","price":"120.00","variants":[{"name":"Mavi","sku":"KUPA-MAVI","options":[{"name":"Renk","value":"Mavi"}],"price_rule":{"kind":"tl","value":"20.00"},"opening_stock":"5"},{"name":"Beyaz","sku":"KUPA-BEYAZ","options":[{"name":"Renk","value":"Beyaz"}],"price_rule":null,"opening_stock":"5"}]}'

Mavi seçeneğin satış fiyatı 140 TL, beyazınki 120 TL olur. price_rule ürün fiyatından farktır: kind değeri tl veya percent, value negatif olabilir; price_rule: null ürün fiyatını izler. Kural ile mutlak price/compare_price aynı istekte gönderilmez. Açılış stoğunu seçenekli üründe her seçeneğe yazın. Her seçenek ayrıca kendi external_reference alanını alabilir.

Var olan ürüne Ürüne seçenek ekle ile aynı seçenek gövdesini gönderin. Açık sipariş varken de seçenek eklenebilir: ilk seçenek varsayılan seçeneğin kimliğini ve stoğunu korur. Mevcut stoğu değiştirecekseniz opening_stock yanında gördüğünüz expected_stock gerekir; normal stok işlemleri için stok yazma rehberini kullanın. Setin parçası olan varsayılan seçeneğin dönüşümü paneldeki gibi engellenir.

SKU ile seçeneği bulun

curl --fail-with-body --silent --show-error --get \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/variants" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  --data-urlencode 'sku=KUPA-MAVI'

GET /v1/variants?sku=KUPA-MAVI sonucundaki var_ kimliğiyle PATCH /variants/{id} çağırabilirsiniz. SKU ve barkod, işletmede canlı seçenekler arasında baştaki/sondaki boşluk ve harf büyüklüğü dikkate alınmadan tekildir.

Fiyatı güncelleyin

prd_… yerine ürününüzün kimliğini, If-Match yerine en son GET veya yazma yanıtının ETag değerini tırnaklarıyla yazın. Başlığı okumak için curl’e --include ekleyebilirsiniz.

curl --fail-with-body --silent --show-error -X PATCH \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/products/prd_1234567890abcdef1234567890abcdef" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: urun-fiyat-20261016-001' \
  -H 'If-Match: "0123456789abcdef"' \
  --data '{"price":"140.00"}'

If-Match isteğe bağlıdır; ürün siz okuduktan sonra değiştiyse yazmayı durdurur. ETag, anahtarınızın görebildiği ürün, seçenek, kategori ve marka fiyatı alanlarının içerik özetidir; yanıtta revision alanı bulunmaz. Stok miktarı, stok sayım durumu ve updated_at değişiklikleri özete katılmaz. include (yanıta alt kayıt ekleme) ve archived parametreleri etiketi değiştirmez; aynı anahtarla okuduğunuz ETag’i kullanın. 412 revision_mismatch alırsanız ürünü yeniden okuyup yeni tekrar anahtarıyla deneyin. PATCH’te atlanan alan korunur; categories: [] kategori bağlarını, brand: null ürün markasını kaldırır.

Seçenek ayrıntıları Seçeneği güncelle ile güncellenir; seçeneğin ETag’i bağlı ürünün ETag’idir. is_default: true olan varsayılan satırı paneldeki gibi PATCH /products/{id} ile düzenleyin; seçenek PATCH/arşiv ucunda yalnız ürünün eklenmiş seçenekleri kullanılır. Marka fiyatında da varsayılan satır için variant göndermeyin.

Markaya özel fiyat yazın

Aşağıdaki sto_ ve prd_ kimliklerini değiştirin. Gövdeye eklenen isteğe bağlı variant: "var_…" yalnız o seçeneğin marka fiyatını yazar. Diğer markaların fiyatları ve ürün bağları korunur.

curl --fail-with-body --silent --show-error -X PUT \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/store-prices/sto_1234567890abcdef1234567890abcdef/prd_1234567890abcdef1234567890abcdef" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: marka-fiyat-20261016-001' \
  --data '{"price":"110.00","compare_price":"140.00"}'

Alanlar Marka fiyatını getir okumasıyla aynıdır. price ve compare_price ikisi de zorunludur; ikisi null ise özel fiyat satırı kalkar ve katalog fiyatı devralınır. Yanıt, güncel store_prices listesini içeren üründür; ETag de ürüne aittir. Panelle aynı vitrin önbelleği geçersizleştirilir. Katalog fiyatı değişiklikleri panelin fiyat geçmişine girer; markaya özel fiyatlar paneldeki gibi bu geçmişin dışında kalır.

Arşivleyin ve geri getirin

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/products/prd_1234567890abcdef1234567890abcdef/archive" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: urun-arsiv-20261016-001' \
  --data '{}'

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/products/prd_1234567890abcdef1234567890abcdef/restore" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: urun-geri-20261016-001' \
  --data '{}'

Arşiv kayıt silmez; ürün vitrinden ve varsayılan listelerden kalkar, yeni siparişe eklenemez. Açık sipariş/iade varsa panelin koruması işlemi engeller. Önceden satışta olan ürün draft döner; diğer satış durumları korunur; arşivde sıfırlanan stok ortak stok defteriyle geri gelir. Ürünle birlikte arşivlenen seçenekler geri gelir; önceden ayrı arşivlenenler gelmez. Seçenek arşivi Seçeneği arşivle; bağımsız seçenek geri getirme ucu henüz yoktur. Arşivdeki kaydı okumak için archived=true kullanın.

Sık hatalar ve olaylar

product.created/updated/archived/restored, variant.created/updated/archived/restored ve store_price.updated olayları panelle aynı kalıcı olay kanıtlarından üretilir. Seçenek olayında data.object.id seçeneği, data.object.product ürünü gösterir. events:read ve products:read ile izleyin; ayrıntılar olay akışında.