Produkt-API-Antwortmodelle

Mit response_format: "standard" (Standard) geben Produkt-Endpoints die folgenden Typen zurück. Kanonisches TypeScript: packages/shared/src/products.ts.

Endpoints: Detail · Suche · Bildsuche · Parse

Response-Envelope {#envelope}

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

StandardProductDetail {#standard-product-detail}

Vollständiger Produktsnapshot für Produktseiten und Checkout. Mapping auf Bestellungen: search/detail id → lines[].id (offer_id / Taobao mi_id still accepted), variants[].sku_id → spec_id (Beschaffungsbestellungen).

Identität & Channel

Feld	Typ	Beschreibung
`id`	string	Taobao = `mi_id` (Bestell-`lines[].id`; ändert sich regelmäßig — nicht langfristig cachen). 1688 = `offerId`. Weidian derzeit `prod_weidian_{source_product_id}`
`channel`	string	`1688`, `taobao` oder `weidian`
`source_product_id`	string	1688 = `offerId` (same as `id`); Taobao = original `item_id`
`source_url`	string	Kanonische Produktseiten-URL

Lokalisierter Text (`title`, `description`)

Feld	Typ	Beschreibung
`original`	string	Marketplace-Text (typischerweise Chinesisch)
`translated`	string \| null	Übersetzung für angefragtes `language`
`language`	string	Locale von `translated`
`description`	object \| null	Ausführliches Detail (oft HTML)

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

Alle Beträge CNY Yuan (nicht Fen). Bevorzugen Sie promotion_amount, wenn gesetzt, sonst display_amount.

Feld	Typ	Beschreibung
`price.original_amount`	number	Listenpreis vor Aktionen
`price.display_amount`	number	Käuferseitiger Preis (CNY)
`price.promotion_amount`	number \| null	Aktions-Stückpreis, falls zutreffend
`price.original_currency` / `display_currency`	string	Immer `CNY`
`price_tiers[]`	array	1688-Großhandelsstaffeln (neue Angebote ab ≥2); leer bei Taobao
`min_order_quantity`	number \| null	1688 MOQ
`distribution_min_quantity`	number \| null	1688-Dropship-Mindestmenge

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

Feld	Typ	Beschreibung
`images[].url`	string	Bild-CDN-URL
`images[].type`	enum	`main`, `gallery` oder `variant`
`videos.main` / `videos.detail`	string \| null	1688-Videos; Taobao `null`

Attribute vs. Varianten

Nur variants[] steuert SKU-Auswahl und Bestellpositionen.

Feld	Rolle
`attributes[]`	CPV-Spezifikationen - nur Anzeige, nicht für SKU-Auflösung
`variants[]`	Kaufbare SKU-Matrix mit Preis, Bestand und Spezifikationen

Variantenobjekt (`variants[]`)

Feld	Typ	Beschreibung
`sku_id`	string	Bei Order Create als `spec_id` übergeben
`upstream_sku_id`	string \| null	Numerische 1688-`skuId`
`attributes[]`	array	Spezifikationsdimensionen (Farbe, Größe, …)
`attributes[].name` / `value`	string	Anzeige-Labels (lokalisiert gemäß `language`)
`attributes[].original_name` / `original_value`	string	Stabile chinesische Schlüssel zum Gruppieren / Abgleichen
`attributes[].prop_id`	string \| null	Upstream-Attribut-ID als String (Taobao `prop_id`; 1688 `attributeId`). Bevorzugen gegenüber Namensetext
`attributes[].value_id`	string \| null	Upstream-Wert-ID als String (Taobao `value_id`). 1688 ohne valueId → `null`
`attributes[].image`	string \| null	Options-/Swatch-Bild
`price`	object	SKU-Preis in Yuan
`stock`	number	Verfügbare Menge; `0` = nicht vorrätig
`image`	string \| null	SKU-Hauptbild
`shipping`	object \| null	1688-SKU-Paketmaße (Tabelle unten); Taobao `null`
`min_order_quantity`	number \| null	1688-MOQ (Produktwert auf jeder SKU)
`distribution`	object \| null	1688-Dropship-Preise

SKU-Paketmaße (`variants[].shipping`)

Gemappt aus 1688-Upstream productShippingInfo.skuShippingDetails (SkuShippingDetail). Taobao hat kein Äquivalent — immer null. Leere oder 0-Maße/Gewichte werden zu null normalisiert; ohne Dimensionsdaten ist shipping selbst null.

Feld	Typ	Beschreibung
`width_cm`	number \| null	Breite, cm (Händlerangabe)
`length_cm`	number \| null	Länge, cm
`height_cm`	number \| null	Höhe, cm
`weight_kg`	number \| null	Gewicht, kg
`official_width_cm`	number \| null	Offiziell gemessene Breite, cm
`official_length_cm`	number \| null	Offiziell gemessene Länge, cm
`official_height_cm`	number \| null	Offiziell gemessene Höhe, cm
`official_weight_kg`	number \| null	Offiziell gemessenes Gewicht, kg
`ai_weight_kg`	number \| null	KI-vorhergesagtes Gewicht, kg
`ai_weight_accuracy`	string \| null	KI-Gewichtgenauigkeit für die Blattkategorie (z. B. `80%`)
`source`	string \| null	Maßquelle (z. B. `商家自填`)

Für Frachtschätzungen official_* bevorzugen, dann Händlerangaben, dann ai_weight_kg (mit ai_weight_accuracy als Konfidenzhinweis).

Verkäufer, Versand & Metadaten

Feld	Typ	Beschreibung
`seller.id` / `seller.name`	string	Shop-ID und Anzeigename
`seller.shop_url`	string \| null	Storefront-Link
`shipping.shipping_from`	string \| null	Inländische Versandregion
`shipping.domestic_shipping_fee`	object \| null	Geschätzte Inlandgebühr in Yuan
`metadata.raw_category`	string \| null	Upstream-Kategorie
`metadata.brand`	string \| null	Angegebene Marke
`metadata.updated_at`	string	Letzte Synchronisierung nach ISO 8601
`trade_score`	string \| null	1688-Qualitätsscore

Beispiel (gekürzt)

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

Feldverfügbarkeit nach Channel

Feld	1688	Taobao	Weidian
`videos`, `price_tiers`, `trade_score`	✓	—	Variiert
`variants[].shipping`, `distribution`	✓	—	—
`variants[].attributes[].prop_id`	✓ (`attributeId`)	✓ (`prop_id`)	—
`variants[].attributes[].value_id`	— (`null`)	✓ (`value_id`)	—
`source_product_id` für Bestellungen	`offerId`	`mi_id`	Plattform-ID

StandardProductList {#standard-product-list}

Aus Suche und Bildsuche. Jeder items[]-Eintrag ist eine Zusammenfassung - Detail aufrufen für SKU-Matrix.

Feld	Typ	Beschreibung
`channel`	string	Abgefragter Marketplace
`keyword`	string	Echo des Keywords (leer bei reiner Bildsuche)
`page` / `page_size`	number	Angewendete Paginierung
`total`	number	Upstream-Gesamtzahl (kann ungefähr sein)
`items[]`	array	`StandardProductListItem`-Objekte
`pic_region_info`	object	Bildsuche: erkannte Crop-Region

StandardProductListItem

Feld	Typ	Beschreibung
`id`, `channel`, `source_product_id`, `source_url`	string	`source_product_id` verwenden, um Detail abzurufen
`title`	LocalizedTitle	Listing-Titel
`price`	ProductPrice	Summary-Preis in CNY Yuan
`image`	string	Thumbnail-URL
`seller.name`	string	Shop-Name

Upload-image-Antwort {#upload-image-response}

Feld	Typ	Beschreibung
`channel`	string	Marketplace, der das Bild gespeichert hat
`image_id`	string	In Bildsuche wiederverwenden

Variantenauswahl {#variant-selection}

Detail laden → product.variants lesen.
Nach attributes[].original_name für Dimensionsauswahlen gruppieren (oder nach prop_id, falls vorhanden).
Varianten bei jeder Benutzerauswahl filtern; nicht vorrätige Optionen deaktivieren.
Passende sku_id und source_product_id an Order Preview übergeben.

Abgleichsschlüssel: Bei Taobao prop_id + value_id bevorzugen, wenn gesetzt (stabile CPV-Identitäten; vermeiden Vertauschungen, wenn viele SKUs denselben Attributnamen teilen). Für UI-Gruppierung auf original_name + original_value zurückfallen. name / value nur zur Anzeige. Semantische Typen nicht aus Labels ableiten.

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

Bei 1688 dieselbe Form: prop_id ← attributeId und value_id: null (Upstream-SkuAttribute ohne valueId).

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support