BuyEasy OpenAPI 文档

1688 商品与采购 API

按统一协议接入 1688 搜索、详情、关联商品和跨境采购

BuyEasy 负责签名、鉴权、计费、日志和平台授权管理，客户侧只需要使用统一的 App Key / Secret 调用。

统一鉴权

x-api-key + Authorization Bearer

可计费

成功调用写入账单和调用日志

订单隔离

采购支付只走客户授权账号

JSON 返回

统一 success / code / data 结构

请求入口

Base URL: https://open.buyeasysaas.com

Header: x-api-key / Authorization

接入说明

商品搜索、详情、图搜、店铺商品和链接解析按已开通产品直接调用
订单预览、下单和协议支付必须使用客户自己的 1688 授权账号
复杂参数支持 JSON 对象或 JSON 字符串，建议使用 POST + application/json
价格规则：未达批发门槛时仅在存在适用一件采购价时参考计价；达到实际门槛再使用 SKU 批发价或阶梯价，最终以官方预览为准

2026-09 兼容扩展：详情可选 price_contract=2026-09 返回独立价格结构；图搜支持可选 region、itemTitle。旧请求和价格字段保持不变，框选 UI 与复购合约交易尚未开放。

POST/api/open/1688/items/search

商品搜索

按关键词搜索 1688 货源商品。

商品 API 已开通

商品搜索、详情、图搜和店铺商品按已开通产品直接调用。

参数	类型	必填	说明	示例
keywords	string	是	搜索关键词	phone case
page	number	否	页码，默认 1	1
limit	number	否	每页数量，1-20	20
price_start	number	否	最低价	5
price_end	number	否	最高价	50
category_id	number	否	类目 ID	1042954
country_code	string	否	多语言编码	en

keywordsstring是

搜索关键词

phone case

pagenumber否

页码，默认 1

limitnumber否

每页数量，1-20

price_startnumber否

最低价

price_endnumber否

最高价

category_idnumber否

类目 ID

1042954

country_codestring否

多语言编码

请求示例

curl -X POST "https://api.your-domain.com/api/open/1688/items/search" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_APP_KEY" \
-H "Authorization: Bearer YOUR_APP_SECRET" \
-d '{ "keywords": "phone case", "page": 1, "limit": 20 }'

返回示例

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": { "items": [], "source": "1688" },
  "billing": {
    "charged": 0.027,
    "unitPrice": 0.027,
    "multiplier": 1,
    "product": "接口产品名称",
    "callId": 1024
  }
}

POST/api/open/1688/items/detail

商品详情

查询商品规格、零售价、批发阶梯价、库存、图片和供应信息。

商品 API 已开通

商品搜索、详情、图搜和店铺商品按已开通产品直接调用。

参数	类型	必填	说明	示例
goods_id	string	是	1688 商品 ID，也可传 offer_id	628747622184
offer_id	string	否	商品 offerId，和 goods_id 二选一	628747622184
price_contract	string	否	可选填 2026-09，增加 item.pricing，不改变旧字段；仅详情支持	2026-09
country_code	string	否	多语言编码	en

goods_idstring是

1688 商品 ID，也可传 offer_id

628747622184

offer_idstring否

商品 offerId，和 goods_id 二选一

628747622184

price_contractstring否

可选填 2026-09，增加 item.pricing，不改变旧字段；仅详情支持

2026-09

country_codestring否

多语言编码

请求示例

curl -X POST "https://api.your-domain.com/api/open/1688/items/detail" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_APP_KEY" \
-H "Authorization: Bearer YOUR_APP_SECRET" \
-d '{ "goods_id": "628747622184", "country_code": "en" }'

返回示例

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": {
  "item": {
    "offerId": "628747622184",
    "pricing_model": "retail_wholesale_v2",
    "retailPrice": "12.50",
    "retail_price": "12.50",
    "min_order_quantity": 1,
    "minOrderQuantity": 1,
    "productSaleInfo": {
      "retailPrice": "12.50",
      "priceRangeList": [{ "startQuantity": 2, "price": "8.80" }]
    },
    "productSkuInfos": [
      { "skuId": "1001", "specId": "abc", "retailPrice": "13.20", "price": "8.80" }
    ]
  }
},
  "billing": {
    "charged": 0.027,
    "unitPrice": 0.027,
    "multiplier": 1,
    "product": "接口产品名称",
    "callId": 1024
  }
}

- 向后兼容：原始 productSaleInfo、productSkuInfos、price、priceRangeList 和 sale_price 字段继续保留；新增别名不会要求既有客户立即修改。

- retailPrice / retail_price 是人民币一件采购参考价，未达批发门槛时可能用于多件计价；foreignCurrencyRetailPrice 不作为人民币成本或汇率使用。

