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}

StandardProductDetail {#standard-product-detail}

Snapshot sản phẩm đầy đủ cho trang sản phẩm và checkout. Map sang đơn hàng: search/detail id → lines[].id (offer_id / Taobao mi_id still accepted), variants[].sku_id → spec_id (Procurement orders).

Danh tính & kênh

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

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.

Media (images[], videos)

Attributes so với variants

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

Object variant (variants[])

Kích thước kiện SKU (variants[].shipping)

Ánh xạ từ upstream 1688 productShippingInfo.skuShippingDetails (SkuShippingDetail). Taobao không có tương đương — luôn null. Giá trị rỗng hoặc 0 được chuẩn hóa thành null; nếu SKU không có dữ liệu, shipping là null.

Khi ước tính cước, ưu tiên official_*, rồi kích thước/trọng lượng người bán, rồi ai_weight_kg (dùng ai_weight_accuracy làm gợi ý độ tin cậy).

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

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

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

Khả dụng field theo kênh

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.

StandardProductListItem

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

Chọn variant {#variant-selection}

1. Load detail → đọc product.variants.
2. Nhóm theo attributes[].original_name cho bộ chọn chiều (hoặc theo prop_id nếu có).
3. 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.
4. Truyền sku_id và source_product_id khớp sang order preview.

Khóa khớp: với Taobao, ưu tiên prop_id + value_id khi có (định danh CPV ổn định; tránh nhầm khi nhiều SKU dùng cùng tên thuộc tính). Nhóm UI dùng original_name + original_value. name / value chỉ để hiển thị. Không suy luận kiểu ngữ nghĩa từ nhãn.

{
  "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 dùng cùng cấu trúc: prop_id ← attributeId và value_id: null (SkuAttribute upstream không có valueId).