1688寻源通是1688开放平台为跨境ERP、代采商和SaaS服务商提供的官方供应链数据解决方案，通过API接口可将1688的货盘、订单、物流等信息接入自有系统，实现程序化寻源、自动化比价和一键代采。
以下是完整的对接流程指南。
---
## 一、接入前提（资质要求）
寻源通API面向**企业开发者**开放，个人账号无法申请核心接口。具体资质要求如下：
| 要求项 | 说明 |
|---|---|
| **主体资质** | 企业或个体工商户，需提供营业执照、法人身份证、企业对公账户 |
| **业务方向** | 跨境电商、跨境ERP、独立站、跨境供应链服务相关 |
| **考核门槛（2026新规）** | 月成交额 ≥ 12万元（通过寻源通API产生的确认订单）；调用效率 ≥ 0.5元/次（总成交额÷总调用次数）；不达标会被限流或清退 |
| **海外主体** | 1688开放平台不接受海外公司直接入驻，必须使用国内企业营业执照注册 |
> 若GMV暂时达不到门槛，可考虑接入第三方官方合作渠道。
## 二、完整接入流程
### 第1步：注册企业开发者账号
访问 **open.1688.com**，使用企业1688账号登录，注册为企业开发者，提交营业执照等材料完成实名认证（审核约1-2个工作日）。
### 第2步：创建应用并申请寻源通权限
在开放平台控制台完成以下操作：
1. **创建应用**：进入「应用管理」→「创建应用」，应用类型选择「企业应用 / 跨境电商类」，应用场景必须填写跨境相关内容（如跨境选品、跨境供应链、跨境订单同步）。
2. **申请API权限**：进入「API市场」→「跨境寻源通」，勾选所需接口。常用接口包括：
- `crossBorder.product.search` — 跨境商品搜索
- `crossBorder.product.get` — 商品详情
- `crossBorder.supplier.get` — 供应商资质
- `crossBorder.order.create` — 跨境订单创建
- `crossBorder.order` — 订单/物流查询
3. **提交审核**：附上使用场景说明，审核周期通常为1-3个工作日。
### 第3步：获取密钥
审核通过后，在应用详情页获取：
- **appKey**：应用唯一标识
- **appSecret**：签名密钥，需严格保密
### 第4步：OAuth 2.0授权获取AccessToken
寻源通采用OAuth 2.0授权机制，Token有效期通常为7天，需实现自动刷新机制。
**① 引导用户授权**（前端跳转）：
```
https://open.1688.com/auth/authorize.htm
?response_type=code
&client_id={appKey}
&redirect_uri={回调地址}
&state=自定义
&scope=crossBorder
```
**② 用授权码换取AccessToken**（后端调用）：
```
POST https://open.1688.com/auth/token.htm
参数：
grant_type=authorization_code
client_id={appKey}
client_secret={appSecret}
code=上一步返回的code
redirect_uri={回调地址}
```
返回 `access_token`、`refresh_token` 及有效期，后续需用 `refresh_token` 定期刷新Token，避免过期失效。
### 第5步：接口签名规则
所有接口调用均需签名，算法为 **MD5**，步骤如下：
1. 将除 `sign` 外的所有请求参数按参数名ASCII码升序排列
2. 拼接为字符串：`appSecret + key1value1key2value2... + appSecret`
3. 对拼接串进行MD5加密，结果转为**大写**
**Python签名示例**：
```python
import hashlib
def generate_sign(params, app_secret):
sorted_params = sorted((k, v) for k, v in params.items() if k != 'sign')
sign_str = app_secret + ''.join(f"{k}{v}" for k, v in sorted_params) + app_secret
return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
```
### 第6步：接口调用示例（跨境商品搜索）
请求地址格式为：
```
https://gw.open.1688.com/openapi/param2/1/[接口命名空间]/[接口名]
```
以 `crossBorder.product.search` 为例：
```python
import requests
import time
APP_KEY = "你的AppKey"
APP_SECRET = "你的AppSecret"
ACCESS_TOKEN = "你的AccessToken"
url = "https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.crossborder.product.search"
biz_params = {
"keywords": "wireless earbuds",
"page_no": 1,
"page_size": 20,
"crossBorderType": "direct", # 跨境直发
"certification": "CE,FDA", # 合规认证筛选
"targetMarket": "EU" # 目标市场
}
public_params = {
"app_key": APP_KEY,
"access_token": ACCESS_TOKEN,
"method": "alibaba.crossborder.product.search",
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()),
"format": "json",
"v": "2.0"
}
all_params = {**public_params, **biz_params}
all_params["sign"] = generate_sign(all_params, APP_SECRET)
resp = requests.post(url, data=all_params)
print(resp.json())
```
### 第7步：测试 → 上线 → 运维
- 先在沙箱环境验证接口调用和签名逻辑
- 确认无误后切换正式环境
- 上线后监控Token有效性、调用频率和错误率，及时处理异常
## 三、核心接口清单
| 接口类别 | 接口名 | 功能说明 |
|---|---|---|
| **商品** | `crossBorder.product.search` | 按关键词、类目、价格等搜索跨境商品 |
| **商品** | `crossBorder.product.get` / `alibaba.product.get` | 获取商品详情（标题、价格、SKU、库存、供应商等） |
| **供应商** | `crossBorder.supplier.get` | 获取供应商资质、经营年限、诚信通等级 |
| **订单** | `crossBorder.order.create` | 创建跨境采购订单 |
| **订单** | `crossBorder.order` | 查询订单详情、物流轨迹 |
| **库存** | `alibaba.icbu.inventory.update` | 实时同步供应商商品库存 |
商品详情接口支持指定返回字段（如 `subject`、`priceRanges`、`skuInfo`、`saleInfo`、`shippingInfo` 等），可按需裁剪响应数据量。
## 四、常见问题与错误码
| 错误码 | 含义 | 处理建议 |
|---|---|---|
| `400` | 参数错误 | 检查必填字段是否缺失 |
| `403` | 权限不足 | 重新申请对应接口权限 |
| `429` | 调用频率超限 | 降低请求频率，增加重试间隔 |
| `500` | 服务器错误 | 稍后重试 |
| `4013` | 调用次数超限 | 检查套餐配额，申请扩容 |
**其他常见问题**：
- **Token过期**：AccessToken有效期约7天，需用refresh_token自动刷新。
- **海外公司无法入驻**：1688开放平台仅接受国内企业营业执照注册，海外主体需通过第三方合作渠道接入。
- **签名失败**：注意签名需转大写，参数排序需按ASCII码升序，空值需过滤。
## 五、费用说明
寻源通API本身**免费开通**，但需满足平台的GMV和调用效率考核指标。若考核不达标，可能出现限流或清退，建议定期关注调用数据，确保持续合规。
