快服务第三方对接文档

version 1.6

发布日期 2018-11-13

合作咨询电话：13699105453

OPENAPI 文档简介

快服务第三方对接系统，允许第三方以商户身份，对接快服务配送运力，开发者可以通过阅读本接口文档来帮助开发。为了识别商户，快服务配送平台针对每个商户账号会产生一个唯一的App Id，相对应App Id还会分配一个Secret Key，用于验证商户身份的合法性。

商户注册通道

接入说明

快服务 OPENAPI 系统，采用 REST 风格设计，所有接口请求地址都是可预期的以及面向资源的。使用规范的 HTTP 响应代码来表示请求结果的正确或错误信息，所有的 API 请求都会以规范友好的 JSON 对象格式返回（包括错误信息）。

一、通讯协议与报文格式

通讯双方采用http作为通讯协议，请求头必须添加："Content-Type": "application/json;charset=utf-8"，编码格式为UTF-8。

二、接口调用URL

正式http请求URL: http://*.*.kfw.net
联调http请求URL: http://*.*.kfw.net

 
正式http请求URL: http://*.*.kfw.net
联调http请求URL: http://*.*.kfw.net

三、签名规则

每个接口访问时需要带一个签名参数 sign ，假设请求传送的参数如下：

{
    "app_id": "abc123",
    "address": "北京市朝阳区"
}

 
{
    "app_id": "abc123",
    "address": "北京市朝阳区"
}

第一步，对参数按照key=value的格式，并按照参数名ASCII字典顺序从小到大排序如下：

data = "address=北京市朝阳区&app_id=abc123"

 
data = "address=北京市朝阳区&app_id=abc123"

第二步，拼接API密钥

sign_data = "address=北京市朝阳区&app_id=abc123&key=xyz456"

 
sign_data = "address=北京市朝阳区&app_id=abc123&key=xyz456"

key对应的value为app_secret的值，在联调和上线时进行分配。

第三步，签名字符串进行MD5加密，生成32位的字符串，并转换为大写，得到如下参数即为正确：

19EF15AA3599ABD2994AF7CC62788C3E

 
19EF15AA3599ABD2994AF7CC62788C3E

最终请求json：

{
    "app_id": "abc123",
    "address": "北京市朝阳区",
    "sign": "19EF15AA3599ABD2994AF7CC62788C3E"
}

 
{
    "app_id": "abc123",
    "address": "北京市朝阳区",
    "sign": "19EF15AA3599ABD2994AF7CC62788C3E"
}

特别注意：

参数名需区分大小写
参数默认值为空字符串，请不要用null,none,false,true之类
字符串UTF-8编码

四、联调参数

测试环境联调参数如下：

app_id : kfw_dTuBCMsnyG0C6ipJ
openid : 1546057964
access_token : bdb53967a481c353b7b1539358a287bf6833fb95
app_secret : kbd8WmrIZXvRdt36YBuQaRc2gc8j7LfH

注：

公共参数中，access_token为商户授权token，是固定值。
联调测试阶段，使用联调测试参数进行开发测试，开发者通过接口返回信息，进行相应调整。
申请上线，第三方需要注册认证成为快服务商户，使用线上参数进行系统对接。

相关接口

一、计算配送费用

POST

http://..net/openapi/v1/order/expense

请求参数说明

参数名	类型	是否必须	描述
sign	string	是	签名，签名规则见文档接入说明
app_id	string	是	开发者ID
access_token	string	是	商户授权token
openid	int	是	用户ID
goods_weight	float	是	单位: kg
expect_time	string	否	期望取货时间，格式：2018-11-13 17:00:00
receiver_city	string	是	收货地所在城市
receiver_address	string	是	收货人地址
receiver_lat	string	否	收货人地址纬度，由百度地图提供
receiver_lng	string	否	收货人地址经度，由百度地图提供
sender_city	string	是	发货地所在城市
sender_address	string	是	发货人地址
sender_lat	string	否	发货人地址纬度，由百度地图提供
sender_lng	string	否	发货人地址经度，由百度地图提供

响应参数说明

参数名	类型	示例值	描述
respcd	string	0000	响应状态码
resperr	string	签名错误	响应错误信息
expense1	float	18	专人直送配送费，单位为元。当返回值为-1时，表示当前区域不支持此服务
expense4	float	16.5	当日达配送费，单位为元。当返回值为-1时，表示当前区域不支持此服务
dist	float	1.4	专人直送的配送距离，单位为km

