Model phản hồi Product API

Với response_format: "standard" (mặc định), endpoint sản phẩm trả về các kiểu dưới đây. TypeScript chính thức: packages/shared/src/products.ts.

Endpoints: detail · search · image search · parse

Envelope phản hồi {#envelope}

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

StandardProductDetail {#standard-product-detail}

Snapshot sản phẩm đầy đủ cho trang sản phẩm và checkout. Map sang đơn hàng: source_product_id → offer_id, variants[].sku_id → spec_id (Procurement orders).

Danh tính & kênh

Field	Type	Description
`id`	string	Khóa tổng hợp HIOBuy: `{channel}_{source_product_id}`
`channel`	string	`1688`, `taobao`, hoặc `weidian`
`source_product_id`	string	1688 = `offerId`; Taobao = `mi_id` (bắt buộc cho order APIs)
`source_url`	string	URL trang sản phẩm chính tắc

Văn bản bản địa hóa (`title`, `description`)

Field	Type	Description
`original`	string	Văn bản marketplace (thường là tiếng Trung)
`translated`	string \| null	Bản dịch cho `language` được yêu cầu
`language`	string	Locale của `translated`
`description`	object \| null	Chi tiết dài (thường là HTML)

Giá (`price`, `price_tiers[]`)

Tất cả số tiền là CNY yuan (không phải fen). Ưu tiên promotion_amount khi có, nếu không dùng display_amount.

Field	Type	Description
`price.original_amount`	number	Giá niêm yết trước khuyến mãi
`price.display_amount`	number	Giá hiển thị cho người mua (CNY)
`price.promotion_amount`	number \| null	Đơn giá khuyến mãi khi áp dụng
`price.original_currency` / `display_currency`	string	Luôn là `CNY`
`price_tiers[]`	array	Bậc giá sỉ 1688; rỗng trên Taobao
`min_order_quantity`	number \| null	MOQ 1688
`distribution_min_quantity`	number \| null	Số lượng tối thiểu dropship 1688

Media (`images[]`, `videos`)

Field	Type	Description
`images[].url`	string	URL CDN ảnh
`images[].type`	enum	`main`, `gallery`, hoặc `variant`
`videos.main` / `videos.detail`	string \| null	Video 1688; Taobao `null`

Attributes so với variants

Chỉ variants[] điều khiển việc chọn SKU và order lines.

Field	Vai trò
`attributes[]`	CPV specs — chỉ hiển thị, không dùng để resolve SKU
`variants[]`	Ma trận SKU có thể mua, gồm giá, tồn kho, specs

Object variant (`variants[]`)

Field	Type	Description
`sku_id`	string	Truyền làm `spec_id` khi order create
`upstream_sku_id`	string \| null	`skuId` số của 1688
`attributes[]`	array	Chiều spec (màu, size, …)
`price`	object	Giá cấp SKU theo yuan
`stock`	number	Số lượng khả dụng; `0` = hết hàng
`image`	string \| null	Ảnh chính của SKU
`shipping`	object \| null	Kích thước kiện 1688 cho freight
`distribution`	object \| null	Giá dropship 1688

Người bán, vận chuyển & metadata

Field	Type	Description
`seller.id` / `seller.name`	string	Shop id và tên hiển thị
`seller.shop_url`	string \| null	Link storefront
`shipping.shipping_from`	string \| null	Khu vực gửi hàng nội địa
`shipping.domestic_shipping_fee`	object \| null	Phí nội địa ước tính theo yuan
`metadata.raw_category`	string \| null	Danh mục upstream
`metadata.brand`	string \| null	Thương hiệu khai báo
`metadata.updated_at`	string	Lần đồng bộ cuối ISO 8601
`trade_score`	string \| null	Điểm chất lượng 1688

Ví dụ (đã rút gọn)

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

Khả dụng field theo kênh

Field	1688	Taobao	Weidian
`videos`, `price_tiers`, `trade_score`	✓	—	Tùy trường hợp
`variants[].shipping`, `distribution`	✓	—	—
`source_product_id` cho orders	`offerId`	`mi_id`	Platform id

StandardProductList {#standard-product-list}

Từ search và image search. Mỗi mục items[] là tóm tắt — gọi detail để lấy ma trận SKU.

Field	Type	Description
`channel`	string	Marketplace được truy vấn
`keyword`	string	Echo của keyword (rỗng khi chỉ tìm bằng ảnh)
`page` / `page_size`	number	Phân trang đã áp dụng
`total`	number	Tổng upstream (có thể xấp xỉ)
`items[]`	array	Object `StandardProductListItem`
`pic_region_info`	object	Tìm bằng ảnh: vùng crop được phát hiện

StandardProductListItem

Field	Type	Description
`id`, `channel`, `source_product_id`, `source_url`	string	Dùng `source_product_id` để fetch detail
`title`	LocalizedTitle	Tiêu đề listing
`price`	ProductPrice	Giá tóm tắt bằng CNY yuan
`image`	string	URL thumbnail
`seller.name`	string	Tên shop

Phản hồi upload-image {#upload-image-response}

Field	Type	Description
`channel`	string	Marketplace đã lưu ảnh
`image_id`	string	Tái sử dụng trong image search

Chọn variant {#variant-selection}

Load detail → đọc product.variants.
Nhóm theo attributes[].original_name cho bộ chọn chiều.
Lọc variant theo từng lựa chọn của người dùng; disable tùy chọn hết hàng.
Truyền sku_id và source_product_id khớp sang order preview.