Winkwop Geliştirici

Tema

Ürünler ​

Taban adres: https://api.winkwop.com/api/v1/integration/products İzinler: okuma uçları read_products, yazma uçları write_products ister.

Bu sayfa özellikle senkronizasyon (ERP/pazaryeri → Winkwop) yapan entegratörler için: SKU'nun mağazada nasıl bir kimlik gibi davrandığını, varyantların tekrarlanan çağrılarda nasıl eşleştiğini ve satış kanalı alanlarını ayrıntılı anlatır. Tek seferlik CRUD için doğrudan ilgili bölüme geçebilirsiniz.

Listele ​

bash
curl https://api.winkwop.com/api/v1/integration/products \
  -H "X-Api-Key: wk_sk_..."
json
{
  "products": [
    {
      "id": "b3f5...-uuid",
      "name": "Pamuklu Tişört",
      "slug": "pamuklu-tisort",
      "price": 199.9,
      "compare_at_price": null,
      "sku": "TS-001",
      "product_type": "simple",
      "track_quantity": true,
      "quantity": 42,
      "stocks": { "loc-uuid": 30, "loc-uuid-2": 12 },
      "category_ids": ["cat-uuid"],
      "sales_channel_ids": ["chan-uuid"],
      "status": "active",
      "variant_options": null,
      "variants": null
    }
  ]
}

stocks, depo bazlı miktarı gösterir (location_id → adet) — depo id'lerini görmek için Depolar sayfasına bakın. Mağaza tek depoyla çalışıyorsa quantity alanına bakmanız yeterli, bkz. Stok.

product_type: simple (tek SKU) ya da variant (varyantlı — aşağıya bakın). Yalnızca bilgi amaçlı bir etikettir, ne göndereceğinizi variant_options/ variants alanlarının varlığı belirler; product_type alanını hiç göndermeseniz de varyant dizisi doluysa ürün varyantlı sayılır.

Tek ürün ​

bash
curl https://api.winkwop.com/api/v1/integration/products/{id} \
  -H "X-Api-Key: wk_sk_..."

id başka bir mağazaya aitse ya da yoksa 404 NOT_FOUND döner.

SKU tekilliği ​

Bir mağaza içinde sku tekildir. Aynı SKU'yla ikinci kez POST atarsanız ürün "yine de oluşur" değil, 409 CONFLICT döner:

json
{
  "error": {
    "code": "CONFLICT",
    "message": "\"TS-001\" SKU'su bu mağazada zaten kullanılıyor"
  }
}

Bu bilinçli bir tasarım: senkronizasyon işleri (kron, webhook, yeniden deneme) aynı isteği yanlışlıkla iki kez gönderirse eskiden sessizce yinelenen ürün açılıyordu. Artık açıkça hata alırsınız — ve zaten aşağıdaki upsert ucu bu senaryoyu baştan ortadan kaldırır, POST'u hiç kullanmanıza gerek kalmaz.

Oluştur ​

bash
curl -X POST https://api.winkwop.com/api/v1/integration/products \
  -H "X-Api-Key: wk_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pamuklu Tişört",
    "price": 199.90,
    "sku": "TS-001",
    "quantity": 50,
    "status": "active"
  }'

Yalnızca name ve price zorunlu. Diğer alanlar (description, category_ids, images, compare_at_price, barcode, brand_id, supplier_id, tag_ids, sales_channel_ids, ...) opsiyonel — göndermezseniz varsayılan/boş kalır.

Güncelle ​

PUT — kısmi güncelleme değildir, name ve price yine zorunludur; göndermediğiniz opsiyonel alanlar null/boş olarak kaydedilir. Yalnızca stok değiştirmek istiyorsanız bu ucu değil stok ucunu kullanın.

bash
curl -X PUT https://api.winkwop.com/api/v1/integration/products/{id} \
  -H "X-Api-Key: wk_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pamuklu Tişört",
    "price": 179.90,
    "compare_at_price": 199.90,
    "status": "active"
  }'

