Ürün Toplu İşlem Gönderimi#

POST https://sdkapi.ideal.house/product-import/products

İstek Gövdesi#

processImages'ü bir JSON boolean olarak (true veya false) gönderin, "true" veya "false" gibi bir dize olarak değil. Görsel ön işleme gerektiren mevcut entegrasyonlar artık açıkça processImages: true göndermelidir.

Ürün Alanları#

Mevcut Ürünleri Yeniden İçe Aktarma#

Ürün verilerini güncellemek için ürünü POST /product-import/products üzerinden tekrar gönderin. Ürünler shopId ve sku ile eşleştirilir. Aynı SKU mağazada zaten mevcut ise, mükerrer oluşturmak yerine mevcut ürün kaydı güncellenir ve en son içe aktarma tarafından sağlanan değerler, name, ürün URLs, durum ve boyutlar gibi alanlardaki ilgili depolanan değerlerin üzerine yazar.

Toplu içe aktarma uç noktası kısmi güncelleme uç noktası değildir. SKU zaten mevcut olsa bile, gönderilen her öğe tüm zorunlu ürün alanı kurallarını karşılamalıdır.

SKU içe aktarma kimliğidir ve yeniden içe aktarma yoluyla yeniden adlandırılamaz. Farklı bir SKU göndermek farklı bir ürünü oluşturur veya günceller. Bir SKU'i değiştirmek için eski ürünü mantıksal olarak silin ve ürünü yeni SKU altında içe aktarın.

Görsel değişmemiş olsa bile ürün bilgileri güncellenir. Görsel işleme her gönderimde isteğe bağlıdır: gerektiğinde processImages: true ayarlayın. Daha önce görsel işleme yapılmadan içe aktarılmış bir ürün, bu seçenek etkinleştirilerek tekrar gönderilebilir.

Desteklenen Ürün Türleri#

API aşağıdaki tam, büyük/küçük harfe duyarlı productType değerlerini kabul eder. Bir satırdaki birden fazla ad, aynı Ideal House ürün türünün takma adlarıdır.

Örneğin, "Rugs", "Area Rugs" ve "Area Rug" hepsi geçerlidir ve aynı ürün türü olarak ele alınır. Yukarıda listelenmeyen herhangi bir değer 400 Bad Request döndürür.

İçe Aktarma Durumu#

İsteğe bağlı status alanı aşağıdaki tam değerleri kabul eder:

Diğer herhangi bir değer, sold_out dahil, 400 Bad Request döndürür.

Mobilya için, etkin olmayan gönderimler ürün status: inactive döndürür. Etkin bir gönderim, ürünün henüz görüntülemeye hazır olmadığını ifade eden unprocessed döndürebilir. Bu, 3D üretiminin istendiği anlamına gelmez.

Mobilya 3D Model Üretimi#

Mobilya 3D model üretimi zaman alıcıdır ve krediler tüketir, bu nedenle processImages true olsa bile ürün içe aktarma sırasında gerçekleştirilmez. Gelecekte kullanıcı arayüzünde bir üretim eylemi veya ayrı bir 3D üretim API sunmayı planlıyoruz. Şu anda 3D modellere ihtiyacınız varsa, üretimi ayrı olarak ayarlayabilmemiz için Ideal House temsilcinize e-posta gönderin.

SKU ve Güncelleme Davranışı#

Ideal House, bir ürünü shopId ve sku kombinasyonu ile tanımlar:

• Mağaza için SKU mevcut değilse, yeni bir ürün oluşturulur.
• Mağaza için SKU zaten mevcut ise, mevcut ürün güncellenir.

Bu, belirsiz bir ağ sonucu sonrasında aynı SKU ile bir ürünü yeniden göndermeyi güvenli hale getirir. Kararlı SKU'lar kullanın ve aynı ürünü yeniden denerken yeni bir SKU üretmeyin. Tek bir toplu işlemde aynı SKU'ü birden fazla kez göndermekten kaçının.

Görsel Gereksinimleri#

• URL, çerezler, oturumlar veya özel istek başlıkları olmadan Ideal House sunucuları tarafından erişilebilir olmalıdır.
• Görseli doğrudan döndüren kararlı bir URL kullanın.
• İçe aktarma işi son durumuna ulaşana kadar kaynak görseli erişilebilir tutun.
• Görsel indirme veya işleme sorunları öğe düzeyinde hatalar olarak raporlanır.
• Zemin parke görselleri oluşturmak için hem processImages: true hem de processFloorImages: true'i ayarlayın.

İsteğe Bağlı Görsel İşleme ve Krediler#

Görsel ön işleme varsayılan olarak devre dışıdır:

• processImages: false ile veya alan atlandığında, etkin ürünler arka plan kaldırma, doku optimizasyonu veya zemin bölme olmadan orijinal görsellerini kullanır. Ürün bilgileri yine de içe aktarılır veya güncellenir ve görsel işleme kredisi tahsil edilmez. Etkin olmayan ürünler yukarıda açıklanan durum kurallarına uyar.
• processImages: true ile, desteklenen etkin ürünler aşağıda açıklanan görsel işlemeden yararlanır. Mobilya 3D üretimi dahil değildir.

