# 1688 商品详情 API (alibaba1688.product_detail)

- Canonical page: https://everyinfra.com/alibaba1688-api/product_detail
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "alibaba1688", "action": "product_detail", "params": {...}}
- Price: $0.001389 per call ($1.39 per 1,000 requests); failed calls and empty results are not charged
- Returns: single object
- Mode: sync; add "mode": "async" for slow tasks

1688 商品详情读取一件批发商品的完整公开信息：价格区间与阶梯价、起订量和计价单位、库存与销量、规格明细、评分与好评率、商品图，以及供应商名称、类型、成立年份、粉丝和收藏数，是否支持拿样和一件代发。它回答「从这家拿货划不划算、靠不靠谱」，适合采购评估和供应商比较。

`url` 可以传 1688 商品链接、含唯一商品链接的分享文本，或纯数字 offerId；店铺首页和搜索页会被拒绝。读价格时配合 `price_tiers` 看，买得越多单价越低；`positive_rate` 是 0 到 1 的小数；`skus` 里的选项、价格和库存只在平台明确给出时返回，缺失不等于无货。

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=alibaba1688&action=product_detail

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| url | not declared | yes | not declared | 1688 单品定位。product_detail 接收 detail.1688.com 或 m.1688.com 的正规商品 URL、含唯一商品 URL 的分享文本或纯数字 offerId；qr.1688.com 分享短链仅在可安全解析到商品页时接受。店铺首页和搜索页会拒绝。商品已下架或不存在时返回空结果，empty_reason 为 item_not_found，不扣费；24 小时内再查同一件商品，结果相同，仍不扣费。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | 该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。 |
| url | 该记录在原平台上的可访问链接。 |
| title | 标题。平台无标题概念时（如纯文本帖）为 null。 |
| text | 正文内容，已去除 HTML 标签，全文返回、不截断（个别平台的列表结果本身只有摘要，以该平台的字段说明为准）。 |
| price_min | 价格区间下限。 |
| price_max | 价格区间上限。 |
| currency | 价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。 |
| price_tiers | 阶梯价（买得越多单价越低）：[{min_quantity, max_quantity, price}]，max_quantity 是该档上限（最后一档没有）。不分数量档的商品没有这个字段，价格看 price_min / price_max。 |
| min_order_quantity | 最小起订量(MOQ)。**1688 批发场景的第一门槛，采购前先看它**。 |
| stock | 库存。商品详情同步调用时可能为空；异步调用通常有值。 |
| sold_count | 销量（数字）；只有约数（如 10万+）时缺省，原文见 sold_display。 |
| category | 分类名称，取值为原平台的分类体系，未做跨平台归一。商品详情同步调用时可能为空；异步调用通常有值。 |
| unit | 计价单位（个/件/箱）。 |
| supplier_name | 供应商名称。 |
| supplier_fans | 供应商粉丝数。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_founded_year | 供应商成立年份。 |
| supplier_type | 供应商经营模式（如 生产加工、经销批发）。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_favorited_count | 被收藏次数。商品详情同步调用时可能为空；异步调用通常有值。 |
| supports_dropship | 是否支持一件代发。做无货源电商的关键筛选项。商品详情同步调用时可能为空；异步调用通常有值。 |
| supports_sampling | 是否支持拿样。商品详情同步调用时可能为空；异步调用通常有值。 |
| is_out_of_stock | 是否缺货。商品详情同步调用时可能为空；异步调用通常有值。 |
| skus | 可获取的规格明细；每行的选项、价格、库存和可售状态仅在平台数据明确给出时返回，缺失不等于无货。product_detail 的规格行另有包装重量 weight_g（克）与尺寸 length_cm / width_cm / height_cm / volume_cm3（平台给了才有）。商品详情同步调用时，规格行里的 weight_g、length_cm、width_cm、height_cm、volume_cm3、image_url、original_price 可能为空；需要这几项请用异步调用。 |
| images | 商品主图链接，按页面顺序；product_detail 里有的商品还带规格图，详情区的图在 description_images。没有图片时不出现这个字段。 |
| description_images | 详情描述图 URL 列表（按商品页原顺序）；null 表示该商品无详情图。商品详情同步调用时可能为空；异步调用通常有值。 |
| video_url | 商品视频链接（如有）。 |
| specs | 商品参数/规格表：[{name, value}] 键值对列表（如 材质: TPU）。商品详情同步调用时可能为空；异步调用通常有值。 |
| rating | 商品综合评分（1-5）。商品详情同步调用时可能为空；异步调用通常有值。 |
| rating_scale | 上一列 `rating` 的满分。5 表示五星制、10 表示十分制。只在该行有 rating 时出现。商品详情同步调用时可能为空；异步调用通常有值。 |
| review_count | 累计评价数。商品详情同步调用时可能为空；异步调用通常有值。 |
| positive_rate | 好评率（0-1 小数，如 0.999 = 99.9%）。商品详情同步调用时可能为空；异步调用通常有值。 |
| sold_display | 销量的原文展示（如 已售10万+件）；数字形式见 sold_count。商品详情同步调用时可能为空；异步调用通常有值。 |
| want_buy_count | 想要/求购人数（采购意向热度参考）。商品详情同步调用时可能为空；异步调用通常有值。 |
| category_path | 完整类目路径（如 数码、电脑 > 手机配件 > 手机保护套）；product_detail 常缺省，类目名见 category。商品详情同步调用时可能为空；异步调用通常有值。 |
| services | 商品服务标签列表（如 退货包运费、晚发即赔）。商品详情同步调用时可能为空；异步调用通常有值。 |
| promotions | 当前生效的促销活动名称列表。 |
| customization_supported | 是否支持定制（来图定制/打样等）。商品详情同步调用时可能为空；异步调用通常有值。 |
| winport_url | 供应商 1688 诚信通店铺链接。 |
| city | 城市名，用原平台的语言书写，未做中英归一。商品详情同步调用时可能为空；异步调用通常有值。 |
| province | 供应商所在省份。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_years | 供应商在 1688 平台的年数。商品详情同步调用时可能为空；异步调用通常有值。 |
| package_dimensions | 单件包装尺寸（product_detail）：length_cm、width_cm、height_cm、volume_cm3。 |
| coupons | 店铺券与权益列表：每项含 type（类型代码）、type_name（类型名）、label（标签，如 满50包邮）、summary（说明）、valid_from / valid_to（有效期，原文时间）、link_url（活动页）、id；字段缺失时没有该子键。 |
| promotion_details | 促销活动明细：activity_id、name、type（如 sellerProm 店铺活动 / officialProm 平台活动）、detail / summary（规则说明）、valid_period（有效期原文）、discount_amount（优惠金额，元）、original_price_range（活动前价格区间原文）、note（补充说明，如不免邮区域）、link_url。promotions 仍只给名称。 |
| service_details | 服务保障明细：code（服务代码）、name、description（规则说明）、rule_url（规则页）。services / service_tags 只给名称。商品详情同步调用时可能为空；异步调用通常有值。 |
| purchase_limits | 限购：per_buyer（每个买家限购件数）、promotion_per_buyer（活动价限购件数）；-1 表示不限购。 |
| mix_wholesale | 混批条件：min_amount（混批起批金额，元）、min_varieties（最少款数）。 |
| supports_mix | 是否支持混批（不同款式凑单起批）。商品详情同步调用时可能为空；异步调用通常有值。 |
| review_tags | 买家印象标签：[{tag, count}]，如 面料软糯 ×2。商品详情同步调用时可能为空；异步调用通常有值。 |
| refund_rate | 退款率（0-1 小数）。 |
| review_negative_count | 差评数；null 表示没给，不等于 0。 |
| review_neutral_count | 中评数；null 表示没给，不等于 0。 |
| review_with_photo_count | 带图评价数；null 表示没给，不等于 0。商品详情同步调用时可能为空；异步调用通常有值。 |
| review_with_text_count | 有文字的评价数；null 表示没给，不等于 0。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_stats | 供应商画像（只含有值的子键）：employee_count（员工数）、plant_area_sqm（厂房面积，平方米）、plant_type（厂房类型，如 自有工厂）、equipment_count（主要设备数）、product_count（在售商品数）、repeat_rate（回头率 0-1）、repeat_buyer_count_text / cross_border_buyer_count_text（回头客数、跨境买家数原文，如 300+）、response_rate（响应率 0-1）、positive_review_rate（好评率 0-1）、fulfillment_rate（履约率 0-1）、certificate_count / certificates / management_certificates（证书数、证书名、管理体系认证）、patent_count（专利数）、oem_mode（OEM/ODM）、own_brands（自有品牌原文）、brand_count、partner_brand（合作品牌）、is_major_brand_partner（是否大牌供应商）、scale_tier（规模档，如 规上企业）、honors（荣誉）。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_scores | 供应商分项服务分（1-5，没有评分的项不给）：goods（商品）、logistics（物流）、consultation（咨询）、dispute（纠纷）、return（退换货）；综合分见 supplier_composite_score。 |
| supplier_metric_tags | 工厂指标标签：[{name, value}]，如 回头率 66%、履约率 100%。 |
| supplier_rank | 供应商上榜信息：text（如 2026上榜二钻工厂）、link_url（榜单页）。 |
| supplier_industry_belt | 产业带认证：description（如 1688官方认证的安阳连身衣产业带旗舰商家）、link_url（认证说明页）。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_certification | 第三方验厂/验商认证：agency（认证机构代码，如 sgs、tuv）、report_number（报告编号原文）、report_url（报告页）。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_verification_tags | 供应商认证标签，如 深度验厂、深度验商。 |
| supplier_inspection_report_url | 验厂/验商报告页链接。 |
| supplier_videos | 工厂/公司视频：video_id、title、type（视频类型代码）、video_url、cover_url、duration_sec（秒）。 |
| supplier_address | 供应商地址原文。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_coordinates | 供应商位置坐标：{longitude（经度）, latitude（纬度）}。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_main_category | 供应商主营类目。商品详情同步调用时可能为空；异步调用通常有值。 |
| customization | 定制服务（只含有值的子键）：title（定制说明）、lead_time_days（定制交期，天）、min_order_quantity / min_order_unit（定制起订量与单位）、services（可定制项，如 更换客户标）、options（定制选项：service 选项名、selection 单选/多选、choices[] 每个选择的 name、description、is_default、min_value / max_value / unit（尺寸类取值范围）、image_url、price_tiers[{min_quantity, price}] 加价阶梯）。是否支持定制看 customization_supported。 |
| shipping | 物流（只含有值的子键）：carrier（常用快递）、logistics_text（物流说明原文）、dispatch_hours / dispatch_text（预计发货时长与说明）、delivery_days / delivery_hours（预计送达时长）、fee（运费，元）、is_free_shipping（是否包邮）、ship_from（发货地）、ship_from_code（发货地行政区划代码）、fee_note（运费说明）。 |
| unit_weight_kg | 单件重量（千克）。商品详情同步调用时可能为空；异步调用通常有值。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "alibaba1688",
  "action": "product_detail",
  "params": {
    "url": "https://detail.1688.com/offer/873514490218.html"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "alibaba1688",
        "action": "product_detail",
        "params": {
            "url": "https://detail.1688.com/offer/873514490218.html",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-10-13T04:57:06Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "alibaba1688",
  "action": "product_detail",
  "results": {
    "id": "•••",
    "url": "https://detail.1688.com/offer/873514490218.html",
    "title": "跨境专供Pro6蓝牙耳机真无线入耳式超长续航tws运动无线蓝牙耳机",
    "price_min": 7.1,
    "price_max": 13.8,
    "currency": "CNY",
    "min_order_quantity": 2,
    "stock": 7682692,
    "sold_count": 16813,
    "category": "蓝牙耳机",
    "unit": "条",
    "supplier_name": "深圳高耳基科技有限公司",
    "supplier_fans": "582",
    "supplier_type": "normal_factory",
    "supplier_favorited_count": 582,
    "supports_dropship": {
      "enabled": false,
      "consignPrice": null,
      "consignPriceTiers": [],
      "channels": [],
      "channelDetails": [],
      "protections": [],
      "downstreamPerformance": null,
      "metrics": {
        "orders30d": null,
        "orders7d": null,
        "pickupRate48h": null,
        "pickupRate24h": null,
        "distributorCount": null,
        "downstreamStoreCount": null,
        "publishDate": null
      }
    },
    "supports_sampling": false,
    "is_out_of_stock": false,
    "skus": [
      {
        "id": "•••",
        "name": "Pro6蓝牙耳机  紫色",
        "options": {
          "颜色": "Pro6蓝牙耳机  紫色"
        },
        "price": 7.6,
        "original_price": 7.6,
        "stock": 665434,
        "available": true,
        "image_url": "https://cbu01.alicdn.com/img/ibank/O1CN01ngwdIg1fNlJ87ZHWL_!!2218564053995-0-cib.jpg"
      },
      {
        "id": "•••",
        "name": "八代蓝牙耳机简配",
        "options": {
          "颜色": "八代蓝牙耳机简配"
        },
        "price": 9.6,
        "original_price": 9.6,
        "stock": 666024,
        "available": true
      },
      {
        "id": "•••",
        "name": "Pro6蓝牙耳机 粉色",
        "options": {
          "颜色": "Pro6蓝牙耳机 粉色"
        },
        "price": 7.6,
        "original_price": 7.6,
        "stock": 664567,
        "available": true,
        "image_url": "https://cbu01.alicdn.com/img/ibank/O1CN01VHBm431fNlJGJw3Jm_!!2218564053995-0-cib.jpg"
      }
    ],
    "images": [
      "https://cbu01.alicdn.com/img/ibank/O1CN01RrMK531fNlLKVri2p_!!2218564053995-0-cib.jpg",
      "https://cbu01.alicdn.com/img/ibank/O1CN01oiS7FO1fNlJFcPVcJ_!!2218564053995-0-cib.jpg",
      "https://cbu01.alicdn.com/img/ibank/O1CN019hrirk1fNlJGpWQke_!!2218564053995-0-cib.jpg"
    ],
    "description_images": [
      "https://cbu01.alicdn.com/img/ibank/O1CN01xDu8VE1fNlOMt4i8Z_!!2218564053995-0-cib.jpg",
      "https://cbu01.alicdn.com/img/ibank/O1CN01mTmUSS1fNlONCMZWr_!!2218564053995-0-cib.jpg",
      "https://cbu01.alicdn.com/img/ibank/O1CN01myoX5I1fNlONcSew0_!!2218564053995-0-cib.jpg"
    ],
    "video_url": "https://cloud.video.taobao.com/play/u/2218564053995/p/2/e/6/t/1/482069395965.mp4",
    "specs": [
      {
        "name": "芯片类型",
        "value": "中科蓝讯"
      },
      {
        "name": "功能",
        "value": "防水,降噪,呼吸灯,超长续航,通话功能,语音控制,支持音乐,数显屏幕,电竞低延迟"
      },
      {
        "name": "续航时间",
        "value": "0-4小时"
      }
    ],
    "rating": 4.7,
    "review_count": 20,
    "positive_rate": 0.95,
    "sold_display": "已售2.2万+件",
    "want_buy_count": 127,
    "category_path": "数码、电脑 > 手机配件 > 蓝牙耳机",
    "services": [
      "7天无理由退货",
      "晚发必赔"
    ],
    "winport_url": "https://winport.1688.com/page/index.html?memberId=b2b-2218564053995870c8&_tabId_=index&upstreamSource=od&offerId=873514490218",
    "platform": "1688",
    "rating_scale": 5
  },
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 阶梯价怎么读？

`price_tiers` 列出不同采购数量对应的单价，买得越多单价越低；`min_order_quantity` 是起订量，`unit` 是计价单位。估算采购成本时，按计划采购量落在哪一档来算。

### 怎么判断供应商是工厂还是贸易商？

看 `supplier_type`，它标明是生产商还是贸易商；再结合 `supplier_founded_year`、`supplier_fans` 和 `supplier_favorited_count`，判断供应商的经营年限和受关注程度。

### 规格里没有库存信息是缺货吗？

不一定。`skus` 里每行的选项、价格、库存和可售状态只在平台数据明确给出时返回，缺失不等于无货；判断商品整体是否缺货，请看 `is_out_of_stock`。同步调用时 `stock`、`positive_rate`、`supports_dropship`，以及类目、评价、服务、供应商资料和规格行的尺寸重量等字段可能为空（完整清单见字段说明），需要这些请用异步调用。

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=alibaba1688
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
