首页 /接口文档 /正文/

14：订单状态回调

2021年11月05日

订单状态回调

接口说明：
1：当订单状态发生变化时，会回调账号配置的地址（账户中心->应用中心->回调URL：NotifyUrl）来通知订单状态的变化。
2：回调请求方式为POST，请求格式为application/json，编码utf-8。
3：状态（status）有回退的情况，待取货（已就位：30）可能回退到派单中（转单改派中：20）的状态，子状态（subStatus）以后可能会扩展。
4：回调返回的格式必须是{"status":200,"msg":"","data":null}格式，当status为200表示回调成功，否则，回调失败。当回调失败时会进行重试，当状态流转到下一状态不再重试，最多重试五次。
5：新增callbackEvent和modifyAddressSuccess两个字段，用于区分普通订单状态回调和修改地址结果回调。
  • 回调参数说明
参数 类型/是否必传 字段描述 示例
callbackEvent String/YES 回调事件类型，详见下方callbackEvent枚举 ORDER_STATUS_CALLBACK
issOrderNo String(20)/YES 闪送订单号 TDH2021101514763986
orderNo String(30)/YES 第三方平台流水号 C1119A000013053981
status Integer(8)/YES 订单状态，参考下方订单状态枚举 20
statusDesc String(8)/YES 订单状态描述，参考下方订单状态枚举 派单中
subStatus Integer(8)/NO 订单子状态，参考下方订单状态枚举 1
subStatusDesc String(8)/NO 订单子状态描述，参考下方订单状态枚举 派单中
pickupPassword String(8)/NO 取件密码，计费接口中pickupPwd传1时，下单后，订单会生成取件码
deliveryPassword String(8)/NO 收件密码，骑手取件后生成
deductAmount Integer(8)/NO 扣款金额，单位：分 0
abortType Integer(8)/NO 取消发起人，详见下方枚举 1
punishType Integer(8)/NO 取消责任人，详见下方枚举 1
abortReason String(64)/NO 取消原因 客户主动取消订单
courier Object/NO 闪送员信息
sendBackFee Integer(8)/YES 送回费，单位：分 0
drawback Integer(8)/YES 退款金额，单位：分 0
modifyAddressSuccess Boolean/YES 修改地址是否成功，仅当callbackEvent为MODIFY_ADDRESS_RESULT_CALLBACK时需要重点关注 true
  • courier说明
参数 类型/是否必传 说明 示例
latitude String(20)/NO 闪送员位置纬度（百度坐标系） 40.055091
longitude String(20)/NO 闪送员位置经度（百度坐标系） 116.289263
gcj02Lat String(20)/NO 闪送员位置纬度（高德坐标系） 40.055091
gcj02Lng String(20)/NO 闪送员位置经度（高德坐标系） 116.289263
name String(20)/YES 闪送员姓名 韩师傅
mobile String(20)/YES 闪送员手机号 19000000000
time String(24)/YES 闪送员位置所处的当前时间 2021-10-15 14:11:44
type Integer(8)/NO 字段弃用，可忽略 1
orderCount Integer(8)/NO 闪送员服务总次数 4
headIcon String(100)/NO 闪送员头像
id String(20)/NO 骑手id SSBJ000000001
blacklisted Integer(8)/NO 字段弃用，可忽略 0
deliveryProcessTrail Object[]/NO 配送过程轨迹列表（百度坐标系）
gcj02Trail Object[]/NO 配送过程轨迹列表（高德坐标系）
estimateDeliveryTimeTip String(100)/NO 预计送达时间文案，闪送员未接单或者订单终态，该值为空 227米,预计1分钟上门
  • deliveryProcessTrail说明
参数 类型/是否必传 说明 示例
longitude String(20)/YES 闪送员位置经度（百度坐标系） 116.289263
latitude String(20)/YES 闪送员位置纬度（百度坐标系） 40.055091
datetime String(24)/YES 闪送员位置所处的当前时间 2021-10-14 13:30:31
  • gcj02Trail说明
参数 类型/是否必传 说明 示例
gcj02Lng String(20)/YES 闪送员位置经度（高德坐标系） 116.289993
gcj02Lat String(20)/YES 闪送员位置纬度（高德坐标系） 40.066191
datetime String(24)/YES 闪送员位置所处的当前时间 2021-11-01 13:36:24
  • callbackEvent枚举
枚举值 说明
ORDER_STATUS_CALLBACK 订单状态回调，表示普通订单状态变化
MODIFY_ADDRESS_RESULT_CALLBACK 修改地址结果回调，表示取件后修改地址已有处理结果
  • modifyAddressSuccess说明
取值 说明
true 修改地址成功，闪送员确认按照新地址继续配送
false 修改地址未成功。普通订单状态回调中该字段默认也可能为false，需结合callbackEvent判断
  • 订单状态枚举
