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}

Endpoint	Forma
`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 completo de producto para páginas de producto y checkout. Mapea a pedidos: source_product_id → offer_id, variants[].sku_id → spec_id (Pedidos de compra).

Identidad y canal

Campo	Tipo	Descripción
`id`	string	Clave compuesta de HIOBuy: `{channel}_{source_product_id}`
`channel`	string	`1688`, `taobao` o `weidian`
`source_product_id`	string	1688 = `offerId`; Taobao = `mi_id` (obligatorio para API de pedidos)
`source_url`	string	URL canónica de la página de producto

Texto localizado (`title`, `description`)

Campo	Tipo	Descripción
`original`	string	Texto del marketplace (normalmente chino)
`translated`	string \| null	Traducción para el `language` solicitado
`language`	string	Locale de `translated`
`description`	object \| null	Detalle largo (a menudo HTML)

Precios (`price`, `price_tiers[]`)

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

Campo	Tipo	Descripción
`price.original_amount`	number	Precio de lista antes de promociones
`price.display_amount`	number	Precio visible para el comprador (CNY)
`price.promotion_amount`	number \| null	Precio unitario promocional cuando aplique
`price.original_currency` / `display_currency`	string	Siempre `CNY`
`price_tiers[]`	array	Tramos mayoristas de 1688; vacío en Taobao
`min_order_quantity`	number \| null	MOQ de 1688
`distribution_min_quantity`	number \| null	Mínimo dropship de 1688

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

Campo	Tipo	Descripción
`images[].url`	string	URL CDN de imagen
`images[].type`	enum	`main`, `gallery` o `variant`
`videos.main` / `videos.detail`	string \| null	Videos de 1688; Taobao `null`

Atributos frente a variantes

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

Campo	Rol
`attributes[]`	Especificaciones CPV: solo visualización, no para resolución de SKU
`variants[]`	Matriz de SKU comprable con precio, stock y especificaciones

Objeto de variante (`variants[]`)

Campo	Tipo	Descripción
`sku_id`	string	Pásalo como `spec_id` al crear el pedido
`upstream_sku_id`	string \| null	`skuId` numérico de 1688
`attributes[]`	array	Dimensiones de especificación (color, talla, …)
`price`	object	Precio a nivel SKU en yuanes
`stock`	number	Cantidad disponible; `0` = sin stock
`image`	string \| null	Imagen principal del SKU
`shipping`	object \| null	Dimensiones de paquete de 1688 para flete
`distribution`	object \| null	Precios dropship de 1688

Vendedor, envío y metadatos

Campo	Tipo	Descripción
`seller.id` / `seller.name`	string	Id de tienda y nombre mostrado
`seller.shop_url`	string \| null	Enlace a la tienda
`shipping.shipping_from`	string \| null	Región de despacho nacional
`shipping.domestic_shipping_fee`	object \| null	Tarifa nacional estimada en yuanes
`metadata.raw_category`	string \| null	Categoría upstream
`metadata.brand`	string \| null	Marca declarada
`metadata.updated_at`	string	Última sincronización ISO 8601
`trade_score`	string \| null	Puntuación de calidad de 1688

Ejemplo (truncado)

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

Disponibilidad de campos por canal

Campo	1688	Taobao	Weidian
`videos`, `price_tiers`, `trade_score`	✓	—	Varía
`variants[].shipping`, `distribution`	✓	—	—
`source_product_id` para pedidos	`offerId`	`mi_id`	Id de plataforma

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.

Campo	Tipo	Descripción
`channel`	string	Marketplace consultado
`keyword`	string	Eco de la palabra clave (vacío para búsqueda solo por imagen)
`page` / `page_size`	number	Paginación aplicada
`total`	number	Total upstream (puede ser aproximado)
`items[]`	array	Objetos `StandardProductListItem`
`pic_region_info`	object	Búsqueda por imagen: región de recorte detectada

StandardProductListItem

Campo	Tipo	Descripción
`id`, `channel`, `source_product_id`, `source_url`	string	Usa `source_product_id` para obtener detalle
`title`	LocalizedTitle	Título del listado
`price`	ProductPrice	Precio resumido en yuanes CNY
`image`	string	URL de miniatura
`seller.name`	string	Nombre de tienda

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

Campo	Tipo	Descripción
`channel`	string	Marketplace que almacenó la imagen
`image_id`	string	Reutilizar en búsqueda por imagen

Selección de variantes {#variant-selection}

Carga detalle → lee product.variants.
Agrupa por attributes[].original_name para selectores de dimensión.
Filtra variantes según cada elección del usuario; deshabilita opciones sin stock.
Pasa el sku_id y source_product_id coincidentes a order preview.