1688商品详情 API

Q: 阶梯价怎么读？

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

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

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

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

不一定。skus 里每行的选项、价格、库存和可售状态只在平台数据明确给出时返回，缺失不等于无货；判断商品整体是否缺货，请看 is_out_of_stock。

POST

接口健康状态

24h 健康值: 正常
24h 平均耗时: —

健康 / 正常
可用
少量可用
基本不可用

正常

24 小时趋势

30 天趋势

商品详情：返回单个对象；主要字段 id、url、title、text、price_min、price_max。

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

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

单价 $1.39 / 千次（每次 $0.001389），失败与空结果不扣费。同步返回；慢任务可在请求体加 "mode": "async"，先拿 job_id 再轮询。

AI 提示词

复制下面这段给你常用的 AI 助手：里面写好了这个接口的参数、返回字段和示例请求，它会先问清你的需求，再帮你写采集脚本。

请帮我用 EveryInfra 的「1688 商品详情」接口（alibaba1688/product_detail）写一个数据采集脚本。

接口约定：
- 请求：POST https://api.everyinfra.com/api/v1/social，请求头 Authorization: Bearer <API Key>；Key 从环境变量 EVERYINFRA_API_KEY 读取，不要写进代码。
- 请求体里 platform 填 alibaba1688，action 填 product_detail，参数放在 params 里。
- 必填参数：
  - url：1688 单品定位。product_detail 接收 detail.1688.com 或 m.1688.com 的正规商品 URL、含唯一商品 URL 的分享文本或纯数字 offerId。
- 返回一个对象，主要字段：id、url、title、text、price_min（价格区间下限）、price_max（价格区间上限）、currency、price_tiers（阶梯价（买得越多单价越低））、min_order_quantity（最小起订量(MOQ)）、stock（库存）、sold_count（销量）、category；一共 37 个字段，完整列表见 https://api.everyinfra.com/api/v1/social/catalog?platform=alibaba1688。
- 示例请求体：
{
  "platform": "alibaba1688",
  "action": "product_detail",
  "params": {
    "url": "https://detail.1688.com/offer/873514490218.html"
  }
}
- 计费：$1.39 / 千次；失败和空结果不扣费。
- 一次要采几十上百个时，在请求体加 "mode": "async"：先拿到 job_id，再轮询 GET https://api.everyinfra.com/api/v1/jobs/{job_id} 取结果。
- 返回 422 时，按错误信息里的候选参数和允许值修正；返回 429 或 503 时，按 Retry-After 等待后重试。

写代码前，先问清楚我要采哪些对象、一共多少个、需要哪些字段、结果存成什么格式，再把方案和大概花费讲给我确认。

请求参数

参数名	位置	类型	必填	默认值	说明
`Authorization`	header	`string`	是	-	Bearer 加你的 API Key。在控制台创建；不要放进网址或代码仓库。
`platform`	body	`string`	是	`alibaba1688`	平台标识，固定值。
`action`	body	`string`	是	`product_detail`	能力标识，固定值。
`url`	body.params	未声明	是	-	1688 单品定位。product_detail 接收 detail.1688.com 或 m.1688.com 的正规商品 URL、含唯一商品 URL 的分享文本或纯数字 offerId；qr.1688.com 分享短链仅在可安全解析到商品页时接受。店铺首页和搜索页会拒绝。

代码示例

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"
  }
}'

[OpenAPI 定义 (JSON)]示例从环境变量 EVERYINFRA_API_KEY 读取 Key，复制出去的代码不含你的 Key。

响应示例

真实返回样例

2026年10月13日 12:57（北京时间）用上方代码示例的参数真实调用所得。results 与 count 是那次的真实返回，已隐去名字、账号、头像、主页链接、联系方式等个人信息；id、billing、quota 每次调用都不同，只给结构。

json

{
  "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": { … }
}

返回字段

业务数据在 results 里；下表是每条记录可能包含的字段，平台没有提供的值不会被补造。

字段	含义
`id`	该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。
`url`	该记录在原平台上的可访问链接。
`title`	标题。平台无标题概念时（如纯文本帖）为 null。
`text`	正文内容，已去除 HTML 标签，全文返回、不截断（个别平台的列表结果本身只有摘要，以该平台的字段说明为准）。
`price_min`	价格区间下限。
`price_max`	价格区间上限。
`currency`	价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。
`price_tiers`	阶梯价（买得越多单价越低），配合 min_quantity 读。
`min_order_quantity`	最小起订量(MOQ)。1688 批发场景的第一门槛，采购前先看它。
`stock`	库存。
`sold_count`	销量。
`category`	分类名称，取值为原平台的分类体系，未做跨平台归一。
`unit`	计价单位（个/件/箱）。
`supplier_name`	供应商名称。
`supplier_fans`	供应商粉丝数。
`supplier_founded_year`	供应商成立年份。
`supplier_type`	供应商经营模式（如生产加工、经销批发）。
`supplier_favorited_count`	被收藏次数。
`supports_dropship`	是否支持一件代发。做无货源电商的关键筛选项。
`supports_sampling`	是否支持拿样。
`is_out_of_stock`	是否缺货。
`skus`	可获取的规格明细；每行的选项、价格、库存和可售状态仅在平台数据明确给出时返回，缺失不等于无货。
`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`	完整类目路径（如数码、电脑 > 手机配件 > 手机保护套）。
`services`	商品服务标签列表（如退货包运费、晚发即赔）。
`promotions`	当前生效的促销活动名称列表。
`customization_supported`	是否支持定制（来图定制/打样等）。
`winport_url`	供应商 1688 诚信通店铺链接。
`platform`	数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。

常见问题

阶梯价怎么读？

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

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

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

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

不一定。skus 里每行的选项、价格、库存和可售状态只在平台数据明确给出时返回，缺失不等于无货；判断商品整体是否缺货，请看 is_out_of_stock。

错误与计费

401: 缺少 Key 或 Key 无效。先鉴权再校验参数，未鉴权的请求拿不到参数结构。
422: 参数名或取值不对。错误信息会列出这项能力支持的参数、允许值和最接近的候选，按它改即可；发生在扣费之前。
402: 余额不足，请先充值。
429: 超过账户的每分钟请求上限（名下所有 Key 合计；Key 自设了更低上限时先按它算），按 Retry-After 等待后再试。需要更高上限可在控制台买提速包。
503: 暂时无法完成。已预扣的费用按原账本退回；响应里的 billing 与 refund 写明实际结果，结果未知时会明确标出，不要直接重发。
200 空结果: 请求完成但没有数据，不扣费（billing.reason = empty_result_refunded）。