نماذج استجابة 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. التعيين إلى الطلبات: source_product_id → offer_id، وvariants[].sku_id → spec_id (طلبات الشراء).

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

الحقل	النوع	الوصف
`id`	string	مفتاح HIOBuy مركب: `{channel}_{source_product_id}`
`channel`	string	`1688` أو `taobao` أو `weidian`
`source_product_id`	string	1688 = `offerId`؛ Taobao = `mi_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؛ فارغة في 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	أبعاد المواصفات (لون، مقاس، …)
`price`	object	سعر مستوى SKU باليوان
`stock`	number	الكمية المتاحة؛ `0` = غير متوفر
`image`	string \| null	الصورة الرئيسية لـ SKU
`shipping`	object \| null	أبعاد تغليف 1688 للشحن
`distribution`	object \| null	تسعير dropship في 1688

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

الحقل	النوع	الوصف
`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": "1688_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...",
        "stock": 100
      }
    ]
  },
  "request_id": "req_..."
}

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

الحقل	1688	Taobao	Weidian
`videos`, `price_tiers`, `trade_score`	✓	—	يختلف
`variants[].shipping`, `distribution`	✓	—	—
`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 لبناء محددات الأبعاد.
رشح المتغيرات عند كل اختيار للمستخدم؛ عطّل الخيارات غير المتوفرة.
مرر sku_id المطابق وsource_product_id إلى معاينة الطلب.