- productSkuInfos[].price 与 priceRangeList[] 是当前跨境详情接口的批发参考价；实际门槛可能高于2件，不能直接用作1件价。

- 旧 MOQ 别名为兼容保留，不代表每个 SKU 都支持1件采购。新 pricing 分开返回零售、批发门槛；缺少一件价不能据此认定旧模型。

- 旧促销、分销字段继续保留，不作为新跨境价格契约的基础价；其他分销接口应按其独立协议解释。

- pricing 是参考信息，不包含已核实的混批/合约成交规则；null 表示未确认，不能按0元处理。

- 订单最终金额必须调用 /api/open/1688/orders/preview；1688会根据实际 quantity 自动选择零售价或批发价。

POST/api/open/1688/items/resolve-link

商品链接解析

解析 1688 商品长链接、分享短链或混合分享文案，返回标准商品 ID。

商品 API 已开通

商品搜索、详情、图搜和店铺商品按已开通产品直接调用。

参数	类型	必填	说明	示例
link	string	是	1688 商品链接、短链或完整分享文案	https://detail.1688.com/offer/628747622184.html

linkstring是

1688 商品链接、短链或完整分享文案

https://detail.1688.com/offer/628747622184.html

请求示例

curl -X POST "https://api.your-domain.com/api/open/1688/items/resolve-link" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_APP_KEY" \
-H "Authorization: Bearer YOUR_APP_SECRET" \
-d '{ "link": "https://detail.1688.com/offer/628747622184.html" }'

返回示例

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": { "platform": "1688", "platform_id": "628747622184", "goods_id": "1688_628747622184" },
  "billing": {
    "charged": 0.027,
    "unitPrice": 0.027,
    "multiplier": 1,
    "product": "接口产品名称",
    "callId": 1024
  }
}

- 兼容旧 SaaS platform_info 返回结构；短链逐跳校验 1688 官方域名，不跟随站外重定向。

POST/api/open/taobao/items/resolve-link

淘宝链接解析(多语言)

解析淘宝/天猫商品链接或淘口令，返回多语言商品详情。

商品 API 已开通

商品搜索、详情、图搜和店铺商品按已开通产品直接调用。

参数	类型	必填	说明	示例
link	string	是	完整复制内容、标准商品长链接、e.tb.cn/m.tb.cn/tb.cn 短链或￥...￥淘口令	https://e.tb.cn/h/example?tk=AbCdEf12345
country_code	string	否	返回语言：en/ja/vi/ru/ko/th/km，默认 en	en

linkstring是

完整复制内容、标准商品长链接、e.tb.cn/m.tb.cn/tb.cn 短链或￥...￥淘口令

https://e.tb.cn/h/example?tk=AbCdEf12345

country_codestring否

返回语言：en/ja/vi/ru/ko/th/km，默认 en

请求示例

curl -X POST "https://open.buyeasysaas.com/api/open/taobao/items/resolve-link" -H "Content-Type: application/json" \
-H "x-api-key: YOUR_APP_KEY" \
-H "Authorization: Bearer YOUR_APP_SECRET" -d '{"link": "https://item.taobao.com/item.htm?id=1030880477394", "country_code": "en"}'

返回示例

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": { "item": { "title": "Silk Piao Premium Quality Pull-Out Facial Tissues..." }, "resolved": { "platform": "taobao", "platform_id": "1030880477394", "item_url": "https://item.taobao.com/item.htm?id=1030880477394" } },
  "billing": {
    "charged": 0.027,
    "unitPrice": 0.027,
    "multiplier": 1,
    "product": "接口产品名称",
    "callId": 1024
  }
}

- 链接解析会调用同一商品详情接口并返回多语言结果；短链 tk 自动作为 tao_password，标准商品 URL 作为 item_url。店铺页和搜索页不属于商品定位器。

POST/api/open/1688/items/related

关联推荐

基于商品 ID 获取相似或相关货源推荐。

商品 API 已开通

商品搜索、详情、图搜和店铺商品按已开通产品直接调用。

参数	类型	必填	说明	示例
goods_id	string	是	1688 商品 ID	628747622184
page	number	否	页码	1
limit	number	否	每页数量，1-10	10

goods_idstring是

1688 商品 ID

628747622184

pagenumber否

页码

limitnumber否

每页数量，1-10

请求示例

curl -X POST "https://api.your-domain.com/api/open/1688/items/related" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_APP_KEY" \
-H "Authorization: Bearer YOUR_APP_SECRET" \
-d '{ "goods_id": "628747622184", "limit": 10 }'

返回示例

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": { "items": [] },
  "billing": {
    "charged": 0.027,
    "unitPrice": 0.027,
    "multiplier": 1,
    "product": "接口产品名称",
    "callId": 1024
  }
}