成功返回值示例

{
    "expense_1h": 18,
    "dist": 1.4,
    "expense_4h": 16.5,
    "respcd": "0000"
}

 
{
    "expense_1h": 18,
    "dist": 1.4,
    "expense_4h": 16.5,
    "respcd": "0000"
}

异常返回值示例

{
    "resperr": "签名错误",
    "respcd": "2400"
}

 
{
    "resperr": "签名错误",
    "respcd": "2400"
}

二、查询目标地址所在站点

GET

http://..net/openapi/v1/order/target_station

请求参数说明

参数名	类型	是否必须	描述
app_id	string	是	开发者ID
city	string	是	地址所在城市
address	string	是	地址
business	int	是	配送服务类型；1表示专人直送，4表示当日达或次日达
sign	string	是	签名，签名规则见文档接入说明

响应参数说明

参数名	类型	示例值	描述
respcd	string	0000	响应状态码
resperr	string	分单失败	响应错误信息
address	string	地址	目标地址
city	string	北京市	城市
station_id	int	103058	站点ID
station_name	string	青年路快服务	配送站点

成功返回值示例

{
    "city": "北京市",
    "station_id": 103058,
    "address": "北京市朝阳区远洋国际中心",
    "respcd": "0000",
    "station_name": "青年路快服务"
}

 
{
    "city": "北京市",
    "station_id": 103058,
    "address": "北京市朝阳区远洋国际中心",
    "respcd": "0000",
    "station_name": "青年路快服务"
}

异常返回值示例

{
    "resperr": "分单失败",
    "respcd": "2400"
}

 
{
    "resperr": "分单失败",
    "respcd": "2400"
}

三、推送订单

POST

http://..net/openapi/v1/order/add

请求参数说明

参数名	类型	是否必须	描述
sign	string	是	签名，签名规则见文档接入说明
app_id	string	是	开发者ID
openid	int	是	商户ID
access_token	string	是	用户授权token
order_id	string	是	第三方对接平台订单ID，长度不超过16位
business	int	是	配送服务类型；1表示专人直送，4表示当日达或次日达
ship_id	string	否	运单ID，只适用于同城当日达、次日达业务，长度不超过16位
sub_sheet	string	否	子单ID，只适用于当日达或次日达子母单业务(多个子单号为1，2，3)
goods_info	string	是	订单商品信息
goods_weight	float	否	订单商品重量，单位: kg，business为4时，为必须参数
goods_price	int	否	订单代收货款，单位: 分
remark	string	否	订单备注信息
expect_time	string	否	期望取货时间，business为4时，时间在09:00~18:00之间
sender_name	string	否	发货人名称
sender_address	string	是	商户地址（发货人地址）
sender_city	string	是	发货地所在位置城市名，如”北京市”
sender_tel	string	是	发货人手机号
sender_lat	float	是	发货人地址纬度，由百度地图提供
sender_lng	float	是	发货人地址经度，由百度地图提供
receiver_name	string	否	收货人名称
receiver_address	string	是	收货人地址
receiver_city	string	是	收货地所在城市
receiver_tel	string	是	收货人手机号
receiver_lat	float	是	收货人地址纬度，由百度地图提供
receiver_lng	float	是	收货人地址经度，由百度地图提供
callback_url	string	否	回调url，订单状态变更时回调

响应参数说明

参数名	类型	示例值	描述
respcd	string	0000	响应状态码
resperr	string	签名错误	响应错误信息
order_id	string	1234567890	对接方订单ID
ship_id	string	1234567890	快服务运单ID，后续根据此ID查询订单状态
expense	float	16.5	订单配送费用

请求参数示例

