1688「跨境寻源通」Cross-border Sourcing / Supply API是1688为跨境电商卖家亚马逊/Shopee/TikTok等提供的专属接口集相比普通开放平台API增加了跨境属性HS编码、申报品名、箱规、英文标题、代发物流模板及账期支付支持。下面给你完整的接入流程和可直接运行的Python封装。一、 跨境寻源通与普通1688 API的区别维度普通开放平台API跨境寻源通(Supply) API适用对象国内B2B采购跨境电商卖家需额外认证商品字段中文标题/国内规格英文标题、HS Code、申报价值、箱规、原产国支付方式担保交易支持账期(Credit)、跨境代付物流普通快递跨境小包/海外仓发货模板费用基础免费基础查询免费增值功能需买「跨境资源包」权限申请普通应用需「跨境寻源」标签应用企业实名⚠️前提应用创建时选择「跨境寻源/ISV应用」并在开放平台签署《跨境数据使用协议》否则调不通。二、 费用模型2026版项目收费说明商品查询/详情含跨境字段✅免费supply.product.get等受QPS限制(默认10)代发订单创建/同步✅ 免费同普通订单API实时库存/阶梯价(跨境增强)⚠️ 资源包同普通API进阶包¥980~2980/年档位数据推送/选品洞察⚠️ 增值包按档位收费大卖家按需超量按量≈¥0.005/次极少触发结论中小跨境卖家做商品同步代发订单基础免费额度够用买资源包主要是为了提QPS和实时库存。三、 Python封装跨境商品查询 订单代发跨境寻源通的签名、网关与普通API基本一致区别在method命名空间和部分业务参数。# ali1688_supply_client.py import hashlib import time import requests import urllib.parse from typing import Dict, List, Optional # 封装好API供应商demo urlhttps://console.open.onebound.cn/console/?iLex class Ali1688SupplyClient: 1688 跨境寻源通(Supply) API Client 网关与签名规则和标准1688 Open API一致仅 method/业务参数不同 GATEWAY https://gw.open.1688.com/openapi/param2/2 def __init__(self, app_key: str, app_secret: str, access_token: str): self.app_key app_key self.app_secret app_secret self.access_token access_token # 跨境应用必须传登录态(session key) # ──────────────────────────────────────── # 标准1688 MD5签名 # ──────────────────────────────────────── def _sign(self, params: Dict) - str: filtered sorted((k, v) for k, v in params.items() if v is not None) qs .join(f{k}{v} for k, v in filtered) raw f{self.app_secret}{qs}{self.app_secret} return hashlib.md5(raw.encode(utf-8)).hexdigest().upper() def _call(self, method: str, biz_params: Dict) - Dict: api_params { method: method, app_key: self.app_key, session: self.access_token, timestamp: str(int(time.time() * 1000)), format: json, v: 2.0, sign_method: md5, } api_params[param2] urllib.parse.quote_plus( str(biz_params).replace(, ) ) api_params[sign] self._sign(api_params) resp requests.get(self.GATEWAY, paramsapi_params, timeout15) resp.raise_for_status() data resp.json() if error_response in data: err data[error_response] raise Exception(f1688 Supply Error [{err.get(code)}]: {err.get(msg)}) # 不同method返回key略有不同统一提取 result_key list(data.keys() - {error_response})[0] return data[result_key] # ──────────────────────────────────────── # 1. 查询跨境商品详情含HS Code/英文标题 # ──────────────────────────────────────── def get_cross_border_product(self, offer_id: str) - Dict: 对应 method: alibaba.supply.product.get 返回含 crossBorderInfo { hsCode, enTitle, declareUnit, originCountry ... } biz {offerId: offer_id} return self._call(alibaba.supply.product.get, biz) # ──────────────────────────────────────── # 2. 创建跨境代发订单简化示例 # ──────────────────────────────────────── def create_cross_order(self, offer_id: str, sku_id: str, quantity: int, consignee: Dict) - str: consignee 示例: { fullName: Zhang San, mobile: 8613800138000, country: US, province: California, city: Los Angeles, address: 123 Main St, zip: 90001 } biz { offerId: offer_id, quantity: quantity, skuId: sku_id, consignee: consignee, payType: CREDIT, # 账期支付(需开通) 或 GUARANTEE crossBorder: true # 标记为跨境订单 } res self._call(alibaba.supply.trade.create, biz) order_id res.get(orderId) return order_id # ──────────────────────────────────────── # 3. 查询代发订单物流同普通API可复用 # ──────────────────────────────────────── def get_order_logistics(self, order_id: str) - List[Dict]: biz {orderId: order_id} res self._call(alibaba.logistics.trade.ship, biz) return res.get(logisticsOrders, []) or [] # # 使用示例 # if __name__ __main__: client Ali1688SupplyClient( app_keyYOUR_APP_KEY, app_secretYOUR_APP_SECRET, access_tokenYOUR_ACCESS_TOKEN # 跨境应用需OAuth2获取 ) try: # ① 查跨境商品含HS编码 prod client.get_cross_border_product(698812345678) cross_info prod.get(crossBorderInfo, {}) print(英文标题:, cross_info.get(enTitle)) print(HS Code:, cross_info.get(hsCode)) print(申报单位:, cross_info.get(declareUnit)) # ② 创建代发订单示例 # order_id client.create_cross_order( # offer_id698812345678, # sku_id1234567890, # quantity5, # consignee{...} # ) # print(代发订单ID:, order_id) except Exception as e: print(❌, e)四、 关键避坑清单应用类型必须选对普通「自用型应用」调跨境接口返回无权访问需重建应用选「跨境寻源/ISV」。AccessToken必需跨境接口涉及买家身份账期/地址session参数不可省略用OAuth2授权码换token。HS Code字段可能为空部分供应商未填跨境信息hsCode返回nullERP需做默认值或人工补全。账期支付开通payTypeCREDIT需先在1688卖家后台开通「信任付/账期」否则下单报错。QPS限制免费应用默认≈10/s高频同步建议买资源包提至50~100/s并加重试退避。五、 对接链路面试叙述版跨境ERP/选品系统 │ OAuth2 AccessToken ▼ Supply API → alibaba.supply.product.get │ └─ offerId HS Code EN Title 箱规 ▼ 写入ERP商品主数据SKU映射 │ ▼ 买家下单后 create_cross_order → 1688代发 │ ▼ logistics.trade.ship 轮询 同步物流单号 → ERP出库单如需要我可以补充1688 OAuth2获取AccessToken完整代码或SKU与ERP内部编码映射表设计。
1688跨境寻源通(Supply) API接入与费用说明（附Python源码）
1688「跨境寻源通」Cross-border Sourcing / Supply API是1688为跨境电商卖家亚马逊/Shopee/TikTok等提供的专属接口集相比普通开放平台API增加了跨境属性HS编码、申报品名、箱规、英文标题、代发物流模板及账期支付支持。下面给你完整的接入流程和可直接运行的Python封装。一、 跨境寻源通与普通1688 API的区别维度普通开放平台API跨境寻源通(Supply) API适用对象国内B2B采购跨境电商卖家需额外认证商品字段中文标题/国内规格英文标题、HS Code、申报价值、箱规、原产国支付方式担保交易支持账期(Credit)、跨境代付物流普通快递跨境小包/海外仓发货模板费用基础免费基础查询免费增值功能需买「跨境资源包」权限申请普通应用需「跨境寻源」标签应用企业实名⚠️前提应用创建时选择「跨境寻源/ISV应用」并在开放平台签署《跨境数据使用协议》否则调不通。二、 费用模型2026版项目收费说明商品查询/详情含跨境字段✅免费supply.product.get等受QPS限制(默认10)代发订单创建/同步✅ 免费同普通订单API实时库存/阶梯价(跨境增强)⚠️ 资源包同普通API进阶包¥980~2980/年档位数据推送/选品洞察⚠️ 增值包按档位收费大卖家按需超量按量≈¥0.005/次极少触发结论中小跨境卖家做商品同步代发订单基础免费额度够用买资源包主要是为了提QPS和实时库存。三、 Python封装跨境商品查询 订单代发跨境寻源通的签名、网关与普通API基本一致区别在method命名空间和部分业务参数。# ali1688_supply_client.py import hashlib import time import requests import urllib.parse from typing import Dict, List, Optional # 封装好API供应商demo urlhttps://console.open.onebound.cn/console/?iLex class Ali1688SupplyClient: 1688 跨境寻源通(Supply) API Client 网关与签名规则和标准1688 Open API一致仅 method/业务参数不同 GATEWAY https://gw.open.1688.com/openapi/param2/2 def __init__(self, app_key: str, app_secret: str, access_token: str): self.app_key app_key self.app_secret app_secret self.access_token access_token # 跨境应用必须传登录态(session key) # ──────────────────────────────────────── # 标准1688 MD5签名 # ──────────────────────────────────────── def _sign(self, params: Dict) - str: filtered sorted((k, v) for k, v in params.items() if v is not None) qs .join(f{k}{v} for k, v in filtered) raw f{self.app_secret}{qs}{self.app_secret} return hashlib.md5(raw.encode(utf-8)).hexdigest().upper() def _call(self, method: str, biz_params: Dict) - Dict: api_params { method: method, app_key: self.app_key, session: self.access_token, timestamp: str(int(time.time() * 1000)), format: json, v: 2.0, sign_method: md5, } api_params[param2] urllib.parse.quote_plus( str(biz_params).replace(, ) ) api_params[sign] self._sign(api_params) resp requests.get(self.GATEWAY, paramsapi_params, timeout15) resp.raise_for_status() data resp.json() if error_response in data: err data[error_response] raise Exception(f1688 Supply Error [{err.get(code)}]: {err.get(msg)}) # 不同method返回key略有不同统一提取 result_key list(data.keys() - {error_response})[0] return data[result_key] # ──────────────────────────────────────── # 1. 查询跨境商品详情含HS Code/英文标题 # ──────────────────────────────────────── def get_cross_border_product(self, offer_id: str) - Dict: 对应 method: alibaba.supply.product.get 返回含 crossBorderInfo { hsCode, enTitle, declareUnit, originCountry ... } biz {offerId: offer_id} return self._call(alibaba.supply.product.get, biz) # ──────────────────────────────────────── # 2. 创建跨境代发订单简化示例 # ──────────────────────────────────────── def create_cross_order(self, offer_id: str, sku_id: str, quantity: int, consignee: Dict) - str: consignee 示例: { fullName: Zhang San, mobile: 8613800138000, country: US, province: California, city: Los Angeles, address: 123 Main St, zip: 90001 } biz { offerId: offer_id, quantity: quantity, skuId: sku_id, consignee: consignee, payType: CREDIT, # 账期支付(需开通) 或 GUARANTEE crossBorder: true # 标记为跨境订单 } res self._call(alibaba.supply.trade.create, biz) order_id res.get(orderId) return order_id # ──────────────────────────────────────── # 3. 查询代发订单物流同普通API可复用 # ──────────────────────────────────────── def get_order_logistics(self, order_id: str) - List[Dict]: biz {orderId: order_id} res self._call(alibaba.logistics.trade.ship, biz) return res.get(logisticsOrders, []) or [] # # 使用示例 # if __name__ __main__: client Ali1688SupplyClient( app_keyYOUR_APP_KEY, app_secretYOUR_APP_SECRET, access_tokenYOUR_ACCESS_TOKEN # 跨境应用需OAuth2获取 ) try: # ① 查跨境商品含HS编码 prod client.get_cross_border_product(698812345678) cross_info prod.get(crossBorderInfo, {}) print(英文标题:, cross_info.get(enTitle)) print(HS Code:, cross_info.get(hsCode)) print(申报单位:, cross_info.get(declareUnit)) # ② 创建代发订单示例 # order_id client.create_cross_order( # offer_id698812345678, # sku_id1234567890, # quantity5, # consignee{...} # ) # print(代发订单ID:, order_id) except Exception as e: print(❌, e)四、 关键避坑清单应用类型必须选对普通「自用型应用」调跨境接口返回无权访问需重建应用选「跨境寻源/ISV」。AccessToken必需跨境接口涉及买家身份账期/地址session参数不可省略用OAuth2授权码换token。HS Code字段可能为空部分供应商未填跨境信息hsCode返回nullERP需做默认值或人工补全。账期支付开通payTypeCREDIT需先在1688卖家后台开通「信任付/账期」否则下单报错。QPS限制免费应用默认≈10/s高频同步建议买资源包提至50~100/s并加重试退避。五、 对接链路面试叙述版跨境ERP/选品系统 │ OAuth2 AccessToken ▼ Supply API → alibaba.supply.product.get │ └─ offerId HS Code EN Title 箱规 ▼ 写入ERP商品主数据SKU映射 │ ▼ 买家下单后 create_cross_order → 1688代发 │ ▼ logistics.trade.ship 轮询 同步物流单号 → ERP出库单如需要我可以补充1688 OAuth2获取AccessToken完整代码或SKU与ERP内部编码映射表设计。
