一、接口介绍

发现一个非常好用的上门取件 API 接口——快递 100 商家寄件 API。通过这个接口提交寄件请求，可以直接下单至各快递公司，实现快递员上门取件，下单还可以享运费折扣

这个接口支持国内主流快递公司如 EMS、德邦、京东、极兔、圆通、申通、中通、韵达下单，也就不需要逐家接口对接了。

适用场景：电商退换货用户可以在 APP 上一键退货并自选上门取件的时间；二手回收；发货量较小，无月结账号的微商发货；品牌商家门店发货或门店调拨。

二、 接口测试与对接指南

登录地址： https://api.kuaidi100.com/login/

在对接快递 100 预约上门取件接口前，我们需要完成以下步骤：

注册与获取 API Key

前往快递 100API 开放平台注册账号。 联系客户经理充值运费，获取 API Key 和 Secret。

1、商家寄件（下单价格）

注意：下单价格就是可以查看到下单的预估价格，然后还有折扣的价格

1.1 请求地址

提供统一格式的 HTTP POST 或 GET 调用接口,并返回统一格式 JSON 数据。

https://poll.kuaidi100.com/order/borderapi.do

1.2 请求参数：

param 数据结构：

1.3 返回结果

data 数据结构：

1.4 提供数据内容

请求参数示例

method = price
key = ******
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1647258957705
param = {
    "kuaidicom": "yuantong",
    "sendManPrintAddr": "杭州市西湖区东三十马路",
    "recManPrintAddr": "黑龙江哈尔滨南岗区一匡小区",
    "weight": "1",
    "serviceType": "标准快递"
}

返回结果示例

{
  "data": {
    "firstPrice": "8.0",
    "defPrice": "8.0",
    "defFirstPrice": "8.0",
    "price": "8.0",
    "serviceType": "标准快递",
    "overPrice": "0",
    "defOverPrice": "0",
    "kuaidiCom": "zhongtong"
  },
  "message": "成功",
  "result": true,
  "returnCode": "200"
}

说明：

1.5 Python 测试代码和测试结果

测试代码

# coding = utf-8
import hashlib
import json
import time
import requests


def do_request(url, key, secret, method, t, param):
    md = hashlib.md5()
    md.update((param + t + key + secret).encode())
    sign = md.hexdigest().upper()
    payload = {
        'key': key,
        'method': method,
        't': t,
        'param': param,
        'sign': sign
    }
    return requests.post(url, payload).text


if __name__ == '__main__':
    key = ''  # TODO 客户授权key
    secret = ''  # TODO 秘钥
    url = 'https://poll.kuaidi100.com/order/borderapi.do'  # 请求地址
    method = 'price'


    param = {
        "kuaidiCom": "yuantong",
        "sendManPrintAddr": "杭州市西湖区东三十马路",
        "recManPrintAddr": "黑龙江哈尔滨南岗区一匡小区",
        "weight": "",
        "serviceType": ""
    }
    t = str(int(round(time.time() * 1000)))
    result = do_request(url, key, secret, method, t, json.dumps(param))
    print(result)

测试数据

测试结果

测试结果概述：returnCode=200 表示接口请求成功。具体返回信息如下表：

注意：具体返回数据以接口实时返回数据为主。

2、商家寄件（下单）

选择快递公司进行下单,可以预约上门取件时间。

2.1 接口格式

提供统一格式的 HTTP POST 或 GET 调用接口,并返回统一格式 JSON 数据。

2.2 请求地址

正式请求地址：https://poll.kuaidi100.com/order/borderapi.do（订单将推至快递公司）

沙箱请求地址：https://api.kuaidi100.com/apiMock/border（订单将不推至快递公司：沙箱下单后，可通过：调试工具-商家寄件-下单回调，调试订单各阶段状态。）

请求参数：

param 数据结构：

2.3 返回结果

data 数据结构

eOrder 数据结构

注意：eOrder 实际返回的字段各家快递公司不同，以实际返回为准

2.4 提供数据内容

请求参数示例

method = bOrder
key = ******
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1647258957705
param = {
    "kuaidicom": "yuantong",
    "recManName": "王超",
    "recManMobile": "13800138000",
    "recManPrintAddr": "西藏日喀则市定日县珠穆朗玛峰",
    "sendManName": "王大",
    "sendManMobile": "13800138000",
    "sendManPrintAddr": "西藏日喀则市定日县珠穆朗玛峰",
    "cargo": "文件",
    "callBackUrl": "http: //www.baidu.com",
    "payment": "SHIPPER",
    "serviceType": "标准快递",
    "weight": "1",
    "remark": "",
    "salt": "",
    "dayType": "",
    "pickupStartTime": "",
    "pickupEndTime": "",
    "passwordSigning": "Y",
    "valinsPay": "",
    "op": "0",
    "pollCallBackUrl": "",
    "resultv2": "0",
    "returnType": "",
    "siid": "",
    "tempid": "",
    "printCallBackUrl": ""
}

返回结果示例

{
    "result": true,
    "returnCode": "200",
    "message": "提交成功",
    "data": {
        "taskId": "", // 任务ID
        "orderId": "" // 订单ID
        "kuaidinum": "" // 快递单号
        "eOrder": "[\"destName\":null,\"orgName\":null,\"pkgCode\":null,\"pkgName\":null,\"bulkpen\":\"上海-S33-K27-P\",\"orgExtra\":null}]"
    }
}

说明：

2.5 python 测试代码和测试结果

测试代码

# coding = utf-8
import hashlib
import json
import time
import requests


