Modelos de respuesta de la API de productos

Con response_format: "standard" (predeterminado), los endpoints de producto devuelven los tipos siguientes. TypeScript canónico: packages/shared/src/products.ts.

Endpoints: detalle · búsqueda · búsqueda por imagen · parse

Envoltorio de respuesta {#envelope}

StandardProductDetail {#standard-product-detail}

Snapshot completo de producto para páginas de producto y checkout. Mapea a pedidos: search/detail id → lines[].id (offer_id / Taobao mi_id still accepted), variants[].sku_id → spec_id (Pedidos de compra).

Identidad y canal

Texto localizado (title, description)

Precios (price, price_tiers[])

Todos los importes son yuanes CNY (no fen). Prefiere promotion_amount cuando esté definido; en caso contrario, display_amount.

Medios (images[], videos)

Atributos frente a variantes

Solo variants[] controla la selección de SKU y las líneas de pedido.

Objeto de variante (variants[])

Dimensiones de paquete SKU (variants[].shipping)

Mapeado desde el upstream 1688 productShippingInfo.skuShippingDetails (SkuShippingDetail). Taobao no tiene equivalente — siempre null. Valores vacíos o 0 se normalizan a null; sin datos, shipping es null.

Para estimar flete, prioriza official_*, luego lo declarado por el vendedor, luego ai_weight_kg (con ai_weight_accuracy como pista de confianza).

Vendedor, envío y metadatos

Ejemplo (truncado)

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

Disponibilidad de campos por canal

StandardProductList {#standard-product-list}

Desde búsqueda y búsqueda por imagen. Cada entrada items[] es un resumen; llama a detail para la matriz SKU.

StandardProductListItem

Respuesta upload-image {#upload-image-response}

Selección de variantes {#variant-selection}

1. Carga detalle → lee product.variants.
2. Agrupa por attributes[].original_name para selectores de dimensión (o por prop_id si está presente).
3. Filtra variantes según cada elección del usuario; deshabilita opciones sin stock.
4. Pasa el sku_id y source_product_id coincidentes a order preview.

Claves de coincidencia: en Taobao, prioriza prop_id + value_id cuando existan (identidades CPV estables; evitan cruces cuando muchas SKU comparten el mismo nombre de atributo). Para agrupar en UI, usa original_name + original_value. name / value solo para mostrar. No infieras tipos semánticos a partir de las etiquetas.

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

En 1688 se usa la misma forma: prop_id ← attributeId y value_id: null (SkuAttribute upstream no tiene valueId).