文档中心
一. 获取店铺授权超链接接口 二. 提交销售订单获取任务接口 三. 销售订单获取结果推送接口 四、提交售后(退货)订单获取任务接口 五、售后(退货)订单获取结果推送接口 六、快递单号回传及订单发货接口 七、 信息代码含义 API调试工具

一、获取店铺授权超链接接口

获取到授权超链接后,在浏览器登录授权店铺,也可以通过后台页面进行店铺授权:

https://api.kuaidi100.com/delivery/expressPrint

1.1 接口格式

POST application/x-www-form-urlencoded

1.2 请求地址

https://api.kuaidi100.com/ent/shop/authorize

1.3 请求参数

请求参数(header)

名称类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body)

参数名称数据类型是否必填参数描述
keystring授权码,请申请企业版获取
signstring32位大写,签名,用于验证身份,按MD5 (param + key + secret)的顺序进行MD5加密,不需要加上“+”号。secret在企业管理后台获取
paramObject由其他参数拼接

param数据结构

参数名称数据类型是否必填参数描述
shopTypestring店铺类型,TAOBAO:淘宝,JINGDONG:京东,TOUTIAO:抖店,PINDUODUO:拼多多,KUAISHOU:快手,KUAITUANTUAN:快团团 ,WEIPINHUI:唯品会,YOUZAN:有赞,WEIDIAN:微店,SHIPINHAO:视频号小店,XIAOHONGSHU:小红书。
callbackUrlstring回调地址,默认仅支持http
saltString回调参数sign的加密参数,非空时回调才会有sign参数

1.4 返回结果

字段类型说明备注
resultboolean提交结果true表示成功
returnCodenumber返回编码
messagestring返回报文描述
dataobject业务数据

data数据结构

字段类型说明备注
authorizeUrlstring店铺授权超链接

1.5 返回结果示例


 {
    "result": true,
    "returnCode": 200,
    "message": "SUCCESS",
    "data": {
        "authorizeUrl": "https://oauth.taobao.com/authorize?response_type=code&client_id=21153231&redirect_uri=https%3A%2F%2Ftb.kuaidi100.com%2Fopen%2Ftaobao%2FauthToken.do&state=YXBwS2V5OnkzRXlDanJ3OW9u45698ZTFjMGEyZDA4NDA0MzI0OWE0YmYzOTkyM222ZjMw&view=web"
    }
}

1.6 授权成功推送

用户获取授权超链接的时候,使用到callbackUrl并且授权成功后才会推送。 每条消息推送用户接收和保存成功后,应该返回这样的响应报文:{"result":true,"returnCode":200,"message":"成功"},我方根据result等于true作为推送成功标识,其他均为推送失败。推送失败会隔半小时后重推,连续3次重推都失败则放弃该条消息的推送。

1.6.1 接口格式

POST application/x-www-form-urlencoded

1.6.2 请求地址

由贵司在获取授权超链接请求中通过callbackUrl字段提供 请求参数(header)

名称类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body)

参数名称数据类型是否必填参数描述
signstring32位大写,提交订单获取任务salt非空时才会有该参数。签名,用于验证身份,按MD5 (param + salt)的顺序进行MD5加密,不需要加上“+”号
paramObject由其他参数拼接

param数据结构

参数名称数据类型参数描述
shopTypestring店铺类型,TAOBAO:淘宝,JINGDONG:京东,TOUTIAO:抖店,PINDUODUO:拼多多,KUAISHOU:快手,WEIPINHUI:唯品会,YOUZAN:有赞,WEIDIAN:微店,SHIPINHAO:视频号小店,XIAOHONGSHU:小红书。
shopIdstring店铺ID
shopNameString店铺名称

param示例值


{
	"shopType": "TAOBAO",
	"shopId": "413979111",
	"shopName": "百递云商城"
}

1.6.3推送返回示例


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

二、提交销售订单获取任务接口

用户提交指定时间范围内的销售订单获取任务,快递100根据时间范围拆分出多个销售订单获取的任务列表,返回任务列表给用户。后续快递100会根据任务列表获取销售订单信息,任务获取结束后会把获取结果推送到用户的回调地址中。 任务列表中,每个任务查询失败,隔5分钟后重试,连续3次重试都失败则会终止查询并且推送一条queryStatus=Abort的消息告知用户。

2.1 接口格式

POST application/x-www-form-urlencoded

2.2 请求地址

https://api.kuaidi100.com/ent/order/task

2.3 请求参数

请求参数(header)

名称类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body)

