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}

StandardProductDetail {#standard-product-detail}

Instantané complet du produit pour les pages produit et le checkout. Mapping vers les commandes : search/detail id → lines[].id (offer_id / Taobao mi_id still accepted), variants[].sku_id → spec_id (Commandes d’approvisionnement).

Identité et canal

Texte localisé (title, description)

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.

Médias (images[], videos)

Attributs vs variantes

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

Objet variante (variants[])

Dimensions de colis SKU (variants[].shipping)

Mappé depuis l’upstream 1688 productShippingInfo.skuShippingDetails (SkuShippingDetail). Taobao n’a pas d’équivalent — toujours null. Les tailles/poids vides ou 0 sont normalisés en null ; sans données, shipping est null.

Pour l’estimation fret, préférer official_*, puis les valeurs marchand, puis ai_weight_kg (avec ai_weight_accuracy comme indice de confiance).

Vendeur, expédition et métadonnées

Exemple (tronqué)

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

Disponibilité des champs par canal

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.

StandardProductListItem

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

Sélection de variante {#variant-selection}

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

Clés de correspondance : sur Taobao, privilégiez prop_id + value_id lorsqu’ils sont présents (identités CPV stables ; évitent les mélanges quand plusieurs SKU partagent le même nom d’attribut). Pour le regroupement UI, utilisez original_name + original_value. name / value uniquement pour l’affichage. N’inférez pas de type sémantique à partir des libellés.

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

Sur 1688, même forme : prop_id ← attributeId et value_id: null (SkuAttribute upstream sans valueId).