ส่งข้อมูลสินค้าเป็นชุด#

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

เนื้อหาคำขอ#

ส่ง processImages เป็นค่า boolean ของ JSON (true หรือ false) ไม่ใช่สตริงเช่น "true" หรือ "false". การเชื่อมต่อที่มีอยู่ซึ่งต้องการการประมวลผลภาพล่วงหน้าต้องส่ง processImages: true อย่างชัดเจน

ฟิลด์สินค้า#

นำเข้าสินค้าที่มีอยู่ซ้ำ#

เพื่อแก้ไขข้อมูลสินค้า ให้ส่งสินค้านั้นอีกครั้งผ่าน POST /product-import/products สินค้าจะถูกจับคู่ด้วย shopId และ sku หาก SKU เดียวกันมีอยู่แล้วในร้าน รายการสินค้าที่มีอยู่จะถูกแก้ไขแทนการสร้างรายการซ้ำ และค่าจากการนำเข้าล่าสุดจะทับค่าที่เก็บไว้เดิม รวมถึงฟิลด์เช่น name, URLs ของสินค้า, สถานะ และขนาด

จุดสิ้นสุดการนำเข้าแบบชุด (batch import endpoint) ไม่ใช่จุดสิ้นสุดการอัปเดตบางส่วน (partial-update endpoint). รายการที่ส่งทุกตัวต้องปฏิบัติตามกฎของฟิลด์สินค้าที่จำเป็นทั้งหมด แม้ในกรณีที่ SKU มีอยู่แล้ว

SKU คือตัวตนของการนำเข้าและไม่สามารถเปลี่ยนชื่อได้ผ่านการนำเข้าซ้ำ การส่ง SKU ที่แตกต่างจะสร้างหรือแก้ไขสินค้าที่แตกต่างกัน หากต้องการแทนที่ SKU ให้ลบสินค้าเก่าทางตรรกะและนำเข้าสินค้าภายใต้ SKU ใหม่

ข้อมูลสินค้าจะถูกแก้ไขแม้ว่ารูปภาพจะไม่มีการเปลี่ยนแปลง การประมวลผลรูปภาพเป็นตัวเลือกในแต่ละครั้งที่ส่ง: ตั้งค่า processImages: true เมื่อจำเป็น สินค้าที่นำเข้ามาก่อนหน้าโดยไม่มีการประมวลผลรูปภาพสามารถส่งอีกครั้งโดยเปิดใช้งานตัวเลือกนี้

ประเภทสินค้าที่รองรับ#

API รับค่า productType ที่ถูกต้องและแยกตัวพิมพ์ใหญ่-เล็กดังต่อไปนี้. ชื่อหลายตัวในแถวเดียวกันเป็นชื่อเรียกแทน (aliases) สำหรับ Ideal House ประเภทสินค้าเดียวกัน

ตัวอย่างเช่น "Rugs", "Area Rugs", และ "Area Rug" ล้วนถูกต้องและถูกถือเป็นประเภทสินค้าเดียวกัน ค่าที่ไม่ได้ระบุไว้ด้านบนจะคืน 400 Bad Request

สถานะการนำเข้า#

ฟิลด์ status ที่เป็นตัวเลือกยอมรับค่าที่ถูกต้องดังต่อไปนี้:

ค่าอื่นใด รวมถึง sold_out จะคืน 400 Bad Request

สำหรับเฟอร์นิเจอร์ การส่งที่ไม่ได้ใช้งาน (non-active) จะคืนค่าสถานะสินค้า status: inactive. การส่งที่ใช้งานอยู่ (active) อาจคืนค่า unprocessed ซึ่งหมายความว่าสินค้ายังไม่พร้อมสำหรับการแสดง. สิ่งนี้ไม่ได้หมายความว่ามีการขอสร้าง 3D แล้ว

การสร้างโมเดล 3D สำหรับเฟอร์นิเจอร์#

การสร้างโมเดล 3D สำหรับเฟอร์นิเจอร์ใช้เวลานานและใช้เครดิต จึงไม่ดำเนินการระหว่างการนำเข้าสินค้า แม้ processImages จะเป็น true เราวางแผนที่จะเพิ่มการสั่งสร้างในส่วนติดต่อผู้ใช้หรือ API สำหรับสร้าง 3D แยกต่างหากในอนาคต หากคุณต้องการโมเดล 3D ตอนนี้ กรุณาส่งอีเมลถึงผู้ติดต่อของคุณที่ Ideal House เพื่อให้เราจัดการสร้างแยกต่างหาก

SKU และพฤติกรรมในการแก้ไข#

Ideal House ระบุสินค้าด้วยชุดของ shopId และ sku:

• หาก SKU ไม่มีอยู่ในร้าน สินค้าใหม่จะถูกสร้าง
• หาก SKU มีอยู่แล้วในร้าน สินค้าที่มีอยู่จะถูกแก้ไข

สิ่งนี้ทำให้ปลอดภัยในการส่งสินค้ายอดนิยมซ้ำด้วย SKU เดียวกันหลังจากผลลัพธ์ทางเครือข่ายที่ไม่แน่นอน ใช้ SKU ที่เสถียรและอย่าสร้าง SKU ใหม่เมื่อลองซ้ำสินค้าเดียวกัน หลีกเลี่ยงการส่ง SKU เดียวกันมากกว่าหนึ่งครั้งในชุดข้อมูลเดียว

ข้อกำหนดรูปภาพ#

