1. 简介

本文档详细描述了通过Q-Link平台对接第三方物流商的技术规范和接口说明。如果您需要使用Q-Link已对接的物流商服务，本文档将帮助您:

• 了解物流服务接入的基本要求和技术规范
• 快速集成物流服务的各项功能
• 掌握接口调用的详细说明和示例
• 高效对接第三方物流商的服务

通过阅读本文档，开发者可以轻松实现与Q-Link平台的系统对接，快速启用物流服务功能。

2. 环境要求及基础约定

2.1. 快速开始

2.1.1. 获取授权信息

在开始对接前，您需要获取以下授权信息：

• appKey：客户唯一标识，由平台分配
• appSecret：接口加密密钥，由平台分配，请妥善保管

2.1.2. 环境说明

Q-Link平台提供两个环境：

• 测试环境: https://open-test1.800best.com
  • 用于开发调试，数据隔离
  • 支持完整功能测试
• 生产环境: http://open-prod.800best.com
  • 正式环境，请求生产级别使用
  • 确保测试通过后再接入

2.1.3. 接口规范

本文档接口遵循以下规范：

• 请求方式: POST
• Content-Type: application/json
• 字符编码: UTF-8
• 数据格式: JSON

2.2. 公共参数说明

2.2.1. 请求参数

每个接口调用都需要包含以下基础参数：

2.2.2. Header参数

某些高级功能需要在请求头中包含以下参数：

2.2.3. authInfo授权信息

用于传递特定物流商的授权参数，JSON格式示例：

{
  "authInfo": [
    {
      "authInfoKey": "LOGISTICS_KEY",
      "value": "BG2447"
    },
    {
      "authInfoKey": "LOGISTICS_SECRET",
      "value": "f1dafc7b7c934d21327d990b0ea56cfcf4814ef699345a37010c07e02d5219a9"
    }
  ]
}

注意事项：

• authInfo中的具体参数由各物流商定义，请参考具体物流商的接入文档
• 敏感信息（如密钥）
• 确保JSON格式正确，避免格式错误导致请求失败

2.3. 响应格式说明

2.3.1. 公共响应结构

所有接口返回统一的JSON格式：

响应示例：

{
    "success": true,
    "message": null
}

2.3.2. 错误码说明

常见错误码及处理方法：

2.4. 安全签名机制

2.4.1. 签名算法

为保证接口调用安全性，所有请求都需要进行签名验证：

// 1. 组装待签名字符串
String toSign = "";
if (hasContent) {
    toSign = String.format("{\"appKey\":\"%s\",\"content\":\"%s\"}", appKey, content);
} else {
    toSign = String.format("{\"appKey\":\"%s\"}", appKey);
}

// 2. 拼接appSecret
String signStr = toSign + appSecret;

// 3. SHA1加密
String sign = DigestUtils.sha1Hex(signStr);

2.4.2. 签名示例

// 请求参数
appKey = "TEST_KEY_001";
content = "{\"orderNo\":\"123\"}";
appSecret = "test_secret";

// 待签名字符串
String toSign = "{\"appKey\":\"TEST_KEY_001\",\"content\":\"{\"orderNo\":\"123\"}\"}test_secret";

// 最终签名
String sign = "a1b2c3d4e5f6g7h8i9j0...";

安全建议：

• 确保appSecret不被泄露
• 签名数据中的特殊字符需要进行转义
• 建议对敏感业务数据进行加密

3. 物流授权

方法名:

• auth

接口参数:

返回信息:

请求示例:

{
"appKey": "3215435",
"method": "getTrackingInfo",
"content": "{\"logisticsKey\":\"id001\",\"logisticsKey\":\"testKey\",\"appKey\":\"dfa32423423",\"appSecret\":\"dfs2323\"}",
"sign": "11fbd649164860b5571cb60dfc99baccb375f392"
}

返回示例:

{
    "success": "true",
    "message": ""
}

4. 渠道列表

方法名:

• channels

接口参数:

返回信息:

请求示例:

{
    "appKey": "3215435",
    "content": "",
    "method": "channels",
    "sign": "11fbd649164860b5571cb60dfc99baccb375f392"
}

返回示例:

{
    "success": "true",
    "message": "",
    "channelList": [
        {
            "channelCode": "FedexGround",
            "channelName": "FedEx Ground",
            "carrierName": "FEDEX",
            "transportType": ""
        }
    ]
}

5. 面单取号

方法名:

• createOrder

接口参数:

返回信息:

请求示例