参数名称数据类型是否必填参数描述
keystring授权码,请申请企业版获取
signstring32位大写,签名,用于验证身份,按MD5 (param + key + secret)的顺序进行MD5加密,不需要加上“+”号
paramObject由其他参数拼接

param数据结构

参数名称数据类型是否必填参数描述
shopTypestring店铺类型,TAOBAO:淘宝,JINGDONG:京东,TOUTIAO:抖店,PINDUODUO:拼多多 ,KUAISHOU:快手,KUAITUANTUAN:快团团, DINGXIANG:丁香医生,WEIPINHUI:唯品会,YOUZAN:有赞,WEIDIAN:微店,SHIPINHAO:视频号小店,XIAOHONGSHU:小红书。
shopIdstring店铺ID
orderStatusstring订单状态,UNPAY:未付款;UNSHIP:待发货(默认值);SHIPED:等待买家确认收货;FINISH:交易成功/完成;CLOSE:交易关闭/取消
updateAtMinstring订单更新的最小时间,格式:yyyy-MM-dd HH:mm:ss
updateAtMaxstring订单更新的最大时间,格式:yyyy-MM-dd HH:mm:ss
callbackUrlstring回调地址,默认仅支持http
saltstring回调参数sign的加密参数,非空时回调才会有sign参数

2.4 返回结果

字段类型说明备注
resultboolean提交结果true表示成功
returnCodenumber返回编码
messagestring返回报文描述
dataobject业务数据

data数据结构

字段类型说明备注
totalnumber任务总数
tasksarray[object]任务类别

tasks数据结构

字段类型说明
taskIdstring任务编码
updateAtMinstring订单更新的最小时间,格式:yyyy-MM-dd HH:mm:ss
updateAtMaxstring订单更新的最大时间,格式:yyyy-MM-dd HH:mm:ss

2.5 成功响应结果示例


{
    "result": true,
    "returnCode": 200,
    "message": "SUCCESS",
    "data": {
        "total": 2,
        "tasks": [
            {
                "taskId": "61a8b60a9ac14514bd854318ac9a53ab",
                "updateAtMin": "2021-11-12 16:00:00",
                "updateAtMax": "2021-11-12 16:30:00"
            },
            {
                "taskId": "94261f0d24c54c34a6552584a0dd4197",
                "updateAtMin": "2021-11-12 16:30:00",
                "updateAtMax": "2021-11-12 17:00:00"
            }
        ]
    }
}
     

三、销售订单获取结果推送接口

用户提交订单获取任务的时候,使用到callbackUrl才会有获取结果推送。 每条消息推送用户接收和保存成功后,应该返回这样的响应报文:{"result":true,"returnCode":200,"message":"成功"},我方根据result等于true作为推送成功标识,其他均为推送失败。推送失败会隔半小时后重推,连续3次重推都失败则放弃该条消息的推送。任务列表中,每个任务查询失败,隔5分钟后重试,连续3次重试都失败则会终止查询并且推送一条queryStatus=Abort的消息告知用户。

3.1 接口格式

POST application/x-www-form-urlencoded

3.2 请求地址

由贵司在提交销售订单获取任务请求中通过callbackUrl字段提供

3.3 请求参数

请求参数(header)

名称类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body)

参数名称数据类型是否必填参数描述
signstring32位大写,提交订单获取任务salt非空时才会有该参数。签名,用于验证身份,按MD5 (param + salt)的顺序进行MD5加密,不需要加上“+”号
paramObject由其他参数拼接

param数据结构

参数名称数据类型参数描述
taskIdstring任务ID
queryStatusstring查询状态,Fail:查询失败;Empty:查无结果;Success:查询成功;Abort:终止,连续多次查询都失败
reasonstring订单获取不到的原因
ordersarray[object]订单列表

orders数据结构

