إرسال دفعة منتج#

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

جسم الطلب#

أرسل processImages كقيمة منطقية في JSON (true أو false)، وليس كسلسلة نصية مثل "true" أو "false". يجب الآن على التكاملات القائمة التي تحتاج إلى المعالجة المسبقة للصور إرسال processImages: true صراحةً.

حقول المنتج#

إعادة استيراد المنتجات الموجودة#

لتحديث بيانات المنتج، أرسله مجددًا عبر POST /product-import/products. تُطابق المنتجات باستخدام shopId وsku. عندما تكون قيمة SKU نفسها موجودة في المتجر، يُحدَّث سجل المنتج القائم بدلًا من إنشاء نسخة مكررة، وتحل القيم المرسلة في أحدث استيراد محل القيم المخزنة المقابلة، بما في ذلك حقول مثل name، وقيم URLs الخاصة بالمنتج، والحالة، والأبعاد.

نقطة نهاية استيراد الدفعات ليست نقطة نهاية للتحديث الجزئي. يجب أن يستوفي كل عنصر مُرسل جميع قواعد حقول المنتج المطلوبة، حتى إن كانت قيمة SKU موجودة بالفعل.

يُعد SKU هو هوية الاستيراد ولا يمكن إعادة تسميته عبر إعادة الاستيراد. تقديم SKU مختلف ينشئ أو يحدث منتجًا مختلفًا. لاستبدال SKU، احذف المنتج القديم منطقيًا واستورد المنتج تحت SKU الجديد.

يتم تحديث معلومات المنتج حتى عندما لم تتغير الصورة. معالجة الصور اختيارية في كل تقديم: اضبط processImages: true عند الحاجة. يمكن إعادة تقديم منتج تم استيراده سابقًا دون معالجة صور مع تمكين هذا الخيار.

أنواع المنتجات المدعومة#

يقبل API قيم productType التالية الحرفية وحساسة لحالة الأحرف. الأسماء المتعددة في صف واحد هي أسماء مستعارة لنفس نوع منتج Ideal House.

على سبيل المثال، "Rugs" و "Area Rugs" و "Area Rug" كلها صحيحة وتُعامل كنفس نوع المنتج. أي قيمة غير مدرجة أعلاه تعيد 400 Bad Request.

حالة الاستيراد#

يقبل الحقل الاختياري status القيم التالية بدقة:

أي قيمة أخرى، بما في ذلك sold_out، تعيد 400 Bad Request.

بالنسبة للأثاث، ترجع التقديمات غير النشطة status: inactive. قد يعيد التقديم النشط unprocessed، مما يعني أن المنتج ليس جاهزًا للعرض بعد. هذا لا يعني أنه تم طلب إنشاء 3D.

إنشاء نموذج 3D للأثاث#

يستغرق إنشاء نماذج 3D للأثاث وقتًا ويستهلك أرصدة، ولذلك لا يُنفَّذ أثناء استيراد المنتجات، حتى عندما تكون قيمة processImages هي true. نخطط لتوفير إجراء للإنشاء في واجهة المستخدم أو API منفصلة لإنشاء 3D مستقبلًا. إذا كنت تحتاج إلى نماذج 3D الآن، فراسل جهة اتصالك في Ideal House عبر البريد الإلكتروني لنرتّب إنشاءها بصورة منفصلة.

SKU وسلوك التحديث#

يُعرّف Ideal House المنتج عن طريق ترکیب shopId و sku:

• إذا لم يكن SKU موجودًا للمتجر، يتم إنشاء منتج جديد.
• إذا كان SKU موجودًا بالفعل للمتجر، يتم تحديث المنتج الحالي.

يجعل ذلك إعادة إرسال منتج بقيمة SKU نفسها آمنة بعد نتيجة شبكة غير مؤكدة. استخدم قيم SKUs ثابتة، ولا تنشئ SKU جديدًا عند إعادة محاولة المنتج نفسه. تجنّب إرسال SKU نفسه أكثر من مرة في دفعة واحدة.

متطلبات الصورة#

• يجب أن يكون URL قابلًا للوصول من قبل خوادم Ideal House دون ملفات تعريف الارتباط، أو جلسات تسجيل الدخول، أو رؤوس طلبات مخصصة.
• استخدم URL مستقر يعيد الصورة مباشرة.
• احتفظ بصورة المصدر متاحة حتى يصل مهمة الاستيراد إلى حالة نهائية.
• تُبلغ مشاكل تحميل أو معالجة الصور كفشل على مستوى العنصر.
• لإنشاء صور ألواح الأرضيات، اضبط كلاً من processImages: true و processFloorImages: true.

معالجة الصور الاختيارية والأرصدة#

ما قبل معالجة الصور معطل افتراضيًا:

• عند تعيين processImages: false أو عدم إرسال الحقل، تستخدم المنتجات النشطة صورها الأصلية دون إزالة الخلفية أو تحسين الملمس أو تقسيم صور الأرضيات. تظل معلومات المنتج مستوردة أو محدّثة، ولا يُخصم أي رصيد لمعالجة الصور. تتبع المنتجات غير النشطة قواعد الحالة المذكورة أعلاه.
• مع processImages: true، تتلقى المنتجات النشطة المدعومة معالجة الصور الموضحة أدناه. لا يشمل ذلك إنشاء نموذج 3D للأثاث.

سلوكيات المعالجة الرئيسية هي:

يتلقى Mural و Wall Mural نفس تحسينات الصور الخاصة بالجدار. للحصول على أفضل النتائج، قدم صور منتجات كاملة وواضحة؛ يجب أن يكون للسجاد وفنون الجدران العادية خلفيات بيضاء أو قريبة من الأبيض، ويجب أن تتجنب صور الجدران تشوه المنظور الشديد.

تبلغ تكلفة معالجة الصور الموضحة أعلاه 1 رصيد لكل صورة تُعالَج حديثًا، بما في ذلك تحسين ملمس ورق الجدران. إذا أمكن استخدام نتيجة معالجة سابقة، فلا يُخصم رصيد إضافي للمعالجة. تأكد من توفر أرصدة كافية قبل تفعيل هذا الخيار. إذا لم تكفِ الأرصدة، فلن تُنفَّذ معالجة الصور وقد يظل المنتج في حالة unprocessed. لا تؤكد دفعة استيراد في حالة completed وحدها نجاح معالجة صورة كل منتج.

متطلبات الأبعاد#

لا تحتوي API على حقل منفصل لوحدة الأبعاد. الحقل width مطلوب. ويكون height مطلوبًا عادةً، لكن يمكن لمنتج الأرضيات إرسال 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. انتظر حتى تنتهي المهمة الحالية قبل إرسال دفعة أخرى.