BuyEasy OpenAPI 文档

1688 商品与采购 API

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

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

统一鉴权

x-api-key + Authorization Bearer

可计费

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

订单隔离

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

JSON 返回

统一 success / code / data 结构

请求入口

Base URL: https://你的域名

Header: x-api-key / Authorization

接入说明

商品查询可使用客户授权或平台备用能力
订单预览、下单和协议支付必须使用客户自己的 1688 授权账号
复杂参数支持 JSON 对象或 JSON 字符串，建议使用 POST + application/json

1688 商品详情仍以 goods_id 或 offer_id 作为标准入参，系统会自动去除 1688_ 前缀后转给上游。

POST/api/open/1688/items/search

商品搜索

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

可走平台备用能力

未授权也可调用商品类接口；如客户授权且额度可用，优先使用客户授权

参数	类型	必填	说明	示例
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.02,
    "product": "接口产品名称",
    "callId": 1024
  }
}

POST/api/open/1688/items/detail

商品详情

查询商品规格、价格、库存、图片和供应信息。

可走平台备用能力

未授权也可调用商品类接口；如客户授权且额度可用，优先使用客户授权

参数	类型	必填	说明	示例
goods_id	string	是	1688 商品 ID，也可传 offer_id	628747622184
offer_id	string	否	商品 offerId，和 goods_id 二选一	628747622184
country_code	string	否	多语言编码	en

goods_idstring是

1688 商品 ID，也可传 offer_id

628747622184

offer_idstring否

商品 offerId，和 goods_id 二选一

628747622184

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", "sku_list": [] } },
  "billing": {
    "charged": 0.02,
    "product": "接口产品名称",
    "callId": 1024
  }
}

POST/api/open/1688/items/related

关联推荐

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

可走平台备用能力

未授权也可调用商品类接口；如客户授权且额度可用，优先使用客户授权

参数	类型	必填	说明	示例
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.02,
    "product": "接口产品名称",
    "callId": 1024
  }
}