参数名称数据类型参数描述
shopTypestring店铺类型,TAOBAO:淘宝,JINGDONG:京东,TOUTIAO:抖店,PINDUODUO:拼多多,KUAISHOU:快手 ,KUAITUANTUAN:快团团, DINGXIANG:丁香医生,WEIPINHUI:唯品会,YOUZAN:有赞,WEIDIAN:微店,SHIPINHAO:视频号小店,XIAOHONGSHU:小红书。
shopIdstring店铺ID
shopNamestring店铺名称
orderNumstring店铺订单号
orderStatusstring订单状态,UNPAY:未付款;UNSHIP:待发货(默认值);SHIPED:等待买家确认收货;FINISH:交易成功/完成;CLOSE:交易关闭/取消
receiverNamestring收件人姓名
receiverNameEncstring收件人姓名的密文
receiverMobilestring收件人手机号
receiverMobileEncstring收件人手机号的密文
receiverPhonestring收件人电话号码
receiverPhoneEncstring收件人电话号码的密文
receiverCountrystring收件国家或地区
receiverProvincestring收件人省份
receiverCitystring收件人城市
receiverDistrictstring收件人区县
receiverStreetstring收件人街道
receiverAddressstring收件人详细地址
receiverAddressEncstring收件人详细地址的密文
receiverZipstring收件人邮政编码
buyerMessagestring买家留言
tradeMemostring商家备注
createAtstring订单创建时间,格式:yyyy-MM-dd HH:mm:ss
updateAtstring订单更新时间,格式:yyyy-MM-dd HH:mm:ss
payTimestring支付时间,格式:yyyy-MM-dd HH:mm:ss
totalFeenumber商品金额
paymentnumber实付金额
sellerFeenumber货款金额(订单总金额-商家优惠金额)
postFeenumber邮费
oaidstring此字段用于淘宝接口解密
payTypenumber支付方式,1:货到付款;2:邮局汇款;3:自提;4:在线支付;5:公司转账;6:银行卡转账。如平台未返回该字段,则为:null
refundStatusnumber售后状态 ,1:无售后或售后关闭;2:售后处理中;3:退款中;4: 退款成功。如平台未返回该字段,则为:null
discountFeenumber优惠金额
goodsListarray[object商品信息列表

goodsList数据结构

参数名称数据类型参数描述
goodNamestring商品名称
goodUnitstring商品单位
goodCountnumber商品数量
goodPricenumber商品价格
skustringsku外部编码
goodSpecstring商品规格
goodPicPathstring商品图片地址
oidstring子订单编号
goodIdnumber商品外部编码
discountFeenumber子订单优惠金额

3.4 返回结果

字段类型说明备注
resultboolean提交结果true表示成功,否则隔半小时重推,连续3次重推失败则放弃该消息推送
returnCodenumber返回编码
messagestring返回报文描述

3.5 查询无结果的回调param参数示例


{
	"taskId": "bb8122cb5a3f48c9be2724e7f3fb2813",
	"queryStatus": "Empty",
	"reason": "查询无结果",
	"orders": []
}
     

3.6 查询有记录的回调param参数示例


{
	"taskId": "0badadb9642e48ef8ae8c7294e804719",
	"queryStatus": "Success",
	"reason": null,
	"orders": [{
		"shopType": "JINGDONG",
		"shopId": "617111",
		"shopName": "服务市场测试店铺",
		"orderNum": "232407101111",
		"orderStatus": "CLOSE",
		"receiverName": "张三",
		"receiverNameEnc": null,
		"receiverMobile": "186*******7",
		"receiverMobileEnc": "363433643e1cfffc68f625e78224d33a7ba4866561167ebdd3e201111cd80f789d50f",
		"receiverPhone": "186*******7",
		"receiverPhoneEnc": "363433643e1cfffc68f625e78224d33a7ba4866561167ebdd3e201111cd80f789d50f ",
		"receiverCountry": null,
		"receiverProvince": "广东",
		"receiverCity": "深圳市",
		"receiverDistrict": "南山区",
		"receiverAddress": "广东深圳市南山区高新园金蝶软件园",
		"receiverAddressEnc": null,
		"receiverZip": null,
		"buyerMessage": "",
		"tradeMemo": "",
		"createAt": "2021-12-23 10:38:06",
		"updateAt": "2021-12-23 10:42:23",
		"payTime": "2021-12-23 10:38:18",
		"totalFee": 0.01,
		"payment": 0.01,
		"sellerFee": 0.01,
		"postFee": 0.00,
		"oaid": null,
		"payType": 4,
		"refundStatus": null,
		"goodsList": [{
			"goodName": "二代云打印机",
			"goodUnit": null,
			"goodCount": 1,
			"goodPrice": 0.01,
			"sku": "10020316102459SJ2021081210",
			"goodSpec": null,
			"goodPicPath": null,
			"oid": null
		}]
	}]
}
     

四、提交售后(退货)订单获取任务接口

用户提交指定时间范围内的售后订单获取任务,快递100根据时间范围拆分出多个售后订单获取的任务列表,返回任务列表给用户。后续快递100会根据任务列表获取售后订单信息,任务获取结束后会把获取结果推送到用户的回调地址中。 任务列表中,每个任务查询失败,隔5分钟后重试,连续3次重试都失败则会终止查询并且推送一条queryStatus=Abort的消息告知用户。

4.1 接口格式

POST application/x-www-form-urlencoded

4.2 请求地址

https://api.kuaidi100.com/ent/refundOrder/task

4.3 请求参数

请求参数(header)

名称类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body)