• URL ต้องเข้าถึงได้โดยเซิร์ฟเวอร์ของ Ideal House โดยไม่ต้องใช้คุกกี้ เซสชันการเข้าสู่ระบบ หรือหัวคำขอแบบกำหนดเอง
• ใช้ URL ที่เสถียรซึ่งคืนรูปภาพโดยตรง
• เก็บรูปภาพต้นฉบับไว้จนกว่างานนำเข้าจะถึงสถานะสิ้นสุด
• ปัญหาการดาวน์โหลดหรือประมวลผลรูปภาพจะถูกรายงานเป็นความล้มเหลวระดับรายการ
• เพื่อสร้างภาพไม้แผ่นสำหรับพื้น (Floor plank images) ให้ตั้งค่าทั้ง processImages: true และ processFloorImages: true

การประมวลผลรูปภาพและเครดิตแบบตัวเลือก#

การเตรียมรูปภาพล่วงหน้าถูกปิดใช้งานโดยค่าเริ่มต้น:

• เมื่อใช้ processImages: false หรือไม่ระบุฟิลด์ สินค้าที่ใช้งานอยู่จะใช้รูปภาพต้นฉบับโดยไม่มีการลบพื้นหลัง การปรับแต่งพื้นผิว หรือการแยกส่วนพื้น ข้อมูลสินค้ายังคงถูกนำเข้าหรือแก้ไข และไม่มีการหักเครดิตการประมวลผลรูปภาพ สินค้าที่ไม่ได้ใช้งานจะปฏิบัติตามกฎสถานะที่อธิบายไว้ด้านบน
• เมื่อใช้ processImages: true สินค้าที่รองรับและใช้งานอยู่จะได้รับการประมวลผลรูปภาพตามที่อธิบายไว้ด้านล่าง การสร้าง 3D สำหรับเฟอร์นิเจอร์ไม่รวมอยู่ด้วย

พฤติกรรมหลักในการประมวลผลคือ:

Mural และ Wall Mural จะได้รับการปรับปรุงภาพเช่นเดียวกับผนัง (Wall). เพื่อให้ได้ผลลัพธ์ที่ดีที่สุด ให้ส่งภาพสินค้าที่สมบูรณ์และชัดเจน; พรม (Rugs) และงานศิลปะบนผนัง (Wall Art) ทั่วไปควรมีพื้นหลังสีขาวหรือเกือบขาว และภาพผนังควรหลีกเลี่ยงการบิดเบือนมุมมองที่รุนแรง

การประมวลผลภาพที่อธิบายข้างต้นมีค่าใช้จ่าย 1 เครดิตต่อภาพใหม่ที่ถูกประมวลผล รวมถึงการปรับแต่งพื้นผิวผนัง. หากผลลัพธ์ที่ประมวลผลแล้วมีอยู่และสามารถใช้งานได้ จะไม่คิดเครดิตการประมวลผลเพิ่มเติม. ตรวจสอบให้แน่ใจว่ามีเครดิตเพียงพอก่อนเปิดใช้งานตัวเลือกนี้. หากเครดิตไม่เพียงพอ การประมวลผลภาพจะไม่ดำเนินการและสินค้าอาจยังคงเป็น unprocessed. ชุดการนำเข้าที่ completed ไม่ได้ยืนยันด้วยตัวเองว่าภาพสินค้าทุกตัวถูกประมวลผลสำเร็จ

ข้อกำหนดขนาด#

API ไม่มีฟิลด์หน่วยมิติแยกต่างหาก. width เป็นสิ่งจำเป็น. height โดยปกติเป็นสิ่งจำเป็น ในขณะที่สินค้าประเภทพื้น (Floor) สามารถระบุ length แทน; เมื่อมีทั้งสอง length จะถูกใช้เป็นความยาวของไม้แผ่นพื้น. ตัวเลขที่ไม่มีหน่วยและสตริงตัวเลขจะถูกตีความว่าเป็นนิ้ว. สตริงอาจรวม in, ft, cm, mm, หรือ m; ค่าจะถูกตรวจสอบว่าเป็นมิติที่เป็นบวกและปรับให้เป็นนิ้วก่อนจัดเก็บ. thickness เป็นตัวเลือกและรับช่วงค่าเช่น "3-4 mm" ซึ่งจะถูกปรับให้เป็น "0.1-0.2 in"

dimension_display เป็นป้ายชื่อแสดงตัวเลือกและไม่ใช้สำหรับการตรวจสอบขนาดหรือการแปลงหน่วย สามารถใช้หน่วยและรูปแบบที่แสดงต่อลูกค้าที่คุณต้องการ เช่น "24 in x 36 in" หรือ "26 cm x 36 cm"

ตัวอย่างคำขอ#

{
  "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 (เปิดใช้งานการประมวลผลรูปภาพ)#

ตัวอย่างนี้เปิดใช้งานการเตรียมรูปภาพล่วงหน้าอย่างชัดเจน ผลลัพธ์การลบพื้นหลังใหม่จะใช้เครดิต 1

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"
      }
    ]
  }'

การตอบกลับที่ยอมรับ#

คำขอที่ถูกต้องจะคืน 202 Accepted การประมวลผลจะดำเนินการต่อแบบอสังโครนัส

{
  "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
}

หากร้านมีงาน pending หรือ running อยู่แล้ว API จะคืน 409 Conflict รอจนกว่างานปัจจุบันจะเสร็จสิ้นก่อนส่งชุดข้อมูลอื่น