{
    "appKey": "1",
    "method": "createOrder",
    "content": {
        "senderAddress": {
            "name": "FSR",
            "company": null,
            "address1": "17, Jalan Bola Sepak Empat 13/11d, Seksyen 13",
            "address2": null,
            "fullAddress": "17, Jalan Bola Sepak Empat 13/11d, Seksyen 13",
            "phone1": "626-328-4549",
            "email": null,
            "country": "MY",
            "province": "Kuala Lumpur",
            "city": "Kuala Lumpur",
            "town": null,
            "postalCode": "51200"
        },
        "packageHigh": 8,
        "totalWeight": 0.44,
        "packageLength": 18,
        "packageWide": 12,
        "codPayAmount": null,
        "itemList": [
            {
                "sku": "X0045DKY3H",
                "skuName": "握力器五件套-深蓝-骰子版",
                "cnCustomsName": null,
                "enCustomsName": null,
                "customsCode": null,
                "price": 0,
                "currency": "USD",
                "quantity": 1,
                "weight": 0.44,
                "skuWeight": 0.44,
                "color": null,
                "weightUnit": "KG",
                "length": "18.0",
                "width": "12.0",
                "height": "8.0",
                "lengthUnit": "cm",
                "skuPrice": 18.99
            }
        ],
        "recipientAddress": {
            "name": "Jonathan Padilla",
            "company": null,
            "address1": "17, Jalan Bola Sepak Empat 13/11d, Seksyen 13",
            "address2": "",
            "fullAddress": "17, Jalan Bola Sepak Empat 13/11d, Seksyen 13",
            "phone1": "(+1)9797302829",
            "phone2": "",
            "email": "",
            "country": "MY",
            "province": "Kuala Lumpur",
            "city": "Kuala Lumpur",
            "town": null,
            "postalCode": "51200"
        },
        "customerNumber": "S250721448561",
        "remarks": null,
        "channelCode": "flashexpressmy",
        "logisticsKey": "CA1305"
    },
    "sign": "c77f2ad0b06d8e2b04af9aec9b8b6f7740d07249"
}

返回示例

{
    "code": null,
    "errorMsg": null,
    "result": {
        "trackingNumber": "M0601UUP8AM"
    },
    "success": true,
    "notSuccess": null
}

6. 面单取消

方法名:

• cancelOrder

接口参数:

请求示例:

{
    "appKey": "1",
    "method": "createOrder",
    "content": {"logisticsKey":"CA1305","customerNumber":"S250721448561","trackingNumber":"M0601UUF3AM"},
    "sign": "c77f2ad0b06d8e2b04af9aec9b8b6f7740d07249"
}

返回示例:

{
    "code": null,
    "errorMsg": null,
    "result": null,
    "success": true,
    "notSuccess": null
}

7. 面单取面

方法名:

• getLabelData

接口参数:

返回信息:

请求示例:

{
    "appKey": "1",
    "method": "createOrder",
    "content": {"logisticsKey":"CA1305","customerNumber":"S250721448561","trackingNumber":"M0601UUF3AM"},
    "sign": "c77f2ad0b06d8e2b04af9aec9b8b6f7740d07249"
}

返回示例:

8. 获取物流轨迹

方法名:

• getTrackingInfo

接口参数:

返回信息:

TrackingEvent

请求示例:

{
    "appKey": "1",
    "method": "createOrder",
    "content": {"logisticsKey":"CA1305","customerNumber":"S250721448561","trackingNumber":"M0601UUF3AM"},
    "sign": "c77f2ad0b06d8e2b04af9aec9b8b6f7740d07249"
}

返回示例:

{
    "state": null,
    "code": null,
    "errorMsg": null,
    "args": null,
    "props": null,
    "result": {
        "orderNumber": "S2507289247541",
        "carrierName": "flashexpressmy",
        "trackingNumber": "M150526Y7PVAG0",
        "status": "CREATED",
        "stageList": [
            {
                "trackingEvents": [
                    {
                        "eventDate": "1753711339000",
                        "eventPlace": "Malaysia",
                        "eventDesc": "order created successfully"
                    }
                ]
            }
        ]
    },
    "success": true,
    "notSuccess": null
}

9. 订阅物流轨迹

方法名:

• subscribe

接口参数:

返回信息:

请求示例:

{
    "success": "true",
    "message": "",
    "data": [
        {
            "trackingNumber": "DS35841212312",
            "orderNumber": "orderNumber",
            "errorMessage": "运单不存在"
        }
    ]
}

10. WebHook

10.1. 推送物流轨迹

/logistics/callback

方法名:

• pushLogistics

接口参数:

trackingEvents

请求示例:

{
    "carrierName": "百世跨境",
    "customerNumber": "A250724147161",
    "stageList": [
        {
        "number": 3,
        "status": "待发运",
        "trackingEvents": [
            {
                "eventDate": "您的货物已在跨境深圳(测试)入库。",
                "eventDesc": "2025-06-26 11:19:57",
                "eventPlace": "国内"
                },
                {
                "eventDate": "您的运单已提交，等待货物送达百世仓库。",
                "eventDesc": "2025-06-26 11:19:47",
                "eventPlace": "-"
                }
            ]
        }
    ],
    "status": "SHIPPED",
    "trackingNumber": "BSO9250626001016"
}

11. 支持物流信息

11.1. 尾程物流

11.2. 头程物流