需要实现的接口
- 回调接口是指第三方提供的一个 API 请求入口,此 API 接口的请求和响应需要按照以下文档进行开发
- 所有参数区分大小写
- 友朋采用 HTTP POST Content-Type:application/x-www-form-urlencoded 方式请求第三方回调接口
- 所有参数区分大小写
请求参数
| 参数名称 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| method | string | Y | 业务方法,以下每个接口表示每个业务方法 (字母小写) |
| biz_content | string | Y | 业务参数 json 字符串 |
| timestamp | int | Y | unix 时间戳到秒 |
| sign_type | string | Y | 签名方式,md5 (小写) |
| sign | string | Y | 签名(小写) |
返回结果
| 参数名称 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| error_code | int | 是 | 错误代码 =0 正常(操作成功,接口调用成功) !=0 异常错误 |
| error_msg | string | 是 | 错误描述 |
| data | object | 是 | 返回业务内容 |
签名与校验签名
- 除 sign 参数外所有参数必须参与签名,参数以文本方式字典排序,排序后使用 key=value&key=value 方式拼接字符串
- 得到字符串 tmpString
- 签名:md5(tmpString+"&"+appSecret) 得出的结果转换为小写字母
- appSecret 由品牌商在后台配置(此文档里接口 appSecret 用的是支付配置中的签名秘钥，非支付业务接口签名均用开放平台 appSecret)
售中回调
通知接口 cabinet.order.vi.result.notify
接口说明:
- 识别结果,第三方需要同步返回结果
- 此接口是用于当自取柜开门后,识别商品回调 注意:商品识别异常时不会发起通知，需要运营商自行上运营商平台处理异常订单,完成后会发起回调。
业务参数:
| 参数名称 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| ReceiptNo | string | Y | 友朋订单号 |
| Products | array | Y | 商品列表 |
Products: [{
"Qty": 1,
"BarCode": "6925303723910",
"Name": "\u7edf\u4e00\u51b0\u7ea2\u83361L",
"Price": 1,
"CostPrice": 0,
"TotalPrice": 1
}]
第三方返回要求示例
//成功
{
"error_code": 0, //业务逻辑成功返回0 不成功返回非0
"error_msg": "SUCCESS",
"data": {
}
}
//失败
{
"error_code": -1,
"error_msg": "业务失败原因的描述",
}
售后回调
通知接口 cabinet.order.product.modify
接口说明:
- 售后订单修改订单商品后通知
业务参数:
| 参数名称 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| ReceiptNo | string | Y | 友朋原订单号 |
| originalOrderRow | object | Y | 原订单 |
| newOrderRow | object | Y | 调整后订单 |
| PaySuccessNotifyUrl | string | Y | 调整后的订单支付成功后回调链接 |
originalOrderRow
{
"CID": "5f519ebf4405f00010750ef5", // 设备ID
"OID": "5db266d87bd4810010954b0e", // 运营商ID
"BID": "5d254c16683ead0011492950", // 品牌商ID
"UserID": "5fcf260311ab6d0010c8b20e", // 用户ID
"OpenID": "13715352279", // 平台的OpenID, 如小程序的AppID,支付宝
"PayType": 99, // 支付方式 0=未知 1=微信(支付分) 2=支付宝 201=品牌商微信代收 99=第三方支付
"PayExtend": {}, // 支付商户的扩展
"ClientIPAddress": "127.0.0.1", // 客户端ip
"ScenesType": 0, // 支付场景 0=扫码支付 1=友朋刷脸 2=微信刷脸 3=支付宝刷脸 4=密码购
"ServiceStatus": 2, // 服务状态 0=未开始服务 1=服务中 2=服务结束 (通过回调来更新) 3=价格计算完成 4=价格已确认
"TradeNo": "9927749809022", // 第三方交易流水号
"ThirdpartyAppID": "106267743528", // 开放平台调用的AppID
"ReceiptNo": "OD210122112202688925", // 单据编号 唯一
"TradeRawData": { // 交易具体信息
"no": 1
},
"PayTime": 1611285601, // 支付时间
"Products": [// 商品信息
{
"Qty": 1, // 数量
"BarCode": "6902538004045",
"Name": "脉动青柠口味瓶装600ml",
"Price": 2, // 单价 单位:分
"CostPrice": 0, // 成本 单位:分
"TotalPrice": 2 // 总价 单位:分
}
],
"DoorStatus": 0, // 开门状态 -1=没有开门 0=已关门 1=已开门
"TradeStatus": 1, // 交易状态 0=等待结算 1=已支付成功 2=已退款成功 -1=已取消订单
"Price": 0, // 实收金额 单位分
"IsSuspicious": 0, // 订单是否可疑
"RefundsProducts": [], // 退款商品
"RefundsPrice": 0, // 退款金额 单位分
"RefundsRawData": {}, // 退款具体信息
"UserRefundsStatus": 1, // 用户退款申请状态 0=未申请 1=申请退款 -1=拒绝退款 2=通过退款
"RefundsType": 1, // 退款处理方式 => 1=拒绝退款 2=仅退款 3=补扣新订单、原订单退款 4=补扣新订单支付成功后，原订单退款
"UserRefundsTime": 1611285756, // 用户退款申请时间
"UserRefundsReason": "REFUNDS_REASON_PRODUCT_NOT_MATCH", // 用户退款原因 REFUNDS_REASON_PRODUCT_VI_MORE = 多识别商品 REFUNDS_REASON_PRODUCT_EXPIRED = 商品已过期 REFUNDS_REASON_PRODUCT_NOT_MATCH = 识别错商品 REFUNDS_REASON_PRODUCT_VI_LESS = 算漏商品 REFUNDS_REASON_OFFLINE_PAYMENT = 线下收款 REFUNDS_REASON_WECHAT_COMPLAINT = 微信投诉
"UserRefundsRemarks": "20e10122001", // 用户退款备注
"UserRefundsImageUrl": [], // 用户退款上传的图片URL
"UserRefundsMobile": "13715352279", // 用户退款时手机号码
"UserOrderInfo": "", // 用户对于 => 异常订单的 => 订单信息补充
"RefundsTime": 0, // 退款时间
"OpAccountID": "", // 退款操作的AccountID
"OpRefundsRemarks": "", // 运营商 => 退款处理备注
"DealResultStatus": 0, // 运营商 => 处理结果 0=未知 1=本单未产生消费 2=修改订单明细结算 3=恶意行为罚款
"DealTime": 0, // 运营商 => 处理时间
"DealRemarks": "", // 运营商 => 处理意见
"SOpAccountID": "", // 异常订单操作的AccountID
"CompleteStatus": null, // 订单完成状态 SUCCESS=完成
"CreateAt": 1611285723, // 创建时间
"UpdatedAt": 1611285756, // 更新时间
"id": "600a44db524b3420fc218c2c" // 订单ID
}
newOrderRow
{
"CID": "5f519ebf4405f00010750ef5", // 设备ID
"OID": "5db266d87bd4810010954b0e", // 运营商ID
"BID": "5d254c16683ead0011492950", // 品牌商ID
"UserID": "5fcf260311ab6d0010c8b20e", // 用户ID
"OpenID": "13715352279", // 平台的OpenID, 如小程序的AppID,支付宝
"PayType": 99, // 支付方式 0=未知 1=微信(支付分) 2=支付宝 201=品牌商微信代收 99=第三方支付
"PayExtend": {}, // 支付商户的扩展
"ClientIPAddress": "127.0.0.1", // 客户端ip
"ScenesType": 0, // 支付场景 0=扫码支付 1=友朋刷脸 2=微信刷脸 3=支付宝刷脸 4=密码购
"ServiceStatus": 2, // 服务状态 0=未开始服务 1=服务中 2=服务结束 (通过回调来更新) 3=价格计算完成 4=价格已确认
"TradeNo": "9927749809022", // 第三方交易流水号
"ThirdpartyAppID": "106267743528", // 开放平台调用的AppID
"ReceiptNo": "OD210122112202688925", // 单据编号 唯一
"TradeRawData": { // 交易具体信息
"no": 1
},
"PayTime": 1611285601, // 支付时间
"Products": [// 商品信息
{
"Qty": 1, // 数量
"BarCode": "6902538004045",
"Name": "脉动青柠口味瓶装600ml",
"Price": 2, // 单价 单位:分
"CostPrice": 0, // 成本 单位:分
"TotalPrice": 2 // 总价 单位:分
}
],
"DoorStatus": 0, // 开门状态 -1=没有开门 0=已关门 1=已开门
"TradeStatus": 1, // 交易状态 0=等待结算 1=已支付成功 2=已退款成功 -1=已取消订单
"Price": 0, // 实收金额 单位分
"IsSuspicious": 0, // 订单是否可疑
"RefundsProducts": [], // 退款商品
"RefundsPrice": 0, // 退款金额 单位分
"RefundsRawData": {}, // 退款具体信息
"UserRefundsStatus": 1, // 用户退款申请状态 0=未申请 1=申请退款 -1=拒绝退款 2=通过退款
"UserRefundsTime": 1611285756, // 用户退款申请时间
"UserRefundsReason": "REFUNDS_REASON_PRODUCT_NOT_MATCH", // 用户退款原因 REFUNDS_REASON_PRODUCT_VI_MORE = 多识别商品 REFUNDS_REASON_PRODUCT_EXPIRED = 商品已过期 REFUNDS_REASON_PRODUCT_NOT_MATCH = 识别错商品 REFUNDS_REASON_PRODUCT_VI_LESS = 算漏商品 REFUNDS_REASON_OFFLINE_PAYMENT = 线下收款 REFUNDS_REASON_WECHAT_COMPLAINT = 微信投诉
"UserRefundsRemarks": "20210122001", // 用户退款备注
"UserRefundsImageUrl": [], // 用户退款上传的图片URL
"UserRefundsMobile": "13715352279", // 用户退款时手机号码
"UserOrderInfo": "", // 用户对于 => 异常订单的 => 订单信息补充
"RefundsTime": 0, // 退款时间
"OpAccountID": "", // 退款操作的AccountID
"OpRefundsRemarks": "", // 运营商 => 退款处理备注
"DealResultStatus": 0, // 运营商 => 处理结果 0=未知 1=本单未产生消费 2=修改订单明细结算 3=恶意行为罚款
"DealTime": 0, // 运营商 => 处理时间
"DealRemarks": "", // 运营商 => 处理意见
"SOpAccountID": "", // 异常订单操作的AccountID
"CompleteStatus": null, // 订单完成状态 SUCCESS=完成
"CreateAt": 1611285723, // 创建时间
"UpdatedAt": 1611285756, // 更新时间
"id": "600a44db524b3420fc218c2c" // 订单ID
}
第三方返回要求示例
//业务成功
{
"error_code": 0, //业务逻辑成功返回0 不成功返回非0
"error_msg": "SUCCESS"
}
//业务失败
{
"error_code": -1,
"error_msg": "业务失败原因的描述",
}
通知接口 cabinet.order.refunds.result.notify
接口说明:
- 退款结果通知
- 当第三方订单变为退款成功或拒绝退款时会调用此接口通知第三方
业务参数:
| 参数名称 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| ReceiptNo | string | Y | 订单交易编号 |
| UserRefundsStatus | Number | Y | 退款状态 -1=拒绝退款 2=通过退款 |
| OpRefundsRemarks | string | Y | 审核备注 |
| RefundsPrice | Number | N | 退款金额 单位 |
| RefundsTime | Number | N | 退款时间 |
第三方返回要求示例
//业务成功
{
"error_code": 0, //业务逻辑成功返回0 不成功返回非0
"error_msg": "SUCCESS"
}
//业务失败
{
"error_code": -1,
"error_msg": "业务失败原因的描述",
}