{
    "sign": "9527D65B4A83C692ABA6E4C88739437E",
    "app_id": "kfw_dTuBCMsnyG0C6ipJ",
    "openid": 1546057964,
    "access_token": "bdb53967a481c353b7b1539358a287bf6833fb95",
    "order_id": "1234567890",
    "business": 4,
    "ship_id": "1234567890",
    "goods_info": "商品信息",
    "goods_weight": 2.5,
    "goods_price": 1000,
    "expect_time": "2018-11-13 17:00:00",
    "sender_name": "张三",
    "sender_address": "北京市朝阳区融科望京中心",
    "sender_city": "北京市",
    "sender_tel": "13888888888",
    "sender_lat": 40.003765,
    "sender_lng": 116.490155,
    "receiver_name": "李四",
    "receiver_address": "北京市朝阳区远洋国际中心",
    "receiver_city": "北京市",
    "receiver_tel": "18888888888",
    "receiver_lat": 39.920589,
    "receiver_lng": 116.497980
}

 
{
    "sign": "9527D65B4A83C692ABA6E4C88739437E",
    "app_id": "kfw_dTuBCMsnyG0C6ipJ",
    "openid": 1546057964,
    "access_token": "bdb53967a481c353b7b1539358a287bf6833fb95",
    "order_id": "1234567890",
    "business": 4,
    "ship_id": "1234567890",
    "goods_info": "商品信息",
    "goods_weight": 2.5,
    "goods_price": 1000,
    "expect_time": "2018-11-13 17:00:00",
    "sender_name": "张三",
    "sender_address": "北京市朝阳区融科望京中心",
    "sender_city": "北京市",
    "sender_tel": "13888888888",
    "sender_lat": 40.003765,
    "sender_lng": 116.490155,
    "receiver_name": "李四",
    "receiver_address": "北京市朝阳区远洋国际中心",
    "receiver_city": "北京市",
    "receiver_tel": "18888888888",
    "receiver_lat": 39.920589,
    "receiver_lng": 116.497980
}

成功返回值示例

# 专人直送业务返回
{
    "distance": 1.4,
    "order_id": "1234567890",
    "ship_id": "KFWZS147888889",
    "respcd": "0000",
    "expense": 18
}

 
# 专人直送业务返回
{
    "distance": 1.4,
    "order_id": "1234567890",
    "ship_id": "KFWZS147888889",
    "respcd": "0000",
    "expense": 18
}

# 当日达或次日达业务返回
{
    "data": {
        "order_id": "1234567890",
        "ship_id": "1234567890",
        "expense": 16.5
    },
    "respcd": "0000"
}

 
# 当日达或次日达业务返回
{
    "data": {
        "order_id": "1234567890",
        "ship_id": "1234567890",
        "expense": 16.5
    },
    "respcd": "0000"
}

异常返回值示例

{
    "resperr": "发货地暂未开通服务",
    "respcd": "2400"
}

 
{
    "resperr": "发货地暂未开通服务",
    "respcd": "2400"
}

四、查询订单配送状态

POST

http://..net/openapi/v1/order/status

请求参数说明

参数名	类型	是否必须	描述
app_id	string	是	开发者ID
access_token	string	否	用户授权token，平台查询无需提供
ship_id	string	是	运单ID
sign	string	是	签名，签名规则见文档接入说明

响应参数说明

参数名	类型	示例值	描述
respcd	string	0000	响应状态码
resperr	string	没有该运单	响应错误信息
order_id	string	20181111905467	对接方订单ID
ship_id	string	KN10161346061	快服务运单ID，后续根据此ID查询订单状态
headquarters	string	北京快服务	配送所属分站
business	int	4	配送服务类型；1表示专人直送，4表示当日达或次日达
order_status	int	2	状态说明，1=已创建，2=已接单，3=已取货，4=已送达，7=已取消
state	int	4	物流状态，只适用于同城当日达、次日达业务 0=发件，1=到件，2=收(揽)件，3=派件，4=签收，5=退回，6=退签
courier_name	string	陈师傅	骑士姓名
courier_mobile	string	13000000000	骑士联系方式
courier_lat	float	39.915210	骑士纬度
courier_lng	float	116.403900	骑士经度
details	list	[]	配送详情

成功返回值示例

