业务异步通知#
使用背景：运营商在友朋开放平台创建开发者appid 并设置了业务回调地址，开发者接收友朋异步通知所需实现的接口。
具体根据所实际需要的业务场景来接收友朋的异步通知
1. 使用说明#
1、触发通知条件后，友朋主动调用接口通知给到开发者
2、需要在运营商后台>营销中心>开放平台>开发者中配置回调地址和勾选相应的异步通知接口【免费】
3、如果多个开发者都配置了地址，则所有的地址都会收到接口通知
4、回调地址即通知的接口地址， 根据 method 不同做不同的业务处理
5、所有接口统一采用 https post 方式调用
1.1 开发者配置回调地址#
1.2 异步通知请求方式#
Method: POST
Content-Type: application/x-www-form-urlencoded
1.3 公共请求参数#
| 参数名称 | 类型 | 是否必须 | 描述 | 示例值 |
|---|
| appid | string | Y | 运营商后台创建的 AppID | 930859529955 |
| method | string | Y | 接口名称 (字母小写) | eg: notify.activity.voucher.exchangecode |
| biz_content | string | Y | 业务参数 json 字符串 | |
| timestamp | int | Y | unix 时间戳到秒 | 1556943285 |
| sign_type | string | Y | 签名方式,md5 (小写) | md5 |
| sign | string | Y | 签名(小写) | 签名方式见下文 |
注意接收友朋异步通知没有 version参数及参与签名，和请求友朋API接口的参数及参与签名不完全一致。需按照上述请求参数接收和签名校验。
1.4 返回结果结构#
| 参数名称 | 类型 | 是否必须 | 说明 | 示例值 |
|---|
| error_code | int | 是 | 错误代码 =0 正常(操作成功,接口调用成功) !=0 异常错误 | 0 |
| error_msg | string | 是 | 错误描述 | ERR_SYSTEM |
| data | object | 是 | 返回业务内容 | {} |
1.5 签名#
除 sign 参数外所有参数必须参与签名,参数以文本方式字典排序,排序后使用 key=value&key=value 方式拼接字符串
签名:md5(tmpString+"&"+appSecret) 得出的结果转换为小写字母
1.6 开发者接收成果后返回给友朋#
{ error_code:0 , error_msg:"SUCCESS"}
1.7 友朋重试机制及开发者去重机制#
友朋回调开发者指定的URL，如开发者的接收接口没有返回指定结果，友朋将重试10次。请开发者确保接口稳定性。
当友朋异步通知开发者时，开发者需自行实现去重机制。
2. 异步事件通知#
开发者根据实际所需业务场景，接收友朋的异步通知后存档并自行处理内部系统逻辑,注意同步返回成果接收结果给友朋。
| 通知事件 method | 说明 |
|---|
| notify.cabinet.order.simple | 自取柜的订单用户完成支付后触发 |
| notify.cabinet.changed | 自取柜配置发生变化时触发 |
| notify.close.door | 前置条件：在调用[cabinet.open.door]接口后，友朋服务器收到机器关门后触发 |
| notify.consumer.order.simple | 售货机设备上报出货结果时触发 |
| notify.terminal.cargo.supplement | 售货机完成补货时触发 |
| notify.activity.voucher.exchangecode | 使用兑换码在售货机兑换成功并已出货的情况下触｜ |
| notify.depot.changed | 商品库存发生变化时触发，包含仓、人、机器 |
| notify.depot.pickup.return | 补货员将商品退货到仓库时触发 |
2.1 notify.cabinet.order.simple#
| 参数名称 | 类型 | 说明 |
|---|
| ReceiptNo | string | 订单交易编号 |
| CID | string | 自取柜设备 ID |
| PayTime | int | 支付时间 |
2.2 notify.cabinet.changed#
| 参数名称 | 类型 | 说明 |
|---|
| RequestID | string | 请求ID |
| Name | string | 设备名称 |
| DeviceCode | string | 设备编号 |
| Code | string | 生产编码 |
| EnableSell | boolean | 是否开启售卖，默认停止售卖 |
| SellStatus | integer | 设备售货状态，0=停止售货，1=正常售货，2=待投放 |
| OnlineStatus | integer | 设备在线状态，0=离线，1=在线 |
| Province | string | 省份 |
| City | string | 城市 |
| District | string | 区县 |
| ServicePhone | string | 客服电话 |
| ExtElectronicStatus | integer | 电源状态，0=断电，1=通电 |
| ReplenisherAccountID | string | 补货员id |
| CabinetCount | integer | 柜门数 |
| Location | array | 地理位置，包含经度和纬度 |
| CargoConfig | array object | 货道信息 |
"CargoConfig" 的详细信息，这是一个包含多个对象的数组，每个对象都有 "Row", "Col" 和 "BarCode" 的属性。| 参数名称 | 类型 | 说明 |
|---|
| Row | integer | 行号 |
| Col | integer | 列号 |
| BarCode | string | 条形码 |
2.3 notify.close.door#
| 参数名称 | 类型 | 说明 |
|---|
| Status | int | 1=机器有开门 2=机器没有开门 |
| ReceiptNo | string | 单号 |
| Msg | string | 消息文案 |
2.4 notify.consumer.order.simple#
| 参数名称 | 类型 | 说明 |
|---|
| ReceiptNo | string | 订单交易编号 |
| TID | string | 售货机设备 ID |
| ShipmentsStatus | int | 出货结果 |
| ShipmentsError | string | 失败原因 |
2.5 notify.terminal.cargo.supplement#
2.6 notify.activity.voucher.exchangecode#
| 参数名称 | 类型 | 说明 |
|---|
| VoucherID | string | 兑换码库 id |
| VoucherCode | string | 兑换码 |
| TID | string | 设备 ID |
| ReceiptNo | string | 订单号 |
| ShipmentsStatus | int | 出货状态 0=等待出货 1=出货成功 -1=出货失败 2=等待取货 3=无库存 等待取货 |
2.7 notify.depot.changed#
| 参数名称 | 类型 | 说明 |
|---|
| RequestID | string | 请求 id，用于多次请求下去重 |
| BizType | string | 库存变化类型 |
| BizID | string | 业务 ID |
| ReceiptNo | string | 业务单号 |
| Timestamp | int | 库存变化时间戳 |
| DepotID | string | 仓库 ID |
| AccountID | string | 补货员 ID |
| DeviceID | string | 设备 ID |
| ProductList | array | 商品列表 |
2.8 notify.depot.pickup.return#
| 参数名称 | 类型 | 说明 |
|---|
| RequestID | string | 请求 id，用于多次请求下去重 |
| BizID | string | 退货单 id |
| ReceiptNo | string | 退货单单号 |
| CreateReturnOrderAt | int | 创建退货单时间戳 |
| DepotID | string | 仓库 ID |
| AccountID | string | 补货员 ID |
| ProductList | array | 商品列表 |
