# IM红包后端接口API
[TOC]
## 1、接收支付宝异步通知接口
* 描述
用于处理支付宝异步通知；
* 请求
```
请求地址：mxm/api/v1/redpack/handleApNotify
请求方式：POST
请求类型：无
```
* params参数说明-JSON类型
```
{
// 支付宝操作流水号
operation_id=20171229517078765802
// 通知时间
notify_time=2017-12-29 14:36:32
// 支付宝操作订单号
auth_no=2017122910002001580293176770
// 通知状态
status=SUCCESS
// 签名类型
sign_type=RSA2
// 支付宝应用标识
auth_app_id=2017111709985890
// 编码
charset=UTF-8
// 平台订单号
out_order_no=e4f54153-5f24-4bc3-a653-19aafcdf0c81
// 支付宝用户标识
payee_user_id=2088702658098580
// 通知类型
notify_type=fund_auth_pay
// 支付宝操作类型
operation_type=PAY
// 接口版本，固定值
version=1.0
// 参数签名
sign=p//GD0wdHKjPUzJHcQDmSTRWJDRKQMFLC0IRrhzmwxIrfTb3YFnwi7KzPw+SpdQdOfcp3W2fnP/aUdB7GotCsyH/8/lx4jfns2k/7K770fyyGcTNF5Q7kj6Uyafs3woD5IiAON6wOWiXjbxE2tPBmYV0x7w8nH1O+x1tVZ9zyZ3drMeeTrX9sS9EHUSTAbQ51uHHLoOwWd4gVLKrCgGsvcb37BsTrirRmumu2CaVA0Og5Y9mJiy6vZJRH7Tt63rE3jhV9/K73ZLZB3g7BTMn2GbSbfk3Ep03TMY2RHXZyXQhxKUl/Bbj0bXyWruwg7l6OT5roYEjlww8kgJgBtEoUw==
// 操作金额
amount=0.02
// 交易创建时间
gmt_create=2017-12-29 14:36:32
// 支付宝用户账号
payee_logon_id=186****7081
// 平台流水号
out_request_no=e4f54153-5f24-4bc3-a653-19aafcdf0c81-1514529390773
// 支付宝应用标识
app_id=2017111709985890
// 通知标识
notify_id=140229b2671b6657d965e2d869402c7kh6
// 交易完成时间
gmt_trans=2017-12-29 14:36:32
}
```
* 方法返回
无
* 错误码
无
* 版本支持
xSimpleV4.0及以上
***
## 2、绑定支付宝账号接口
* 描述
绑定平台账号与支付宝账号；
* 请求
```
请求地址：mxm/api/v1/redpack/bindingAlipay
请求方式：POST
请求类型：
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| ---------- | ---- | ---- | ---- | --------- |
| apUserId | 是 | 字符串 | | 支付宝唯一用户标识 |
| apAuthCode | 是 | 字符串 | | 支付宝授权码 |
| appKey | 是 | 字符串 | | 应用唯一标识 |
| userId | 是 | 字符串 | | 用户唯一标识 |
| loginName | 否 | 字符串 | | 用户登录账号 |
| userName | 否 | 字符串 | | 用户名称 |
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 绑定失败时的提示信息 |
| data | JSON | | 无 |
* 错误码
无
* 参数示例
```
{
apAvatar //用户头像
apNickName //用户昵称
apUserId//支付宝用户id
}
```
* 版本支持
xSimpleV4.0及以上
***
## 3、发红包接口
* 描述
客户端点击发红包按钮，调用此接口传入基本参数；服务端补充完整的参数并进行参数签名返回给客户端；然后客户端根据返回的数据调用支付宝接口进行红包发送；
* 请求
```
请求地址：mxm/api/v1/redpack/sendRedPack
请求方式：POST
请求类型：
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| ----------- | ---- | ---- | ---- | -------------------------------- |
| appKey | 是 | 字符串 | | 应用唯一标识 |
| userId | 是 | 字符串 | | 发红包用户标识 |
| rp_type | 是 | 字符串 | | 红包类型：0为普通红包；1为群聊拼手气红包；2为群聊人均分配红包 |
| rp_param | 是 | JSON | | 红包基本参数 |
| biz_content | 是 | JSON | | 红包金额参数 |
* rp_param参数说明
```
{
"rp_count":7, // 数字、必选；红包发送个数
"rp_userId":"12", // 字符串、可选；单聊发红包接收者用户标识，当rp_type的值为0时，该参数必选
"rp_groupId":"123" // 字符串、可选；群聊发红包接收者群标识，当rp_type的值为1、2时，该参数必选
}
```
* biz_content参数说明
```
{
"amount":"0.10", // 字符串、必选；发送红包金额
"order_title":"测试发红包" // 字符串、可选；发送红包时的描述
}
```
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 网络请求失败时的提示信息 |
| data | JSON | | 接口返回数据，用户自定义 |
* data参数说明
```
{
// 签名串
sign = "N9jrLFCFHAsPBJbT%2FL6%2Bksf1yZB9n403FkSwTzbApAaLXrZrzQkac831%2BQIOGAv5AXbw32i4TZHeDuaU8o%2Bz547lhh1VCcN4cGSLOXN3SZjjY6MxMGuv9UUyv90skrtw1C8Re4R33T6dn2PpQBYg5rZnG9XQNTezpOO5YMeya1VVEJ2R9pGkquRHuNjew15%2BYX8BwoUY3y836CUIx2HA2yiUSe7s%2F1V5AdTVd5DtcVXacWyGqS7%2B55GOGLoqJdFXmUIhK6%2FwqOs3sbJFwIgKhTG3xuYpl24O1tWKtw%2Biuq1lr8NgKTLBljmtyKyvqkEWJvobvd38NO1WRCqnT7foaA%3D%3D";
// 签名参数
signStr = "appKey=123456789&app_id=2017111709985890&biz_content={\"order_title\":\"\U6d4b\U8bd5\U53d1\U7ea2\U5305\",\"amount\":\"0.10\",\"out_order_no\":\"df68acbf-5317-4f00-b6bc-72fc5d8b1d3a\",\"out_request_no\":\"df68acbf-5317-4f00-b6bc-72fc5d8b1d3a-1514533589175\"}&charset=UTF-8&format=JSON&method=alipay.fund.coupon.order.app.pay¬ify_url=http://app.coracle.com:10087/simple/notify.jsp&pay_timeout=30m&reqType=sendRedPack&rp_param={\"rp_groupId\":\"123\",\"rp_count\":7,\"rp_userId\":\"2\"}&rp_type=1&sign_type=RSA2×tamp=2017-12-29 15:46:29&userId=1&version=1.0";
// 平台操作授权订单号
orderNo = "0c95bd94-7f8c-45e1-a450-8349455e8100";
// 平台操作授权流水号
requestNo = "0c95bd94-7f8c-45e1-a450-8349455e8100-1514519300459";
}
```
* 错误码
无
* 参数示例
```
IOS : @{
@"appKey":@"ewewsdfds80349230",
@"userId":@"323",
@"rp_type":@"0",
@"rp_param":@{
@"rp_count":@1,
@"rp_userId":@"122"
},
@"biz_content":@{
@"amount":@"0.01",
@"order_title":@"测试发红包"
}
}
```
* 版本支持
xSimpleV4.0及以上
***
## 4、拆红包打款接口
* 描述
调用此接口可进行红包领取；
* 请求
```
请求地址：mxm/api/v1/redpack/receiveRedPack
请求方式：POST
请求类型：
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ---- | ------------------------------------- |
| userId | 是 | 字符串 | | 平台用户标识 |
| appKey | 是 | 字符串 | | 平台应用标识 |
| groupId | 是 | 字符串 | | 红包接收者群标识（群聊领红包，需传改红包发放的群ID） |
| apUserId | 是 | 字符串 | | 接收者支付宝用户标识 |
| apAuthNo | 是 | 字符串 | | 支付宝授权订单号（发红包成功后，通过查询红包发送状态接口返回的数据中获取） |
| rpType | 是 | 字符串 | | 红包类型 |
| rpId | 是 | 字符串 | | 红包标识 |
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 网络请求失败时的提示信息 |
| data | JSON | | 接口返回数据，用户自定义 |
* 错误码
无
* 版本支持
xSimpleV4.0及以上
***
## 5、红包退款接口
* 描述
用于平台主动调用退款接口，退回发红包用户账号
用户发红包后，支付宝默认是保留48小时，如果超时未领取或者部分未领取会自动退回发红包账号；
* 请求
```
请求地址：mxm/api/v1/redpack/refundRedPack
请求方式：POST
请求类型：
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ---- | -------- |
| userId | 是 | 字符串 | | 操作退款用户标识 |
| appKey | 是 | 字符串 | | 平台应用标识 |
| apAuthNo | 是 | 字符串 | | 支付宝授权订单号 |
| rpType | 是 | 字符串 | | 红包类型 |
| rpId | 是 | 字符串 | | 红包标识 |
| describe | 否 | 字符串 | | 退款原因 |
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 网络请求失败时的提示信息 |
| data | JSON | | 接口返回数据，用户自定义 |
* 错误码
无
* 版本支持
xSimpleV4.0及以上
***
## 6、查询红包发送状态接口
* 描述
调用此接口查询支付宝是否扣款成功；
* 请求
```
请求地址：mxm/api/v1/redpack/queryRedPackStatus
请求方式：POST
请求类型：
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| ------- | ---- | ---- | ---- | --------- |
| userId | 是 | 字符串 | | 平台用户标识 |
| appKey | 是 | 字符串 | | 平台应用标识 |
| orderNo | 是 | 字符串 | | 平台操作授权订单号 |
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 网络请求失败时的提示信息 |
| data | JSON | | 接口返回数据，用户自定义 |
* data参数说明
```
{
}
```
* 错误码
无
* 版本支持
xSimpleV4.0及以上
***
## 7、查询个人红包记录接口
* 描述
查询个人红包收发记录
* 请求
```
请求地址：mxm/api/v1/redpack/queryMyRedPackList
请求方式：POST
请求类型：
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ---- | ------------------ |
| userId | 是 | 字符串 | | 用户标识 |
| rpIsSend | 是 | 字符串 | | 是否发送红包;0为发红包；1为收红包 |
| year | 是 | 字符串 | 2018 | 查询年份 |
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 网络请求失败时的提示信息 |
| data | JSON | | 接口返回数据，用户自定义 |
* data参数说明
```
{ //收发红包记录
rpId // 红包标识
rpType // 红包类型；0为普通红包；1为群聊拼手气红包；2为群聊人均分配红包
rpAmount // 红包金额
rpTime // 红包收发时间
rpLuck // 红包手气最佳，多用在收红包列表中；0为一般，1为最佳；
rpDescribe // 红包描述
}
```
* 错误码
无
* 版本支持
xSimpleV4.0及以上
***
## 8、查询红包明细接口
* 描述
查询单个红包明细详情
* 请求
```
请求地址：mxm/api/v1/redpack/queryRedPackDetails
请求方式：POST
请求类型：contentType:”application/x-www-form-urlencoded”
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| ------- | ---- | ---- | ---- | ---- |
| rpId | 是 | 字符串 | | 红包标识 |
| orderNo | 是 | 字符串 | | 订单ID |
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 网络请求失败时的提示信息 |
| data | JSON | | 接口返回数据，用户自定义 |
* data参数说明
```
{
rpId // 红包标识
rpType // 红包类型
rpAmount // 红包金额
rpTime // 红包发送时间
rpDescribe // 红包描述
rpType // 红包类型；0为普通红包；1为群聊拼手气红包；2为群聊人均分配红包
apAuthNo // 支付宝授权订单号
apOperationNo // 支付宝资金操作流水号
luckFlag //1为手气最佳，0为一般
}
```
* 错误码
无
* 版本支持
xSimpleV4.0及以上
***
## 9、个人红包收发统计接口
* 描述
查询用户某一年红包收发记录的统计数据
* 请求
```
请求地址：mxm/api/v1/redpack/queryMyRedPackSummary
请求方式：POST
请求类型：
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| ------ | ---- | ---- | ---- | ---------------------------------- |
| userId | 是 | 字符串 | | 用户id |
| type | 是 | 字符串 | | “SEND”表示查询发送的红包，"RECEIVE"表示查询收到的红包 |
| year | 是 | 数字 | 2018 | 年份 |
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 网络请求失败时的提示信息 |
| data | JSON | | 接口返回数据，用户自定义 |
* data参数说明
```
{
//图像
avatar
//用户名
userName
//红包数量
count
//红包金额
amount
//手气最佳数
luckyNum
}
```
* 错误码
无
* 版本支持
xSimpleV4.0及以上
***
## 10、用户账号接口
* 描述
查询用户账号信息
* 请求
```
请求地址：mxm/api/v1/redpack/getUserInfo
请求方式：POST
请求类型：
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| ------ | ---- | ---- | ---- | ---- |
| userId | 是 | 字符串 | | 用户id |
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 网络请求失败时的提示信息 |
| data | JSON | | 接口返回数据，用户自定义 |
* data参数说明
```
{
// 平台用户标识
userId
// 平台用户账号
loginName
// 平台用户名称
userName
// 平台应用标识
appKey
// 支付宝用户标识
apUserId
// 支付宝授权码
apAuthCode
// 支付宝分享标识
apOpenId
// 支付宝用户昵称
apNickName
// 支付宝用户图像
apAvatar
// 支付宝用户账号（暂时获取不到）
apAccount
}
```
* 错误码
无
* 版本支持
xSimpleV4.0及以上
***
## 11、获取支付宝授权接口
* 描述
查询用户支付宝授权信息
* 请求
```
请求地址：mxm/api/v1/redpack/getAlipayAuth
请求方式：POST
请求类型：
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| ------ | ---- | ---- | ---- | ---- |
| userId | 是 | 字符串 | | 用户id |
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 网络请求失败时的提示信息 |
| data | JSON | | 接口返回数据，用户自定义 |
* data参数说明
```
{
// 签名串
sign = "N9jrLFCFHAsPBJbT%2FL6%2Bksf1yZB9n403FkSwTzbApAaLXrZrzQkac831%2BQIOGAv5AXbw32i4TZHeDuaU8o%2Bz547lhh1VCcN4cGSLOXN3SZjjY6MxMGuv9UUyv90skrtw1C8Re4R33T6dn2PpQBYg5rZnG9XQNTezpOO5YMeya1VVEJ2R9pGkquRHuNjew15%2BYX8BwoUY3y836CUIx2HA2yiUSe7s%2F1V5AdTVd5DtcVXacWyGqS7%2B55GOGLoqJdFXmUIhK6%2FwqOs3sbJFwIgKhTG3xuYpl24O1tWKtw%2Biuq1lr8NgKTLBljmtyKyvqkEWJvobvd38NO1WRCqnT7foaA%3D%3D";
// 签名参数
signStr = "appKey=123456789&app_id=2017111709985890&biz_content={\"order_title\":\"\U6d4b\U8bd5\U53d1\U7ea2\U5305\",\"amount\":\"0.10\",\"out_order_no\":\"df68acbf-5317-4f00-b6bc-72fc5d8b1d3a\",\"out_request_no\":\"df68acbf-5317-4f00-b6bc-72fc5d8b1d3a-1514533589175\"}&charset=UTF-8&format=JSON&method=alipay.fund.coupon.order.app.pay¬ify_url=http://app.coracle.com:10087/simple/notify.jsp&pay_timeout=30m&reqType=sendRedPack&rp_param={\"rp_groupId\":\"123\",\"rp_count\":7,\"rp_userId\":\"2\"}&rp_type=1&sign_type=RSA2×tamp=2017-12-29 15:46:29&userId=1&version=1.0";
}
```
* 错误码
无
* 版本支持
xSimpleV4.0及以上
***
## 12、获取红包领取详情接口
* 描述
点击红包时，返回红包信息
* 请求
```
请求地址：mxm/api/v1/redpack/queryRedPack
请求方式：POST
请求类型：
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| ---- | ---- | ---- | ---- | ---- |
| rpId | 是 | 字符串 | | 红包id |
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 网络请求失败时的提示信息 |
| data | JSON | | 接口返回数据，用户自定义 |
* data参数说明
| 键 | 类型 | 描述 |
| ------------- | ---- | --------------------------- |
| avatar | 数字 | 用户头像 |
| userName | 字符串 | 用户名 |
| redPackType | 数字 | 0为普通红包；1为群聊拼手气红包；2为群聊人均分配红包 |
| amount | 数字 | 领取金额，未领取时为空 |
| isValid | 布尔 | 是否有效，如果过期则无效 |
| restAmount | 数字 | 红包剩余金额，没领红包时返回 |
| receiveStatus | 数字 | 0已领取，1可领取 |
| describe | 字符串 | 红包描述 |
* 错误码
无
* 版本支持
xSimpleV4.0及以上
***
## 13、查询红包是否可以领取
* 描述
点击红包时，查询红包是否可以领取和红包信息
* 请求
```
请求地址：mxm/api/v1/redpack/queryRedPackDetails
请求方式：POST
请求类型：
```
* params参数说明-JSON类型
| 键 | 必选 | 类型 | 示例 | 描述 |
| ------ | ---- | ---- | ---- | ---- |
| rpId | 是 | 字符串 | | 红包标识 |
| userId | 是 | 字符串 | | 用户id |
* 方法返回
| 键 | 类型 | 示例 | 描述 |
| -------- | ---- | ---- | ------------------ |
| reqCode | 字符串 | 0 | 请求成功或失败。0：成功；1：失败； |
| errorMsg | 字符串 | | 网络请求失败时的提示信息 |
| data | JSON | | 接口返回数据，用户自定义 |
* data参数说明
```
{
//是否绑定了支付宝账号，1为已绑定，0为没有
isAuth
//领取金额，为空时表示未领取
amount
//是否有效（过期）
isValid
//红包余额
restAmount
//领取状态，0已领取，1可领取，2已领完
receiveStatus
//过期、已领完描述
message
//红包描述
describe
}
```
* 错误码
无
* 版本支持
xSimpleV4.0及以上
***
网友评论