1688「跨境寻源通」（Cross-border Sourcing / Supply API）是1688为跨境电商卖家（亚马逊/Shopee/TikTok等）提供的专属接口集，相比普通开放平台API增加了跨境属性（HS编码、申报品名、箱规、英文标题）、代发物流模板及账期支付支持。下面给你完整的接入流程和可直接运行的Python封装。

一、 跨境寻源通与普通1688 API的区别

⚠️ 前提：应用创建时选择「跨境寻源/ISV应用」并在开放平台签署《跨境数据使用协议》，否则调不通。

二、 费用模型（2026版）

三、 Python封装：跨境商品查询 + 订单代发

# ali1688_supply_client.py
import hashlib
import time
import requests
import urllib.parse
from typing import Dict, List, Optional
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
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, params=api_params, timeout=15)
        resp.raise_for_status()
        data = resp.json()

        if "error_response" in data:
            err = data["error_response"]
            raise Exception(f"1688 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_key="YOUR_APP_KEY",
        app_secret="YOUR_APP_SECRET",
        access_token="YOUR_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_id="698812345678",
        #     sku_id="1234567890",
        #     quantity=5,
        #     consignee={...}
        # )
        # print("代发订单ID:", order_id)

    except Exception as e:
        print("❌", e)

四、 关键避坑清单

1. 应用类型必须选对：普通「自用型应用」调跨境接口返回无权访问，需重建应用选「跨境寻源/ISV」。

2. AccessToken必需：跨境接口涉及买家身份（账期/地址），session参数不可省略，用OAuth2授权码换token。

3. HS Code字段可能为空：部分供应商未填跨境信息，hsCode返回null，ERP需做默认值或人工补全。

4. 账期支付开通：payType=CREDIT需先在1688卖家后台开通「信任付/账期」，否则下单报错。

5. 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内部编码映射表设计。