{
    "respcd": "0000",
    "order_id": "20181111905467",
    "ship_id": "KN10161346061",
    "headquarters": "北京快服务",
    "business": 4,
    "order_status": 4,
    "state": 4,
    "courier_name": "陈师傅",
    "courier_mobile": "13000000000",
    "courier_lat": 39.915210,
    "courier_lng": 116.403900,
    "details": [
        {
            "status": -6,
            "info": "运单信息已录入",
            "state": 0,
            "time": "2018-11-12 14:54:05"
        },
        {
            "status": 0,
            "info": "运单已分配【建国门快服务】派件",
            "state": 0,
            "time": "2018-11-12 14:54:05"
        },
        {
            "status": 0,
            "info": "运单已分配【王府井快服务】揽件",
            "state": 0,
            "time": "2018-11-12 14:54:05"
        },
        {
            "status": 5,
            "info": "运单已分配揽件骑士【周师傅】，骑士会尽快上门揽收，联系电话【18311151111】",
            "state": 1,
            "time": "2018-11-12 14:54:09"
        },
        {
            "status": 1,
            "info": "运单已揽收，揽件骑士【李师傅】",
            "state": 2,
            "time": "2018-11-12 15:23:06"
        },
        {
            "status": 2,
            "info": "运单已到达【王府井快服务】",
            "state": 2,
            "time": "2018-11-12 15:54:59"
        },
        {
            "status": 3,
            "info": "中转员【邵师傅】已装车，即将发往【建国门快服务】",
            "state": 0,
            "time": "2018-11-13 05:05:23"
        },
        {
            "status": 7,
            "info": "运单已到达【建国门快服务】",
            "state": 1,
            "time": "2018-11-13 07:47:03"
        },
        {
            "status": 4,
            "info": "运单已分配给骑士【陈师傅】，正在派送，联系电话【13000000000】",
            "state": 3,
            "time": "2018-11-13 07:47:24"
        },
        {
            "status": 6,
            "info": "客户已签收，感谢使用快服务",
            "state": 4,
            "time": "2018-11-13 09:04:59"
        }
    ]
}

 
{
    "respcd": "0000",
    "order_id": "20181111905467",
    "ship_id": "KN10161346061",
    "headquarters": "北京快服务",
    "business": 4,
    "order_status": 4,
    "state": 4,
    "courier_name": "陈师傅",
    "courier_mobile": "13000000000",
    "courier_lat": 39.915210,
    "courier_lng": 116.403900,
    "details": [
        {
            "status": -6,
            "info": "运单信息已录入",
            "state": 0,
            "time": "2018-11-12 14:54:05"
        },
        {
            "status": 0,
            "info": "运单已分配【建国门快服务】派件",
            "state": 0,
            "time": "2018-11-12 14:54:05"
        },
        {
            "status": 0,
            "info": "运单已分配【王府井快服务】揽件",
            "state": 0,
            "time": "2018-11-12 14:54:05"
        },
        {
            "status": 5,
            "info": "运单已分配揽件骑士【周师傅】，骑士会尽快上门揽收，联系电话【18311151111】",
            "state": 1,
            "time": "2018-11-12 14:54:09"
        },
        {
            "status": 1,
            "info": "运单已揽收，揽件骑士【李师傅】",
            "state": 2,
            "time": "2018-11-12 15:23:06"
        },
        {
            "status": 2,
            "info": "运单已到达【王府井快服务】",
            "state": 2,
            "time": "2018-11-12 15:54:59"
        },
        {
            "status": 3,
            "info": "中转员【邵师傅】已装车，即将发往【建国门快服务】",
            "state": 0,
            "time": "2018-11-13 05:05:23"
        },
        {
            "status": 7,
            "info": "运单已到达【建国门快服务】",
            "state": 1,
            "time": "2018-11-13 07:47:03"
        },
        {
            "status": 4,
            "info": "运单已分配给骑士【陈师傅】，正在派送，联系电话【13000000000】",
            "state": 3,
            "time": "2018-11-13 07:47:24"
        },
        {
            "status": 6,
            "info": "客户已签收，感谢使用快服务",
            "state": 4,
            "time": "2018-11-13 09:04:59"
        }
    ]
}

异常返回值示例

{
    "resperr": "没有该运单",
    "respcd": "2400"
}

 
{
    "resperr": "没有该运单",
    "respcd": "2400"
}

五、取消订单

POST

http://..net/openapi/v1/order/cancel

请求参数说明

参数名	类型	是否必须	描述
app_id	string	是	开发者ID
access_token	string	是	用户授权token
ship_id	string	是	运单ID
order_id	string	是	订单ID
reason	string	是	取消原因
sign	string	是	签名，签名规则见文档接入说明

响应参数说明

参数名	类型	示例值	描述
respcd	string	0000	响应状态码
resperr	string	已经签收的运单，无法操作	响应错误信息
status	string	ok	取消状态
info	string	取消成功

成功返回值示例

{
    "status": "ok",
    "kind": "Cancel",
    "data": {
        "status": "ok",
        "info": "取消成功"
    },
    "respcd": "0000"
}

 
{
    "status": "ok",
    "kind": "Cancel",
    "data": {
        "status": "ok",
        "info": "取消成功"
    },
    "respcd": "0000"
}

异常返回值示例

{
    "resperr": "运单已签收，无法操作",
    "respcd": "2400"
}

 
{
    "resperr": "运单已签收，无法操作",
    "respcd": "2400"
}

