Модели ответов Product API

С response_format: "standard" (по умолчанию) product endpoints возвращают типы ниже. Канонический TypeScript: packages/shared/src/products.ts.

Endpoints: детали · поиск · поиск по изображению · парсинг

Обертка ответа {#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. Маппинг в orders: search/detail id → lines[].id (offer_id / Taobao mi_id still accepted), variants[].sku_id → spec_id (заказы закупки).

Идентичность и канал

Поле	Тип	Описание
`id`	string	Taobao = `mi_id` (order `lines[].id`; периодически меняется — не кэшируйте надолго). 1688 = `offerId`. Weidian currently `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	Канонический URL страницы товара

Локализованный текст (`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	List price до promotions
`price.display_amount`	number	Цена для покупателя (CNY)
`price.promotion_amount`	number \| null	Promotional unit price, когда применимо
`price.original_currency` / `display_currency`	string	Всегда `CNY`
`price_tiers[]`	array	Оптовые ступени 1688 (новые офферы от ≥2); пусто на Taobao
`min_order_quantity`	number \| null	1688 MOQ
`distribution_min_quantity`	number \| null	Минимум 1688 dropship

Медиа (`images[]`, `videos`)

Поле	Тип	Описание
`images[].url`	string	URL изображения CDN
`images[].type`	enum	`main`, `gallery` или `variant`
`videos.main` / `videos.detail`	string \| null	Видео 1688; Taobao `null`

Attributes vs variants

Только variants[] управляет выбором SKU и строками заказа.

Поле	Роль
`attributes[]`	CPV specs — только отображение, не для SKU resolution
`variants[]`	Покупаемая SKU matrix с ценой, остатком и specs

Объект variant (`variants[]`)

Поле	Тип	Описание
`sku_id`	string	Передавайте как `spec_id` при order create
`upstream_sku_id`	string \| null	Числовой `skuId` 1688
`attributes[]`	array	Измерения spec (цвет, размер, …)
`attributes[].name` / `value`	string	Отображаемые подписи (локализованы по `language`)
`attributes[].original_name` / `original_value`	string	Стабильные китайские ключи для группировки / сопоставления
`attributes[].prop_id`	string \| null	ID свойства upstream как строка (Taobao `prop_id`; 1688 `attributeId`). Предпочтительнее текста имени
`attributes[].value_id`	string \| null	ID значения upstream как строка (Taobao `value_id`). У 1688 нет valueId → `null`
`attributes[].image`	string \| null	Изображение опции / образца
`price`	object	Цена на уровне SKU в yuan
`stock`	number	Доступное количество; `0` = нет в наличии
`image`	string \| null	Основное изображение SKU
`shipping`	object \| null	Размеры упаковки SKU 1688 (таблица ниже); Taobao — `null`
`min_order_quantity`	number \| null	MOQ 1688 (значение товара на каждом SKU)
`distribution`	object \| null	Цены 1688 dropship

Размеры упаковки SKU (`variants[].shipping`)

Сопоставлено с upstream 1688 productShippingInfo.skuShippingDetails (SkuShippingDetail). У Taobao эквивалента нет — всегда 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 как подсказкой уверенности).

Продавец, доставка и metadata

Поле	Тип	Описание
`seller.id` / `seller.name`	string	Shop id и отображаемое имя
`seller.shop_url`	string \| null	Ссылка на storefront
`shipping.shipping_from`	string \| null	Регион внутренней отправки
`shipping.domestic_shipping_fee`	object \| null	Оценка внутренней платы доставки в yuan
`metadata.raw_category`	string \| null	Upstream category
`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` для orders	`offerId`	`mi_id`	Platform id

StandardProductList {#standard-product-list}

Из поиска и поиска по изображению. Каждая запись items[] — это summary; вызовите detail для SKU matrix.

Поле	Тип	Описание
`channel`	string	Запрошенный маркетплейс
`keyword`	string	Эхо keyword (пусто для чистого image search)
`page` / `page_size`	number	Примененная pagination
`total`	number	Upstream total (может быть приблизительным)
`items[]`	array	Объекты `StandardProductListItem`
`pic_region_info`	object	Image search: обнаруженная crop region

StandardProductListItem

Поле	Тип	Описание
`id`, `channel`, `source_product_id`, `source_url`	string	Используйте `source_product_id` для получения detail
`title`	LocalizedTitle	Название listing
`price`	ProductPrice	Summary price в CNY yuan
`image`	string	Thumbnail URL
`seller.name`	string	Название магазина

Ответ upload-image {#upload-image-response}

Поле	Тип	Описание
`channel`	string	Маркетплейс, который сохранил изображение
`image_id`	string	Повторно используйте в поиске по изображению

Выбор variant {#variant-selection}

Загрузите detail → прочитайте product.variants.
Сгруппируйте по attributes[].original_name для dimension pickers (или по prop_id, если есть).
Фильтруйте variants по каждому выбору пользователя; отключайте options без остатка.
Передайте соответствующие sku_id и source_product_id в order preview.

Ключи сопоставления: для Taobao предпочитайте prop_id + value_id, если они заданы (стабильные CPV-идентификаторы; избегают путаницы, когда много SKU делят одно имя атрибута). Для группировки UI используйте 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 (у upstream SkuAttribute нет valueId).

Get Support

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

Email support