def do_request(url, key, secret, method, t, param):
    md = hashlib.md5()
    md.update((param + t + key + secret).encode())
    sign = md.hexdigest().upper()
    payload = {
        'key': key,
        'method': method,
        't': t,
        'param': param,
        'sign': sign
    }
    return requests.post(url, payload).text


if __name__ == '__main__':
    key = '********'  # TODO 客户授权key
    secret = '********'  # TODO 秘钥
    url = 'https://poll.kuaidi100.com/order/borderapi.do'  # 请求地址
    method = 'bOrder'


    param = {
        "kuaidicom": "shentong",
        "recManName": "李四",
        "recManMobile": "15045666312",
        "recManPrintAddr": "黑龙江哈尔滨南岗区一匡小区",
        "sendManName": "张三",
        "sendManMobile": "15045666311",
        "sendManPrintAddr": "杭州市西湖区东三十马路",
        "cargo": "书籍",
        "callBackUrl": "http://meihua150.cn/reback",
        "payment": "",
        "serviceType": "",
        "weight": "",
        "remark": "",
        "salt": "",
        "dayType": "",
        "pickupStartTime": "",
        "pickupEndTime": "",
        "passwordSigning": "N",
        "valinsPay": "",
        "op": "0",
        "pollCallBackUrl": "",
        "resultv2": "0"
    }
    t = str(int(round(time.time() * 1000)))
    result = do_request(url, key, secret, method, t, json.dumps(param))
    print(result)
    # {"data":{"kuaidinum":"YT2213099035201","orderId":"20066771","attach":null,"taskId":"9FC293CA417E431F33046E64F4C4EC20"},"message":"提交成功","result":true,"returnCode":"200"}

测试数据

测试结果

测试结果概述：returnCode=200 表示接口请求成功。具体返回信息如下表：

注意：具体返回数据以接口实时返回数据为主。

3、商家寄件（下单取消）

对下完单且取件前的订单进行取消操作。对于不需邮寄的订单请及时进行取消，当月订单最晚需在次月 8 日前取消，否则将无法取消。

3.1 接口格式

提供统一格式的 HTTP POST 或 GET 调用接口,并返回统一格式 JSON 数据。

3.2 请求地址

https://poll.kuaidi100.com/order/borderapi.do

请求参数：

param 数据结构：

3.3 返回结果

3.4 提供数据内容

请求参数示例

method = cancel
key = ******
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1647258957705
param = {
    "taskId": "*****",
    "orderId": "*****",
    "cancelMsg": "暂时不寄件了"
}

返回结果示例

{
  "result": true,
  "returnCode": "200",
  "message": "取消成功",
  "data": {}
}

说明：

3.5 Python 测试代码和测试结果

测试代码

# coding = utf-8
import hashlib
import json
import time
import requests


def do_request(url, key, secret, method, t, param):
    md = hashlib.md5()
    md.update((param + t + key + secret).encode())
    sign = md.hexdigest().upper()
    payload = {
        'key': key,
        'method': method,
        't': t,
        'param': param,
        'sign': sign
    }
    return requests.post(url, payload).text


if __name__ == '__main__':
    key = ''  # TODO 客户授权key
    secret = ''  # TODO 秘钥
    url = 'https://poll.kuaidi100.com/order/borderapi.do'  # 请求地址
    method = 'cancel'


    param = {
        "taskId": "EFCC9B7835C226766E2BC9AE1E420593",
        "orderId": "229206462",
        "cancelMsg": "暂时不寄件了"
    }
    t = str(int(round(time.time() * 1000)))
    result = do_request(url, key, secret, method, t, json.dumps(param))
    print(result)

测试数据

测试结果

测试结果概述：returnCode=200 表示接口请求成功，返回结果为取消成功。

注意：具体返回数据以接口实时返回数据为主。

4、商家寄件（下单回调）

订单有状态变更是会触发回调，回调后如果没有得到合作方正确返回，会重复回调多 2 次，即最多回调 3 次。间隔 30 分钟。

上门取件下单成功以后，快递员收到订单，会反馈接单状态，快递 100 会把状态实时推送到我们自己的服务器。

4.1 接口格式

提供统一格式的 HTTP POST,并返回统一格式 JSON 数据。

请求报头：Content-Type=application/x-www-form-urlencoded;charset=UTF-8

4.2 请求地址

请求参数：

param 数据结构：

data 数据结构：

4.3 返回结果

4.4 提供数据内容

请求参数示例

taskId = ** ** **
sign = ** ** **
param = {
    "kuaidicom": "yuantong",
    "kuaidinum": "1234567890",
    "status": "200",
    "message": "成功",
    "data": {
        "orderId": "*****",
        "status": "0",
        "courierName": "王大",
        "courierMobile": "13800138000",
        "weight": "1",
        "defPrice": "15.0",
        "freight": "5.1",
        "volume": "120",
        "actualWeight": "1",
        "feeDetails": [{
            "feeType": "PACKAGINGFEE",
            "feeDesc": "包装费",
            "amount": "0.8",
            "payStatus": 1
        }]，
        "printTaskId": "*****",
        "imgBase64": "*****"
    }
}

返回结果示例

{
  "result": true,
  "returnCode": "200",
  "message": "成功"
}

4.5 回调响应报文及错误码解释

三、总结

快递 100API 开放平台提供以快递查询、快递在线下单预约上门取件为核心的一系列业务接口，对每个接口的开发文档丰富而全面，并且提供标准的多语言示例代码（Java、Python、PHP、.Net）。上面是对下单价格、下单、下单取消，下单回调接口的应用实例。

通过本文的指南，相信您可以快速完成相关接口对接，并利用这项技术提升用户体验和业务效率。