如何使用1688官方API进行订单同步？

一、前置准备（必须完成）

1. 开放平台基础配置

注册 / 登录：1688 开放平台，完成企业实名认证（个人账号无订单接口权限）。

创建应用：在「应用管理」创建应用，获取app_key（应用 ID）、app_secret（应用密钥）。

申请权限：在「权限管理」申请以下核心订单接口权限（免费，审核 1-2 个工作日）：

接口名称	权限说明	核心用途
alibaba.order.get	订单详情查询	拉取 1688 采购单详情
alibaba.order.create	分销订单创建	从自有平台同步订单至 1688 下单
alibaba.logistics.trace	物流轨迹查询	同步供应商发货物流信息
alibaba.trade.receive	订单确认收货	自动化完成订单履约闭环

2. 授权与令牌获取

订单接口需用户授权（即绑定你的 1688 采购账号），通过 OAuth2.0 获取access_token（有效期 24 小时，需定时刷新）：

引导用户访问授权链接：

plaintext

https://open.1688.com/oauth/authorize?client_id=你的app_key&response_type=code&redirect_uri=你的回调地址&state=随机字符串

用户授权后，回调地址会返回code，用code换取access_token：

bash

运行

POST https://open.1688.com/openapi/param2/1/system.oauth2/getToken
参数：
client_id=你的app_key&client_secret=你的app_secret&grant_type=authorization_code&code=授权码&redirect_uri=回调地址

保存access_token和refresh_token（用于过期后自动刷新）。

二、核心流程：订单同步全步骤（API 调用）

步骤 1：自有平台订单数据整理（待同步数据）

先将你的电商平台（淘宝 / 抖音 / 自有商城）订单整理为 1688 API 要求的格式，核心字段示例：

json

{
  "buyer_nick": "采购账号昵称",
  "receiver_name": "张三",
  "receiver_mobile": "138xxxx1234",
  "receiver_address": "浙江省杭州市滨江区XX街道XX小区1栋1单元101",
  "products": [
    {
      "product_id": "1688商品ID",  // 需提前绑定1688商品
      "sku_id": "1688商品规格ID",
      "quantity": 2,  // 采购数量
      "price": 9.9    // 商品单价（需与1688供应商报价一致）
    }
  ],
  "payment_type": "online",  // 支付方式：online/ offline
  "remark": "加急发货"       // 订单备注
}

步骤 2：调用alibaba.order.create创建 1688 采购单（核心）

这是「订单同步」的核心接口，将自有平台订单转为 1688 官方采购单。

1. 接口基础信息

请求地址：https://gw.open.1688.com/openapi/param2/1/alibaba.order/create

请求方式：POST

数据格式：JSON

频率限制：单应用 QPS≤5，日调用≤1000 次

2. Python 调用示例（含签名 + 验签）

python

运行

import requests
import hashlib
import time
import json

# 配置信息（替换为你的实际值）
APP_KEY = "你的app_key"
APP_SECRET = "你的app_secret"
ACCESS_TOKEN = "你的access_token"
API_URL = "https://gw.open.1688.com/openapi/param2/1/alibaba.order/create"

def generate_1688_sign(params, app_secret):
    """生成1688 API签名（MD5）"""
    # 按参数名ASCII升序排序
    sorted_params = sorted(params.items())
    # 拼接参数字符串（key+value）
    param_str = ''.join([f"{k}{v}" for k, v in sorted_params])
    # 首尾拼接app_secret并MD5加密
    sign_str = app_secret + param_str + app_secret
    return hashlib.md5(sign_str.encode()).hexdigest().upper()

def create_1688_order(order_data):
    """创建1688采购订单"""
    # 1. 构造公共参数
    public_params = {
        "app_key": APP_KEY,
        "timestamp": str(int(time.time() * 1000)),
        "format": "json",
        "v": "2.0",
        "sign_method": "md5",
        "access_token": ACCESS_TOKEN,
        "method": "alibaba.order.create"  # 接口方法名
    }
    
    # 2. 构造业务参数（需转为JSON字符串）
    biz_params = {
        "order_param": json.dumps(order_data, ensure_ascii=False)
    }
    
    # 3. 合并参数并生成签名
    all_params = {**public_params, **biz_params}
    all_params["sign"] = generate_1688_sign(all_params, APP_SECRET)
    
    # 4. 发送POST请求
    try:
        response = requests.post(
            API_URL,
            data=all_params,
            headers={"Content-Type": "application/x-www-form-urlencoded"},
            timeout=30
        )
        response.raise_for_status()
        result = response.json()
        return result
    except Exception as e:
        print(f"创建订单失败：{str(e)}")
        return None

