نماذج استجابة Product API

مع response_format: "standard" (الافتراضي)، تعيد نقاط نهاية المنتجات الأنواع أدناه. TypeScript الرسمي: packages/shared/src/products.ts.

نقاط النهاية: detail · search · image search · parse

غلاف الاستجابة {#envelope}

Endpoint	الشكل
`detail`, `parse`	`{ product: StandardProductDetail, request_id }`
`search`, `search-by-image`	`StandardProductList & { request_id }`
`upload-image`	`{ channel, image_id, request_id }`

StandardProductDetail {#standard-product-detail}

لقطة كاملة للمنتج لصفحات المنتج وcheckout. التعيين إلى الطلبات: search/detail id → lines[].id (offer_id / Taobao mi_id still accepted)، وvariants[].sku_id → spec_id (طلبات الشراء).

الهوية والقناة

الحقل	النوع	الوصف
`id`	string	Taobao = `mi_id` (`lines[].id` للطلب؛ يتغيّر دوريا — لا تخزّنه طويلا). 1688 = `offerId`. Weidian حاليا `prod_weidian_{source_product_id}`
`channel`	string	`1688` أو `taobao` أو `weidian`
`source_product_id`	string	1688 = `offerId` (same as `id`); Taobao = original `item_id`
`source_url`	string	رابط صفحة المنتج الرسمي

النص المحلي (`title`, `description`)

الحقل	النوع	الوصف
`original`	string	نص السوق (عادة بالصينية)
`translated`	string \| null	ترجمة للغة `language` المطلوبة
`language`	string	Locale الخاص بـ `translated`
`description`	object \| null	تفاصيل طويلة (غالبا HTML)

التسعير (`price`, `price_tiers[]`)

كل المبالغ CNY yuan (وليست fen). فضل promotion_amount عند وجوده، وإلا display_amount.

الحقل	النوع	الوصف
`price.original_amount`	number	سعر القائمة قبل العروض
`price.display_amount`	number	السعر المعروض للمشتري (CNY)
`price.promotion_amount`	number \| null	سعر الوحدة الترويجي عند انطباقه
`price.original_currency` / `display_currency`	string	دائما `CNY`
`price_tiers[]`	array	شرائح الجملة في 1688 (العروض الجديدة تبدأ من ≥2)؛ فارغة في Taobao
`min_order_quantity`	number \| null	الحد الأدنى للطلب في 1688
`distribution_min_quantity`	number \| null	حد dropship الأدنى في 1688

الوسائط (`images[]`, `videos`)

الحقل	النوع	الوصف
`images[].url`	string	رابط صورة CDN
`images[].type`	enum	`main` أو `gallery` أو `variant`
`videos.main` / `videos.detail`	string \| null	فيديوهات 1688؛ في Taobao تكون `null`

السمات مقابل المتغيرات

variants[] وحدها تقود اختيار SKU وبنود الطلب.

الحقل	الدور
`attributes[]`	مواصفات CPV — للعرض فقط، وليست لحل SKU
`variants[]`	مصفوفة SKU قابلة للشراء مع السعر والمخزون والمواصفات

كائن المتغير (`variants[]`)

الحقل	النوع	الوصف
`sku_id`	string	مرره كـ `spec_id` عند إنشاء الطلب
`upstream_sku_id`	string \| null	`skuId` الرقمي في 1688
`attributes[]`	array	أبعاد المواصفات (لون، مقاس، …)
`attributes[].name` / `value`	string	تسميات العرض (مترجمة حسب `language`)
`attributes[].original_name` / `original_value`	string	مفاتيح صينية مستقرة للتجميع / المطابقة
`attributes[].prop_id`	string \| null	معرّف الخاصية من المصدر كـ سلسلة (Taobao `prop_id`؛ 1688 `attributeId`). يُفضَّل على نص الاسم
`attributes[].value_id`	string \| null	معرّف القيمة من المصدر كـ سلسلة (Taobao `value_id`). 1688 بلا valueId → `null`
`attributes[].image`	string \| null	صورة الخيار / العيّنة
`price`	object	سعر مستوى SKU باليوان
`stock`	number	الكمية المتاحة؛ `0` = غير متوفر
`image`	string \| null	الصورة الرئيسية لـ SKU
`shipping`	object \| null	أبعاد تغليف SKU في 1688 (الجدول أدناه)؛ تاوباو `null`
`min_order_quantity`	number \| null	الحد الأدنى للطلب 1688 (قيمة المنتج على كل SKU)
`distribution`	object \| null	تسعير dropship في 1688

أبعاد تغليف SKU (`variants[].shipping`)

مُعيَّنة من مصدر 1688 productShippingInfo.skuShippingDetails (SkuShippingDetail). لا يوجد مكافئ في تاوباو — دائمًا null. القيم الفارغة أو 0 تُطبَّع إلى null؛ وبدون بيانات يكون shipping نفسه null.

الحقل	النوع	الوصف
`width_cm`	number \| null	العرض، cm (يعلنه التاجر)
`length_cm`	number \| null	الطول، cm
`height_cm`	number \| null	الارتفاع، cm
`weight_kg`	number \| null	الوزن، kg
`official_width_cm`	number \| null	العرض المقاس رسميًا، cm
`official_length_cm`	number \| null	الطول المقاس رسميًا، cm
`official_height_cm`	number \| null	الارتفاع المقاس رسميًا، cm
`official_weight_kg`	number \| null	الوزن المقاس رسميًا، kg
`ai_weight_kg`	number \| null	الوزن المتوقع بالذكاء الاصطناعي، kg
`ai_weight_accuracy`	string \| null	دقة وزن الذكاء الاصطناعي لفئة الورقة (مثل `80%`)
`source`	string \| null	مصدر الأبعاد (مثل `商家自填`)

لتقدير الشحن، فضّل official_* ثم أبعاد/وزن التاجر ثم ai_weight_kg (مع ai_weight_accuracy كإشارة ثقة).

البائع والشحن والبيانات الوصفية

الحقل	النوع	الوصف
`seller.id` / `seller.name`	string	معرف المتجر واسم العرض
`seller.shop_url`	string \| null	رابط واجهة المتجر
`shipping.shipping_from`	string \| null	منطقة الإرسال المحلية
`shipping.domestic_shipping_fee`	object \| null	رسوم محلية تقديرية باليوان
`metadata.raw_category`	string \| null	فئة upstream
`metadata.brand`	string \| null	العلامة التجارية المعلنة
`metadata.updated_at`	string	آخر مزامنة بتنسيق ISO 8601
`trade_score`	string \| null	درجة جودة 1688

مثال (مختصر)

{
  "product": {
    "id": "554456348334",
    "channel": "1688",
    "source_product_id": "554456348334",
    "title": {
      "original": "...",
      "translated": "...",
      "language": "en"
    },
    "price": {
      "display_amount": 29.9,
      "promotion_amount": 24.9
    },
    "variants": [
      {
        "sku_id": "b266e0...",
        "upstream_sku_id": "12123313",
        "stock": 100,
        "shipping": {
          "width_cm": 10,
          "length_cm": 10,
          "height_cm": 10,
          "weight_kg": 1.2,
          "official_width_cm": 5,
          "official_length_cm": 12,
          "official_height_cm": 14,
          "official_weight_kg": 0.001,
          "ai_weight_kg": 0.001,
          "ai_weight_accuracy": "80%",
          "source": "商家自填"
        }
      }
    ]
  },
  "request_id": "req_..."
}

توفر الحقول حسب القناة

الحقل	1688	Taobao	Weidian
`videos`, `price_tiers`, `trade_score`	✓	—	يختلف
`variants[].shipping`, `distribution`	✓	—	—
`variants[].attributes[].prop_id`	✓ (`attributeId`)	✓ (`prop_id`)	—
`variants[].attributes[].value_id`	— (`null`)	✓ (`value_id`)	—
`source_product_id` للطلبات	`offerId`	`mi_id`	معرف المنصة

StandardProductList {#standard-product-list}

من search وimage search. كل عنصر في items[] هو ملخص — استدع التفاصيل للحصول على مصفوفة SKU.

الحقل	النوع	الوصف
`channel`	string	السوق المستعلم عنه
`keyword`	string	صدى الكلمة المفتاحية (فارغ للبحث بالصورة فقط)
`page` / `page_size`	number	الترقيم المطبق
`total`	number	إجمالي upstream (قد يكون تقريبيا)
`items[]`	array	كائنات `StandardProductListItem`
`pic_region_info`	object	بحث الصورة: منطقة القص المكتشفة

StandardProductListItem

الحقل	النوع	الوصف
`id`, `channel`, `source_product_id`, `source_url`	string	استخدم `source_product_id` لجلب التفاصيل
`title`	LocalizedTitle	عنوان القائمة
`price`	ProductPrice	سعر مختصر بوحدة CNY yuan
`image`	string	رابط الصورة المصغرة
`seller.name`	string	اسم المتجر

استجابة Upload-image {#upload-image-response}

الحقل	النوع	الوصف
`channel`	string	السوق الذي خزّن الصورة
`image_id`	string	أعد استخدامه في البحث بالصورة

اختيار المتغير {#variant-selection}

حمل detail → اقرأ product.variants.
اجمع حسب attributes[].original_name لبناء محددات الأبعاد (أو حسب prop_id إن وُجد).
رشح المتغيرات عند كل اختيار للمستخدم؛ عطّل الخيارات غير المتوفرة.
مرر sku_id المطابق وsource_product_id إلى معاينة الطلب.

مفاتيح المطابقة: في Taobao فضّل prop_id + value_id عند توفرهما (هويات CPV مستقرة؛ تمنع الخلط عندما تتشارك عدة SKU نفس اسم الخاصية). للتجميع في الواجهة استخدم original_name + original_value. name / value للعرض فقط. لا تستنتج نوعًا دلاليًا من التسميات.

{
  "prop_id": "1627207",
  "value_id": "43553464153",
  "name": "Color Classification",
  "value": "[Special for Bicycle Maintenance] Professional 46-Piece Set",
  "original_name": "颜色分类",
  "original_value": "【自行车维修专用】专业46件套",
  "image": "https://img.alicdn.com/..."
}

في 1688 نفس الشكل: prop_id ← attributeId و value_id: null (لا يوجد valueId في SkuAttribute المصدر).

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support