文档中心
一、同城配送下单 二、下单回调接口 API调试工具

同城配送下单技术文档

一、同城配送下单

选择快递公司进行下单。

1.1 接口格式

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

1.2 请求地址

https://order.kuaidi100.com/sameCity/order

请求参数:

参数名是否必填类型说明
methodstring业务类型(默认:order)
keystring授权码,请到快递100页面申请企业版接口获取
signstring32位大写,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号。secret在企业管理后台获取
tstring时间戳如:1576123932000
paramparam由其他字段拼接

param数据结构:

参数名是否必填类型说明
comstring快递公司的编码,一律用小写字母,见《快递公司编码》
recManNamestring收件人姓名
recManMobilestring收件人的手机号,手机号和电话号二者其一必填
recManPrintAddrstring收件人所在完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园
sendManNamestring寄件人姓名
sendManMobilestring寄件人的手机号,手机号和电话号二者其一必填
sendManPrintAddrstring寄件人所在的完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10
callbackUrlstringcallBackUrl订单信息回调地址
orderTypestring订单类型 0:立即单(默认) 1:预约单
pickupTimestring预约取件时间(2020-02-02 22:00:00),预约件必填
weightdouble物品总重量KG,不需要带单位,例:1.5
serviceTypestring快递业务服务类型,例:文件广告;对照参数字典
remarkstring备注
saltstring签名用随机字符串
orderSourceNoString物品来源单号(比如美团、饿了么订单方便骑手取货)
orderSourceTypeString物品来源(比如美团、饿了么订单方便骑手取货)
storeIdString店铺id(对应快递公司提供的店铺标识,注意事项可参考常见问题说明
additionFeeInt小费,单位分,不需要带单位,例:1000
priceInt商品价格,单位分,不需要带单位,例:1000
partnerIdString服务商授权信息,对照参数字典
partnerKeyString服务商授权信息,对照参数字典
goodsarray商品详情(强烈建议提供,方便骑手在取货时确认货品信息)

goods数据结构:

参数名是否必填类型说明
nameString商品名称
priceInt商品价格,单位:分
countInt商品数量
unitString商品单位

1.3 返回结果

字段类型说明备注
resultboolean提交结果true提交成功,false失败
returnCodestring返回编码
messagestring返回报文描述
datadata

data数据结构

字段类型说明备注
taskIdstring任务ID
comstring快递公司的编码
orderIdstring订单ID
feeint费用,单位:分
distanceint距离,单位:公里
kuaidiNumstring快递公司订单号

1.4 提供数据内容

请求参数示例

method = order
key = *******
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
 	"com": "kfw",
 	"recManName": "测试",
 	"recManMobile": "13800138000",
 	"recManPrintAddr": "深圳市南山区伟易达大夏",
 	"sendManName": "小张",
 	"sendManMobile": "13800138000",
 	"sendManPrintAddr": "深圳市南山区高新南地铁站b口",
 	"serviceType": "火锅",
 	"weight": 1.00,
  	"remark": "测试订单,待会取消",
 	"salt": "123",
 	"callBackUrl": "http://www.baiud.com",
 	"pickupTime": "",
 	"orderSourceNo": "168168168",
 	"orderSourceType": "美团",
 	"storeId": "106396",
 	"additionFee": 1000,
 	"partnerId": "155555555",
 	"partnerKey": "1111111111"
}

返回结果示例

{
    "returnCode": "200",
    "result": true,
    "message": "提交成功",
    "data": {
        "taskId": "13F873760DCB4CF28D666A13FDE6B31A",
        "com": "kfw",
        "orderId": "1000090",
        "fee": 5000,
        "distance": 1000,
        "kuaidiNum": "KFWZS1476131277"
    }
} 

1.5 信息代码含义

信息代码信息内容描述原因及建议处理方式
200成功成功
400参数错误等提交数据不完整, 检查提交的格式是否为x-www-form-urlencoded的post格式
500服务器错误快递100的服务器出理间隙或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数没有按照文档规定填写等,也会报此错误
501重复提交快递100的服务器出理间隙或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数没有按照文档规定填写等,也会报此错误
503验证签名失败请检查加密方式,param + t + key+ secret 的顺序进行MD5加密,加密后字符串转大写
601key已过期没有可用单量,账号需要充值使用

二、下单回调接口

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

2.1 接口格式

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

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

2.2 请求地址

授权时贵司填入的callbackUrl

请求参数:

字段类型说明备注
taskIdString任务id
signString签名下单时填写了salt时会带sign md5(param+salt)
paramparam参数主体

param数据结构:

参数名是否必填类型说明
kuaidicomstring快递公司的编码,一律用小写字母,见《快递公司编码》,选填。
kuaidinumstring快递单号,单号的最大长度是32个字符。
messagestring状态描述
orderIdstring平台订单ID
statusstring订单状态0-下单成功 1-已接单 10-已取货 13-已签收 9-用户主动取消 99-订单已取消
courierNamestring快递员姓名
courierMobilestring快递员电话
weightstring重量
freightstring运费,单位:分

2.3 返回结果

字段说明备注
result提交结果true提交成功,false失败
returnCode返回编码
message返回报文描述

2.4 提供数据内容

入参param例子

{
    "courierMobile": "13800138000",
    "courierName": "G师傅",
    "kuaidiCom": "kfw",
    "kuaidiNum": "KFWZS1476130507",
    "message": "订单已取消",
    "orderId": "1000086",
    "status": 99
}

要求返回结果

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

2.4 推送响应报文及错误码解释

字段名称字段含义
resulttrue表示成功,false表示失败。如果提交回调接口的地址失败,30分钟后重新回调,3次仍旧失败的,自动放弃
returnCode200: 提交成功 500: 服务器错误 其他错误请自行定义
message返回的提示