Ana işleme davranışları şunlardır:

Mural ve Wall Mural, Duvar ile aynı görsel iyileştirmeleri alır. En iyi sonuçlar için eksiksiz, net ürün görselleri sağlayın; Halılar ve düzenli Duvar Sanatı beyaz veya neredeyse beyaz arka planlara sahip olmalıdır ve Duvar görselleri ciddi perspektif bozulmasından kaçınmalıdır.

Yukarıda açıklanan görsel işleme, Duvar doku optimizasyonu dahil, her yeni işlenen görsel başına 1 kredi'ye mal olur. Mevcut işlenmiş bir sonuç kullanılabilirse, ek işleme kredisi tahsil edilmez. Bu seçeneği etkinleştirmeden önce yeterli kredi olduğundan emin olun. Yetersiz kredi durumunda görsel işleme devam etmez ve ürün unprocessed olarak kalabilir. completed içe aktarma toplu işlemi, her ürün görselinin başarıyla işlendiğini tek başına onaylamaz.

Boyut Gereksinimleri#

API'da ayrı bir boyut birimi alanı yoktur. width zorunludur. height normalde zorunludur, ancak bir Zemin ürünü bunun yerine length sağlayabilir; her ikisi de mevcut olduğunda, length zemin parke uzunluğu olarak kullanılır. Birimsiz sayılar ve sayısal dizeler inç olarak yorumlanır. Dizeler in, ft, cm, mm veya m içerebilir; değerler pozitif boyutlar olarak doğrulanır ve depolamadan önce inçe normalize edilir. thickness isteğe bağlıdır ve "3-4 mm" gibi bir aralığı da kabul eder, bu da "0.1-0.2 in"'ye normalize edilir.

dimension_display isteğe bağlı bir görüntüleme etiketidir ve boyut doğrulaması veya birim dönüşümü için kullanılmaz. Göstermek istediğiniz müşteriye yönelik birim ve biçimi kullanabilir, örneğin "24 in x 36 in" veya "26 cm x 36 cm".

Örnek İstek#

{
  "shopId": "shop_123",
  "processImages": false,
  "processFloorImages": false,
  "products": [
    {
      "sku": "SKU-10001",
      "name": "Gold Wall Mirror",
      "imageUrl": "https://cdn.example.com/products/SKU-10001.png",
      "productUrl": "https://www.example.com/products/SKU-10001",
      "width": "24.0 in",
      "height": "36.0 in",
      "thickness": "2.0 in",
      "dimension_display": "24 in x 36 in",
      "category": "Mirror",
      "color": "Gold",
      "brand": "Example Brand",
      "productType": "Wall Art",
      "status": "active",
      "groupId": "mirror-series-01"
    },
    {
      "sku": "SKU-10002",
      "name": "Black Wall Mirror",
      "imageUrl": "https://cdn.example.com/products/SKU-10002.png",
      "productUrl": "https://www.example.com/products/SKU-10002",
      "width": "2 ft",
      "height": "3 ft",
      "thickness": "3-4 mm",
      "dimension_display": "2 ft x 3 ft",
      "category": "Mirror",
      "color": "Black",
      "brand": "Example Brand",
      "productType": "Wall Art",
      "status": "out_of_stock",
      "groupId": "mirror-series-01"
    }
  ]
}

cURL Örneği (Görsel İşleme Etkin)#

Bu örnek, görsel ön işlemeyi açıkça etkinleştirir. Yeni bir arka plan kaldırma sonucu 1 kredi tüketir.

curl --request POST \
  'https://sdkapi.ideal.house/product-import/products' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
  --header 'X-Client-Secret: <YOUR_CLIENT_SECRET>' \
  --data-raw '{
    "shopId": "shop_123",
    "processImages": true,
    "products": [
      {
        "sku": "SKU-10001",
        "name": "Gold Wall Mirror",
        "imageUrl": "https://cdn.example.com/products/SKU-10001.png",
        "productUrl": "https://www.example.com/products/SKU-10001",
        "width": 24,
        "height": 36,
        "thickness": 2,
        "dimension_display": "24 in x 36 in",
        "category": "Mirror",
        "color": "Gold",
        "brand": "Example Brand",
        "productType": "Wall Art",
        "status": "active",
        "groupId": "mirror-series-01"
      }
    ]
  }'

Kabul Edilen Yanıt#

Geçerli bir istek 202 Accepted döndürür. İşleme asenkron olarak devam eder.

{
  "jobId": "1930000000000000000",
  "shopId": "shop_123",
  "status": "pending",
  "totalCount": 1,
  "processedCount": 0,
  "successCount": 0,
  "failedCount": 0,
  "failures": [],
  "createdAt": "2026-07-21T06:30:00.000Z",
  "startedAt": null,
  "updatedAt": "2026-07-21T06:30:00.000Z",
  "completedAt": null,
  "error": null
}

Mağazada zaten bir pending veya running işi varsa, API 409 Conflict döndürür. Başka bir toplu işlem göndermeden önce mevcut işin bitmesini bekleyin.