Modèles de réponse de l’API Produits

Avec response_format: "standard" (par défaut), les endpoints produit retournent les types ci-dessous. TypeScript canonique : packages/shared/src/products.ts.

Endpoints : détail · recherche · recherche par image · analyse

Enveloppe de réponse {#envelope}

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

StandardProductDetail {#standard-product-detail}

Instantané complet du produit pour les pages produit et le checkout. Mapping vers les commandes : source_product_id → offer_id, variants[].sku_id → spec_id (Commandes d’approvisionnement).

Identité et canal

Champ	Type	Description
`id`	string	Clé composite HIOBuy : `{channel}_{source_product_id}`
`channel`	string	`1688`, `taobao` ou `weidian`
`source_product_id`	string	1688 = `offerId` ; Taobao = `mi_id` (obligatoire pour les API de commande)
`source_url`	string	URL canonique de page produit

Texte localisé (`title`, `description`)

Champ	Type	Description
`original`	string	Texte marketplace (généralement chinois)
`translated`	string \| null	Traduction pour le `language` demandé
`language`	string	Locale de `translated`
`description`	object \| null	Détail long format (souvent HTML)

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

Tous les montants sont en yuan CNY (pas en fen). Préférez promotion_amount lorsqu’il est défini, sinon display_amount.

Champ	Type	Description
`price.original_amount`	number	Prix catalogue avant promotions
`price.display_amount`	number	Prix affiché à l’acheteur (CNY)
`price.promotion_amount`	number \| null	Prix unitaire promotionnel le cas échéant
`price.original_currency` / `display_currency`	string	Toujours `CNY`
`price_tiers[]`	array	Paliers de gros 1688 ; vide sur Taobao
`min_order_quantity`	number \| null	MOQ 1688
`distribution_min_quantity`	number \| null	Minimum dropship 1688

Médias (`images[]`, `videos`)

Champ	Type	Description
`images[].url`	string	URL CDN de l’image
`images[].type`	enum	`main`, `gallery` ou `variant`
`videos.main` / `videos.detail`	string \| null	Vidéos 1688 ; Taobao `null`

Attributs vs variantes

Seul variants[] pilote la sélection SKU et les lignes de commande.

Champ	Rôle
`attributes[]`	Spécifications CPV — affichage uniquement, pas pour résoudre le SKU
`variants[]`	Matrice SKU achetable avec prix, stock et spécifications

Objet variante (`variants[]`)

Champ	Type	Description
`sku_id`	string	À passer comme `spec_id` lors de la création de commande
`upstream_sku_id`	string \| null	`skuId` numérique 1688
`attributes[]`	array	Dimensions de spécification (couleur, taille, …)
`price`	object	Prix au niveau SKU en yuan
`stock`	number	Quantité disponible ; `0` = rupture de stock
`image`	string \| null	Image principale du SKU
`shipping`	object \| null	Dimensions de colis 1688 pour le fret
`distribution`	object \| null	Tarification dropship 1688

Vendeur, expédition et métadonnées

Champ	Type	Description
`seller.id` / `seller.name`	string	ID boutique et nom affiché
`seller.shop_url`	string \| null	Lien de boutique
`shipping.shipping_from`	string \| null	Région d’expédition domestique
`shipping.domestic_shipping_fee`	object \| null	Frais domestiques estimés en yuan
`metadata.raw_category`	string \| null	Catégorie upstream
`metadata.brand`	string \| null	Marque déclarée
`metadata.updated_at`	string	Dernière synchronisation ISO 8601
`trade_score`	string \| null	Score qualité 1688

Exemple (tronqué)

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

Disponibilité des champs par canal

Champ	1688	Taobao	Weidian
`videos`, `price_tiers`, `trade_score`	✓	—	Variable
`variants[].shipping`, `distribution`	✓	—	—
`source_product_id` pour les commandes	`offerId`	`mi_id`	ID plateforme

StandardProductList {#standard-product-list}

Depuis recherche et recherche par image. Chaque entrée items[] est un résumé — appelez le détail pour la matrice SKU.

Champ	Type	Description
`channel`	string	Marketplace interrogée
`keyword`	string	Écho du mot-clé (vide pour une recherche purement par image)
`page` / `page_size`	number	Pagination appliquée
`total`	number	Total upstream (peut être approximatif)
`items[]`	array	Objets `StandardProductListItem`
`pic_region_info`	object	Recherche par image : région de recadrage détectée

StandardProductListItem

Champ	Type	Description
`id`, `channel`, `source_product_id`, `source_url`	string	Utilisez `source_product_id` pour récupérer le détail
`title`	LocalizedTitle	Titre de listing
`price`	ProductPrice	Prix résumé en yuan CNY
`image`	string	URL de vignette
`seller.name`	string	Nom de boutique

Réponse upload-image {#upload-image-response}

Champ	Type	Description
`channel`	string	Marketplace qui a stocké l’image
`image_id`	string	Réutilisation dans recherche par image

Sélection de variante {#variant-selection}

Chargez détail → lisez product.variants.
Groupez par attributes[].original_name pour les sélecteurs de dimension.
Filtrez les variantes à chaque choix utilisateur ; désactivez les options en rupture de stock.
Passez le sku_id correspondant et source_product_id à prévisualisation de commande.