1. 接口说明

开放 API 供商户系统对接，实现在线下单、查询运单、取消运单、查看资金等能力。接口调用需先在用户中心「API 接口管理」页面创建令牌。

2. 通用说明

2.1 统一响应结构

2.2 枚举值

3. 渠道报价（下单前比价）

允许商户通过此接口获取运费报价。返回多个快递渠道的到手价，下单时选择其一即可。

请求参数

请求示例

cURLcurl -X POST "/api/order/quote" \
  -H "Authorization: Bearer ak_xxxx" \
  -d "biz_type=1&sender_name=张三&sender_mobile=13800138000&sender_province=广东省&sender_city=深圳市&sender_district=南山区&sender_address=高新南一道9号&receiver_name=李四&receiver_mobile=13912345678&receiver_province=浙江省&receiver_city=杭州市&receiver_district=西湖区&receiver_address=文三路478号&goods_name=服装&weight=2.5&length=30&width=20&height=15"

返回示例

response{
  "code": 0,
  "msg": "ok",
  "data": {
    "qtoken": "1a2b3c4d5e6f",
    "debug": false,
    "offers": [
      {
        "oid": "yida|1|SF-1",
        "company_code": "SF",
        "company_name": "顺丰速运",
        "logo": "/static/logo/sf.png",
        "intro": "时效快，服务好",
        "eta": "次日达",
        "total_price": 12.5
      }
    ]
  }
}

返回字段说明

4. 创建订单

允许商户通过此接口下单。下单即从会员余额扣款，扣款成功后向快递公司推送，余额不足会返回失败。

请求参数

请求示例

cURLcurl -X POST "/api/order/create" \
  -H "Authorization: Bearer ak_xxxx" \
  -d "biz_type=1&oid=yida|1|SF-1&sender_name=张三&sender_mobile=13800138000&sender_province=广东省&sender_city=深圳市&sender_district=南山区&sender_address=高新南一道9号&receiver_name=李四&receiver_mobile=13912345678&receiver_province=浙江省&receiver_city=杭州市&receiver_district=西湖区&receiver_address=文三路478号&goods_name=服装&weight=2.5&length=30&width=20&height=15&remark=轻放&appoint_time=2026-11-02 14:00"

返回示例

response{
  "code": 0,
  "msg": "下单成功",
  "data": {
    "id": 10086,
    "order_no": "KD20261102000123",
    "waybill_no": "",
    "company_name": "顺丰速运",
    "total_price": 12.5,
    "status": 0
  }
}

返回字段说明

5. 订单列表

分页查询当前令牌所属会员的订单列表，支持按业务类型、状态、关键词过滤。

请求参数

请求示例

cURLcurl "/api/order/list?page=1&page_size=15&biz_type=1&status=4&keyword=KD" \
  -H "Authorization: Bearer ak_xxxx"

返回示例

response{
  "code": 0,
  "msg": "ok",
  "data": {
    "total": 23,
    "page": 1,
    "pageSize": 15,
    "list": [
      {
        "id": 10086,
        "order_no": "KD20261102000123",
        "waybill_no": "SF1234567890123",
        "biz_type": 1,
        "company_code": "SF",
        "company_name": "顺丰速运",
        "total_price": 12.5,
        "pay_status": 1,
        "status": 3,
        "status_text": "运输中",
        "sender_city": "深圳市",
        "receiver_city": "杭州市",
        "create_time": "2026-11-02 09:30:00"
      }
    ]
  }
}

返回字段说明

6. 订单详情

获取单个订单的完整信息，包含寄收件人、物品、费用、状态及时间线。

请求参数

请求示例

cURLcurl "/api/order/detail?id=10086" \
  -H "Authorization: Bearer ak_xxxx"

主要返回字段

7. 物流轨迹

按订单 ID 或运单号查询物流轨迹，返回最新状态与轨迹列表。

请求参数

请求示例

cURLcurl "/api/order/track?waybill_no=SF1234567890123" \
  -H "Authorization: Bearer ak_xxxx"

返回示例

response{
  "code": 0,
  "msg": "ok",
  "data": {
    "status": "运输中",
    "traces": [
      { "time": "2026-11-02 10:12:00", "desc": "快件已到达【杭州转运中心】" },
      { "time": "2026-11-02 08:30:00", "desc": "快件已从【深圳集散中心】发出" }
    ]
  }
}

返回字段说明

8. 取消运单

允许商户取消已下单的运单；已支付订单取消成功后自动退款到会员余额。

请求参数

取消规则

请求示例

cURLcurl -X POST "/api/order/cancel" \
  -H "Authorization: Bearer ak_xxxx" \
  -d "order_no=KD20261102000123&reason=买家改地址"

返回示例

response{
  "code": 0,
  "msg": "取消成功",
  "data": {
    "id": 10086,
    "order_no": "KD20261102000123",
    "waybill_no": "SF1234567890123",
    "status": 5,
    "status_text": "已取消",
    "refund": true
  }
}

返回字段说明

9. 资金信息

查询会员账户的钱包余额、推广费与积分，无需请求参数。

请求示例

cURLcurl -X POST "/api/member/fund" \
  -H "Authorization: Bearer ak_xxxx"

返回示例

response{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance": 100.00,
    "commission": 12.21,
    "integral": 36
  }
}

返回字段说明

10. 推送回调（平台 → 您的服务器）

在令牌「推送回调地址」填写您的接口地址后，订单状态或运单号发生变更时，平台会主动 POST JSON 到该地址。留空则不推送。

通用推送参数

pushType=1 状态变更 · data 对象

pushType=4 订单变更 · data 对象

应答要求

推送示例

状态变更{
  "thirdOrderNo": "KD20261102000123",
  "waybillNo": "SF1234567890123",
  "orderNo": "10086",
  "type": "SF",
  "pushType": 1,
  "data": {
    "status": 3,
    "desc": "运输中"
  }
}

运单号生成{
  "thirdOrderNo": "KD20261102000123",
  "waybillNo": "SF1234567890123",
  "orderNo": "10086",
  "type": "SF",
  "pushType": 4,
  "data": {
    "changeType": 1,
    "newWaybillNo": "SF1234567890123"
  }
}

接收端示例（PHP）

callback.php<?php
// 读取并记录推送内容
$body = file_get_contents('php://input');
file_put_contents('/var/log/callback.log', $body, FILE_APPEND);
// 必须在 2 秒内输出 SUCCESS
echo 'SUCCESS';