参数名称数据类型是否必填参数描述
keystring授权码,请申请企业版获取
signstring32位大写,签名,用于验证身份,按MD5 (param + key + secret)的顺序进行MD5加密,不需要加上“+”号
paramObject由其他参数拼接

param数据结构

参数名称数据类型是否必填参数描述
shopTypestring店铺类型,TAOBAO:淘宝,TOUTIAO:抖店。
shopIdstring店铺ID
orderStatusstring订单状态,WAIT_SELLER_AGREE:买家已经申请退款,等待卖家同意;WAIT_BUYER_RETURN_GOODS:卖家已经同意退款,等待买家退货; WAIT_SELLER_CONFIRM_GOODS:买家已经退货,等待卖家确认收货; SELLER_REFUSE_BUYER:卖家拒绝退款; CLOSED:退款关闭; SUCCESS:退款成功
updateAtMinstring订单更新的最小时间,格式:yyyy-MM-dd HH:mm:ss
updateAtMaxstring订单更新的最大时间,格式:yyyy-MM-dd HH:mm:ss
callbackUrlstring回调地址,默认仅支持http
saltstring回调参数sign的加密参数,非空时回调才会有sign参数

4.4 返回结果

字段类型说明备注
resultboolean提交结果true表示成功
returnCodenumber返回编码
messagestring返回报文描述
dataobject业务数据

data数据结构

字段类型说明备注
totalnumber任务总数
tasksarray[object]任务类别

tasks数据结构

字段类型说明
taskIdstring任务编码
updateAtMinstring订单更新的最小时间,格式:yyyy-MM-dd HH:mm:ss
updateAtMaxstring订单更新的最大时间,格式:yyyy-MM-dd HH:mm:ss

4.5 成功响应结果示例


{
    "result": true,
    "returnCode": 200,
    "message": "SUCCESS",
    "data": {
        "total": 2,
        "tasks": [
            {
                "taskId": "61a8b60a9ac14514bd854318ac9a53ab",
                "updateAtMin": "2021-11-12 16:00:00",
                "updateAtMax": "2021-11-12 16:30:00"
            },
            {
                "taskId": "94261f0d24c54c34a6552584a0dd4197",
                "updateAtMin": "2021-11-12 16:30:00",
                "updateAtMax": "2021-11-12 17:00:00"
            }
        ]
    }
}
     

五、售后(退货)订单获取结果推送接口

用户提交订单获取任务的时候,使用到callbackUrl才会有获取结果推送。 每条消息推送用户接收和保存成功后,应该返回这样的响应报文:{"result":true,"returnCode":200,"message":"成功"},我方根据result等于true作为推送成功标识,其他均为推送失败。推送失败会隔半小时后重推,连续3次重推都失败则放弃该条消息的推送。任务列表中,每个任务查询失败,隔5分钟后重试,连续3次重试都失败则会终止查询并且推送一条queryStatus=Abort的消息告知用户。

5.1 接口格式

POST application/x-www-form-urlencoded

5.2 请求地址

由贵司在提交售后(退货)订单获取任务请求中通过callbackUrl字段提供

5.3 请求参数

请求参数(header)

名称类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body)

参数名称数据类型是否必填参数描述
signstring32位大写,提交订单获取任务salt非空时才会有该参数。签名,用于验证身份,按MD5 (param + salt)的顺序进行MD5加密,不需要加上“+”号
paramObject由其他参数拼接

param数据结构

参数名称数据类型参数描述
taskIdstring任务ID
queryStatusstring查询状态,Fail:查询失败;Empty:查无结果;Success:查询成功;Abort:终止,连续多次查询都失败
reasonstring订单获取不到的原因
ordersarray[object]订单列表

orders数据结构

参数名称数据类型参数描述
shopTypestring店铺类型,TAOBAO:淘宝,TOUTIAO:抖店。
shopIdstring店铺ID
shopNamestring店铺名称
refundNostring售后单号
refundTypeInteger售后类型,1:仅退款;2:退货退款
refundStatusstring退款状态,WAIT_SELLER_AGREE:买家已经申请退款,等待卖家同意;WAIT_BUYER_RETURN_GOODS:卖家已经同意退款,等待买家退货; WAIT_SELLER_CONFIRM_GOODS:买家已经退货,等待卖家确认收货; SELLER_REFUSE_BUYER:卖家拒绝退款; CLOSED:退款关闭; SUCCESS:退款成功
orderNostring订单号
goodsNamestring商品名称
goodsNostring商品编码
refundNumsInteger退货数量
refundAmountBigDecimal退货金额
expressCompanystring售后快递公司
refundWaybillnostring售后快递单号
applyTimestring售后申请时间,格式:yyyy-MM-dd HH:mm:ss
modifiedTimestring售后更新时间,格式:yyyy-MM-dd HH:mm:ss