Bu uç {id} bekler — yani önce hangi Winkwop ürününün hangi SKU'ya karşılık geldiğini bilmeniz gerekir. Çoğu senkronizasyon senaryosunda bunun yerine doğrudan aşağıdaki upsert ucunu kullanmanız daha pratiktir.

Senkronizasyon: SKU ile upsert ​

PUT /api/v1/integration/products/by-sku/{sku}

Bu, entegratörler için asıl kullanmanız gereken uçtur. Kendi sisteminizde bir ürün SKU'suyla var olur; bizim ürettiğimiz id (UUID) sizin için anlamsızdır ve onu saklamak, önce GET/arama yapıp sonra POST ya da PUT kararı vermek zorunda bırakır. Bu uç kararı sizin yerinize verir:

  • SKU'ya sahip bir ürün varsa → güncellenir, 200 OK döner.
  • yoksa → oluşturulur, 201 CREATED döner.
bash
curl -X PUT https://api.winkwop.com/api/v1/integration/products/by-sku/TS-001 \
  -H "X-Api-Key: wk_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pamuklu Tişört",
    "price": 199.90,
    "quantity": 50,
    "status": "active"
  }'

Gövdede sku alanı göndermenize gerek yok, gönderseniz de yok sayılır — kimlik her zaman URL'deki SKU'dur. Aynı isteği istediğiniz kadar tekrar gönderebilirsiniz (idempotent): sonuç hep aynı üründe biriken bir güncelleme olur, asla yeni bir kopya açmaz. Kron işiniz her gece "tüm katalogu gönder" diyorsa doğru uç budur.

Ürün SKU'sunu bu uçla değiştiremezsiniz (yol zaten SKU'yu sabitliyor) — SKU'yu değiştirmeniz gerekiyorsa normal PUT /products/{id} ucunu, id'yi bir kez GET /products?... ile bulduktan sonra kullanın.

Varyantlı ürün ​

Varyant oluşturmak için variant_options (renk/beden gibi seçenek tanımları) ve variants (her kombinasyonun kendi SKU/fiyat/stoğu) gönderin:

bash
curl -X PUT https://api.winkwop.com/api/v1/integration/products/by-sku/TS-001 \
  -H "X-Api-Key: wk_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pamuklu Tişört",
    "price": 199.90,
    "variant_options": [
      { "name": "Beden", "style": "text", "values": ["S", "M", "L"] }
    ],
    "variants": [
      { "sku": "TS-001-S", "price": 199.90, "quantity": 10, "options": { "Beden": "S" }, "status": "active" },
      { "sku": "TS-001-M", "price": 199.90, "quantity": 15, "options": { "Beden": "M" }, "status": "active" }
    ]
  }'

variants[].price, üst düzey price alanından bağımsızdır — varyantlı bir üründe müşteri hep varyant fiyatını görür, üst düzey price yalnızca varyantsız görünümler (ör. arama sonucu önizlemesi) için bir yedektir.

Tekrar senkronizasyonda ne olur (önemli) ​

variants[] içindeki her satır kendi Winkwop id'sini taşımaz — siz yalnızca sku bilirsiniz. Bu yüzden bir varyant satırında id yoksa (hiçbir zaman göndermeniz gerekmez), Winkwop şu sırayla karar verir:

  1. Bu ürünün altında sku'su eşleşen bir varyant var mı? → varsa günceller.
  2. Yoksa → yeni varyant satırı açar.

Yani yukarıdaki isteği yarın tekrar gönderseniz (fiyat/stok değişikliğiyle), TS-001-S ve TS-001-M yeniden oluşmaz, olduğu gibi güncellenir. Bu davranış sürüm önemli — eskiden id gönderilmeyen her varyant satırı koşulsuz yeni satır olarak ekleniyordu; günlük senkronizasyon çalıştıran bir entegrasyon her turda aynı varyantları çoğaltıyordu. Artık SKU eşleştirmesi bunu engelliyor; siz variants[] dizisini "bu ürünün güncel hâli budur" gibi düşünüp her seferinde tam listeyi gönderebilirsiniz.

Dizide listelemediğiniz eski bir varyant silinmez — yalnızca göndermediğiniz için değişmeden kalır. Bir varyantı gerçekten kaldırmak isterseniz onu panelden silin; entegrasyon API'sinde varyant silme ucu yoktur.