status：订单状态 statusDesc：状态描述 说明
20 派单中（转单改派中） 商户已经支付，订单分配给配送员（subStatus为1，表示派单中；subStatus为2，表示转单改派中）
30 待取货（已就位） 配送员已经接单（subStatus为1，表示待取货；subStatus为2，表示已就位）
40 闪送中（申请取消中、物品送回中、取消单客服介入中） 已经取件，配送中（subStatus为1，表示闪送中；subStatus为2，申请取消中；subStatus为3，物品送回中；subStatus为4，取消单客服介入中）
50 已完成（已退款） 已经配送完成（subStatus为1：已完成；subStatus为2：已退款）
60 已取消 已经取消订单
  • abortType枚举
类型 描述
1 客户发起取消
3 闪送员发起取消
10 系统自动发起取消
  • punishType枚举
类型 描述
1 因客户
2 因服务
3 因闪送员
10 因系统自动取消
99 因其它
  • 派单中参数示例
{
    "callbackEvent": "ORDER_STATUS_CALLBACK",
    "issOrderNo": "TDH2021101514763986",
    "orderNo": "C1119A000013053981",
    "status": 20,
    "statusDesc": "派单中",
    "subStatus": 1,
    "subStatusDesc": "派单中",
    "drawback": 0,
    "sendBackFee": 0,
    "modifyAddressSuccess": false
}
  • 待取货参数示例
{
    "callbackEvent": "ORDER_STATUS_CALLBACK",
    "issOrderNo": "TDH2021101514763986",
    "orderNo": "C1119A000013053981",
    "status": 30,
    "statusDesc": "待取货",
    "subStatus": 1,
    "subStatusDesc": "待取货",
    "drawback": 0,
    "sendBackFee": 0,
    "deliveryPassword": "",
    "pickupPassword": "",
    "modifyAddressSuccess": false,
    "courier": {
        "latitude": "40.055091",
        "longitude": "116.289263",
        "name": "韩师傅",
        "mobile": "19000000000",
        "time": "2021-10-15 14:11:44",
        "type": 1,
        "orderCount": 4,
        "headIcon": "",
        "id": "SSBJ000000001",
        "blacklisted": 0,
        "deliveryProcessTrail": [
            {
                "datetime": "2021-10-15 12:11:44",
                "latitude": 40.066191,
                "longitude": 116.289993
            },
            {
                "datetime": "2021-10-15 13:11:44",
                "latitude": 40.067591,
                "longitude": 116.297363
            },
            {
                "datetime": "2021-10-15 14:11:44",
                "latitude": 40.155091,
                "longitude": 116.399263
            }
        ],
        "estimateDeliveryTimeTip": "227米,预计1分钟上门"
    }
}
  • 取消参数示例
{
    "callbackEvent": "ORDER_STATUS_CALLBACK",
    "issOrderNo": "TDH2021101414286533",
    "orderNo": "C1119A000013053981",
    "status": 60,
    "statusDesc": "已取消",
    "deductAmount": 0,
    "drawback": 0,
    "sendBackFee": 0,
    "abortType": 1,
    "punishType": 1,
    "abortReason": "客户主动取消订单",
    "modifyAddressSuccess": false
}
  • 修改地址结果回调示例
{
    "callbackEvent": "MODIFY_ADDRESS_RESULT_CALLBACK",
    "issOrderNo": "TDH2021101514763986",
    "orderNo": "C1119A000013053981",
    "status": 40,
    "statusDesc": "闪送中",
    "subStatus": 1,
    "subStatusDesc": "闪送中",
    "drawback": 0,
    "sendBackFee": 0,
    "deliveryPassword": "",
    "pickupPassword": "",
    "modifyAddressSuccess": true,
    "courier": {
        "latitude": "40.055091",
        "longitude": "116.289263",
        "name": "韩师傅",
        "mobile": "19000000000",
        "time": "2021-10-15 14:11:44",
        "orderCount": 4,
        "id": "SSBJ000000001",
        "estimateDeliveryTimeTip": "227米,预计1分钟送达"
    }
}
  • 接口注意点
1、callbackEvent用于判断回调类型，建议接入方优先根据该字段区分处理逻辑；
2、callbackEvent=ORDER_STATUS_CALLBACK时，按原订单状态回调逻辑处理；
3、callbackEvent=MODIFY_ADDRESS_RESULT_CALLBACK时，表示本次回调为修改地址结果通知；
4、modifyAddressSuccess=true表示修改地址成功；
5、modifyAddressSuccess=false不一定表示修改地址失败，普通订单状态回调中该字段默认也可能为false，需结合callbackEvent一起判断；
6、为了兼容历史回调，接入方解析时建议允许新增字段，不要因未知字段导致反序列化失败。
  • 回调响应示例
{
    "status": 200,
    "msg": "",
    "data": null
}
关键词：