六、订单状态回调

POST

下单接口传入的callback_url / 订单订阅时的callback_url

请求参数说明

参数名	类型	示例值	描述
order_id	string	20181111905467	对接方订单ID
ship_id	string	KN10161346061	快服务运单ID，后续根据此ID查询订单状态
headquarters	string	北京快服务	配送所属分站
order_status	int	2	状态说明，1=已创建，2=已接单，3=已取货，4=已送达，7=已取消
state	int	4	物流状态，0=发件，1=到件，2=收(揽)件，3=派件，4=签收，5=退回，6=退签
courier_name	string	陈师傅	骑士姓名
courier_mobile	string	13000000000	骑士联系方式
courier_lat	float	39.915210	骑士纬度
courier_lng	float	116.403900	骑士经度
msg	string	用户取消	补充信息，如取消原因
operation_time	string	2018-11-13 14:44:25	操作时间
details	list		状态变更详情

响应参数说明

类型	示例值	描述
string	success	第三方处理正常请返回success字符串，否则，会重新请求一次回调接口

请求参数示例

{
    "order_id": "20181111905467",
    "ship_id": "KN10161346061",
    "headquarters": "北京快服务",
    "order_status": 3,
    "state": 3,
    "courier_name": "陈师傅",
    "courier_mobile": "13000000000",
    "courier_lat": 39.915210,
    "courier_lng": 116.403900,
    "msg": "",
    "operation_time": "2018-11-13 07:47:24",
    "details": [
        {
            "status":4,
            "info":"运单已分配给骑士【陈师傅】，正在派送，联系电话【13000000000】",
            "state":3,
            "time":"2018-11-13 07:47:24"
        }
    ]
}

 
{
    "order_id": "20181111905467",
    "ship_id": "KN10161346061",
    "headquarters": "北京快服务",
    "order_status": 3,
    "state": 3,
    "courier_name": "陈师傅",
    "courier_mobile": "13000000000",
    "courier_lat": 39.915210,
    "courier_lng": 116.403900,
    "msg": "",
    "operation_time": "2018-11-13 07:47:24",
    "details": [
        {
            "status":4,
            "info":"运单已分配给骑士【陈师傅】，正在派送，联系电话【13000000000】",
            "state":3,
            "time":"2018-11-13 07:47:24"
        }
    ]
}

成功返回值示例

"success"

 
"success"

【注意事项】

接口参数涉及经纬度的统一要求百度地图提供的经纬度信息，其他经纬度需做转换。
返回值为签名错误时，都是因为sign构造时，没有按照文档签名规则进行处理。
返回值为服务异常时，可能是由于参数缺失或地址超出配送范围，请严格按照接口文档进行参数构造。
下单接口，order_id和ship_id可以相同，若存在ship_id，快服务系统运单ID以此为准。
订单状态回调，除下单操作以外，每次变更订单状态都会进行回调。
线上环境参数需要联系我们进行分配，线上请求域名为：http://*.*.kfw.net

快服务第三方对接文档

version 1.6

发布日期 2018-11-13

OPENAPI 文档简介

接入说明

一、通讯协议与报文格式

二、接口调用URL

三、签名规则

四、联调参数

相关接口

一、计算配送费用

POST

http://*.*.net/openapi/v1/order/expense

请求参数说明

响应参数说明

成功返回值示例

异常返回值示例

二、查询目标地址所在站点

GET

http://*.*.net/openapi/v1/order/target_station

请求参数说明

响应参数说明

成功返回值示例

异常返回值示例

三、推送订单

POST

http://*.*.net/openapi/v1/order/add

请求参数说明

响应参数说明

请求参数示例

成功返回值示例

异常返回值示例

四、查询订单配送状态

POST

http://*.*.net/openapi/v1/order/status

请求参数说明

响应参数说明

成功返回值示例

异常返回值示例

五、取消订单

POST

http://*.*.net/openapi/v1/order/cancel

请求参数说明

响应参数说明

成功返回值示例

异常返回值示例

六、订单状态回调

POST

下单接口传入的callback_url / 订单订阅时的callback_url

请求参数说明

响应参数说明

请求参数示例

成功返回值示例

【注意事项】

http://..net/openapi/v1/order/expense

http://..net/openapi/v1/order/target_station

http://..net/openapi/v1/order/add

http://..net/openapi/v1/order/status

http://..net/openapi/v1/order/cancel