# 测试调用（替换为你的订单数据）
if __name__ == "__main__":
    # 待同步的订单数据
    test_order = {
        "buyer_nick": "你的1688账号昵称",
        "receiver_name": "张三",
        "receiver_mobile": "13800001234",
        "receiver_address": "浙江省杭州市滨江区网商路699号",
        "products": [
            {
                "product_id": "1234567890",  # 替换为真实1688商品ID
                "sku_id": "1122334455",     # 替换为真实规格ID
                "quantity": 2,
                "price": 19.9
            }
        ],
        "payment_type": "online",
        "remark": "测试订单同步"
    }
    
    # 创建订单
    order_result = create_1688_order(test_order)
    if order_result:
        print("订单创建结果：", json.dumps(order_result, indent=2, ensure_ascii=False))
        # 成功后保存1688订单号，用于后续查询/履约
        if "result" in order_result and "order_id" in order_result["result"]:
            print(f"同步成功，1688订单号：{order_result['result']['order_id']}")

步骤 3：订单状态与物流同步

拉取订单状态：调用alibaba.order.get，传入order_id获取订单支付 / 发货 / 收货状态：

python

运行

# 简化示例（核心参数）
def get_order_status(order_id):
    params = {
        "app_key": APP_KEY,
        "timestamp": str(int(time.time() * 1000)),
        "access_token": ACCESS_TOKEN,
        "method": "alibaba.order.get",
        "order_id": order_id,
        # 其他公共参数+签名（同创建订单逻辑）
    }
    # 发送请求并解析状态（paid/ shipped/ received）

同步物流轨迹：供应商发货后，调用alibaba.logistics.trace获取物流单号和轨迹，回传至自有平台：

python

运行

def get_logistics_trace(order_id):
    params = {
        "app_key": APP_KEY,
        "timestamp": str(int(time.time() * 1000)),
        "access_token": ACCESS_TOKEN,
        "method": "alibaba.logistics.trace",
        "order_id": order_id,
        # 签名等参数
    }
    # 解析返回的物流轨迹（快递公司、单号、节点信息）

步骤 4：订单履约闭环（确认收货 / 售后）

买家确认收货后，调用alibaba.trade.receive完成订单闭环；

若有售后需求，调用alibaba.order.refund.create创建退款单，同步售后状态。

三、关键避坑点（新手必看）

签名错误：

业务参数需转为 JSON 字符串，且参数排序必须按 ASCII 升序；

时间戳为 13 位毫秒级，避免请求过期。

权限问题：

订单接口仅对企业认证账号开放，个人账号调用会返回 403；

需确保access_token未过期（建议每 23 小时刷新一次）。

数据一致性：

商品 ID / 规格 ID 必须与 1688 供应商商品一致，否则创建订单失败；

单价需与供应商报价匹配，避免价格异常导致订单被拦截。

限流处理：

批量同步订单时，需控制 QPS（≤5 次 / 秒），建议分批次调用，失败后指数退避重试。

四、替代方案（无代码 / 低代码）

若你无开发能力，可使用 1688 官方合作的 ERP 工具（无需调用 API）：

工具推荐：店小秘、通途、牵牛分销助手；

操作流程：

绑定 1688 账号和自有电商平台（淘宝 / 抖音等）；

配置商品关联规则（自有商品→1688 商品）；

开启「订单自动同步」，系统自动创建 1688 采购单并同步物流。

总结

1688 订单同步的核心是通过alibaba.order.create接口将自有订单转为 1688 采购单，需先完成开放平台认证、权限申请和 OAuth 授权。

关键步骤：整理订单数据→创建采购单→同步订单状态 / 物流→完成履约闭环，核心要保证签名正确、数据一致、遵守限流规则。

无开发能力可选择官方合作 ERP 工具，低成本快速落地订单同步。

审核编辑 黄宇