Satış kanalları ​

Bir ürünün hangi satış kanallarında (online mağaza, belirli bir pazaryeri bağlantısı, vb.) görünür olduğunu sales_channel_ids alanı belirler. Kanal id'lerini önce keşfetmeniz gerekir:

bash
curl https://api.winkwop.com/api/v1/integration/sales-channels \
  -H "X-Api-Key: wk_sk_..."
json
[
  { "id": "chan-uuid", "name": "Online Mağaza", "type_": "online_store", "is_active": true, "slug": "magaza" }
]

Bir ürünü belirli kanallarda açık göndermek için oluşturma/güncelleme isteğinde sales_channel_ids verin:

bash
curl -X PUT https://api.winkwop.com/api/v1/integration/products/by-sku/TS-001 \
  -H "X-Api-Key: wk_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pamuklu Tişört",
    "price": 199.90,
    "sales_channel_ids": ["chan-uuid"]
  }'

sales_channel_ids göndermezseniz mevcut kanal ataması boşaltılır (bu uç kısmi güncelleme yapmıyor, bkz. Güncelle) — ürünün hangi kanallarda kalması gerektiğini her istekte tam olarak belirtin.

Çok sayıda ürünü tek istekte bir kanala açmak/kapatmak için toplu uç:

bash
curl -X POST https://api.winkwop.com/api/v1/integration/products/bulk/sales-channels \
  -H "X-Api-Key: wk_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": ["p1-uuid", "p2-uuid"],
    "sales_channel_ids": ["chan-uuid"],
    "action": "add"
  }'

action: add (mevcut kanallara ekler, dokunmadığı kanalları değiştirmez) ya da remove (yalnızca listelenen kanallardan çıkarır). Yanıt kaç ürünün güncellendiğini döner: {"updated": 2}.

Sil ​

bash
curl -X DELETE https://api.winkwop.com/api/v1/integration/products/{id} \
  -H "X-Api-Key: wk_sk_..."

Toplu içe aktarma (CSV / XML) ​

Tek tek POST/PUT atmak yerine, bir dosyanın içeriğini gövdede düz metin olarak gönderirsiniz — ilk yükleme (yüzlerce satır) için tercih edin, düzenli senkronizasyon için SKU ile upsert ucu daha uygundur (satır bazlı hata raporu yerine anlık, tekil sonuç verir).

bash
curl -X POST https://api.winkwop.com/api/v1/integration/products/import/csv \
  -H "X-Api-Key: wk_sk_..." \
  -H "Content-Type: application/json" \
  -d "{\"csv\": \"sku,name,price,stock\nTS-001,Pamuklu Tişört,199.90,50\n\"}"

XML için aynı şekilde POST .../import/xml gövdede {"xml": "..."}.

Yanıt bir özet döner — hangi satırların başarısız olduğunu satır numarasıyla gösterir, isteğin tamamı tek bir hata yüzünden başarısız olmaz:

json
{
  "total_rows": 120,
  "products_created": 110,
  "products_updated": 8,
  "categories_created": 3,
  "brands_created": 1,
  "failed": 2,
  "images_queued": 45,
  "errors": [
    { "row": 37, "sku": "TS-099", "message": "Fiyat sayısal olmalı" }
  ]
}

Görseller URL olarak verilirse arka planda kendi depolama alanınıza indirilir; images_queued bekleyen görsel sayısını gösterir, içe aktarma bunları beklemeden döner.

Sürüm notu ​

Varyant SKU eşleştirmesi (yukarıdaki "Tekrar senkronizasyonda ne olur" bölümü) ve SKU çakışma koruması, bu dokümanın yayınlandığı sürümle birlikte eklendi. Daha eski bir entegrasyonunuz "aynı SKU'yu tekrar tekrar açıyor" ya da "her senkronizasyonda varyantlar çoğalıyor" gibi bir davranış gösteriyorsa, API tarafında düzeltildi — tekrar denemeniz yeterli.

Winkwop tema platformu

© Winkwop