5.4 返回结果

字段类型说明备注
resultboolean提交结果true表示成功,否则隔半小时重推,连续3次重推失败则放弃该消息推送
returnCodenumber返回编码
messagestring返回报文描述

5.5 查询无结果的回调param参数示例


{
	"taskId": "bb8122cb5a3f48c9be2724e7f3fb2813",
	"queryStatus": "Empty",
	"reason": "查询无结果",
	"orders": []
}
     

5.6 查询有记录的回调param参数示例


{
	"taskId": "f67c84bbc1d6462b836be888086a86c0",
	"queryStatus": "Success",
	"reason": null,
	"orders": [{
		"shopType": "TOUTIAO",
		"shopName": "官方旗舰店",
		"shopId": "12222",
		"refundNo": "111111xxaa",
		"refundType": 1,
		"refundStatus": "SUCCESS",
		"applyReason": "7天无理由退款",
		"orderNo": "4951640848941944689",
		"goodsName": "保湿身体婴儿有机身体乳500ML",
		"goodsNo": "355691792222",
		"refundNums": 1,
		"refundAmount": 109,
		"expressCompany": "",
		"refundWaybillno": "",
		"applyTime": "2022-07-11 19:47:50",
		"modifiedTime": "2022-07-12 09:11:27"
	}]
}
     

六、快递单号回传及订单发货接口

回传快递公司和快递单号给电商平台,并且修改订单状态为已发货状态。

6.1 接口格式

POST application/x-www-form-urlencoded

6.2 请求地址

https://api.kuaidi100.com/ent/logistics/send

6.3 请求参数

请求参数

参数名称数据类型是否必填参数描述
keystring授权码,请申请企业版获取
signstring32位大写,签名,用于验证身份,按MD5 (param + key + secret)的顺序进行MD5加密,不需要加上“+”号
paramObject业务级参数

param数据结构

参数名称数据类型是否必填参数描述
shopTypestring店铺类型,TAOBAO:淘宝,JINGDONG:京东,TOUTIAO:抖店,PINDUODUO:拼多多,KUAISHOU:快手 ,KUAITUANTUAN:快团团, DINGXIANG:丁香医生 ,WEIPINHUI:唯品会,YOUZAN:有赞,WEIDIAN:微店,SHIPINHAO:视频号小店,XIAOHONGSHU:小红书。
shopIdstring店铺ID
orderNumstring订单号,需要填写正确,否则会被电商平台的风控系统拦截
kuaidiComstring快递公司编码,需要填写正确,否则会被电商平台的风控系统拦截,编码请查看参数字典
kuaidiNumstring快递单号,需要填写正确,否则会被电商平台的风控系统拦截
subOrderNumsstring需要拆单发货的子订单集合,针对的是一笔交易下有多个子订单需要分开发货的场景;1次可传人多个子订单号,子订单间用英文逗号隔开;为空表示不做拆单发货(当前仅支持淘宝店铺类型)

6.4 返回结果

字段类型说明备注
resultboolean提交结果true表示成功
returnCodenumber返回编码
messagestring返回报文描述

6.5 返回结果示例


{
	"result": true,
	"returnCode": 200,
	"message": "SUCCESS"

}
     

七、 信息代码含义

信息代码信息内容描述原因及建议处理方式
200成功成功
101请求格式错误请求为post方式的application/x-www-form-urlencoded,而不是application/json,请勿用错格式提交参数
102签名验证失败32位大写,按MD5 (param + key + secret)的顺序进行MD5加密,不需要加上“+”号,secret在授权邮件里面有。注意加密的param参数值必须要和请求提交的param值一致(包括param里面属性字段的顺序)
103缺少必填参数根据文档补充必填参数的赋值
104参数错误根据文档修改参数值
401KEY过期没有可用单量,账号需要充值再使用
402客户不存在账号错误,请检查账号信息是否有误
500系统繁忙,请稍后再试快递100的服务器出现间歇或临时性异常,请联系快递100排查原因
60101暂不支持该店铺类型检查店铺类型是否填写有误
60102店铺授权错误获取店铺授权信息失败,请联系快递100排查原因
60103店铺未授权,请授权后再调用店铺未授权或者授权已过期,请重新授权
60104店铺授权已过期,请重新授权后再调用店铺授权已过期,请重新授权
60201时间范围过大,请调整时间范围重试
60202时间范围错误,请调整时间范围重试