## **应用参数**
对接前，需要向中台申请两个参数
appCode: 应用code
secretKey: 应用秘钥
测试环境地址：https://ip/api
## **公共参数说明**
公共参数包括以下几个（**调用接口时务必带上以下参数**）：
1、appCode：应用code （由中心管理台管理员提供）
2、timeStamp：时间戳（精度为毫秒，时间以标准北京时间为准，时间差不能大于服务器设置的值，当前设置为300秒）
3、sign：签名（签名方式参考下面介绍）
注意：secretKey无需作为参数向后台传递，secretKey只是为了生成sign使用。
返回参数：
每个接口返回参数都包含两个参数：
{
"code":String,
"message":String,
其他参数
}
code: 0 - 失败 1 - 成功
message: 请求失败或者发生错误的具体描述，部分业务消息中携带接口编号
## **请求方式**
所有接口请求方式均采用PSOT方式；
Content-type 使用： application/x-www-form-urlencoded; charset=utf-8
## **签名**
#### **生成签名步骤**
有了安全凭证 appCode和 secretKey后，就可以生成签名串了。生成签名串的详细过程如下：
#### **签名举例**
**假如用户的appCode和secretKey如下**
appCode:U8Q5BKRT27BI
secretKey:1F255EE16ACC2678424FD4FDE8BD5E13
**假如需要调用的参数为**
参数 | 描述 | 值
:-:|:-: |:-:
name | 参数1 | admin
age | 参数2 | 30
timestamp | 参数3 | 1545927421045
appCode | 参数4 | U8Q5BKRT27BI
**参数排序**
首先对所有请求参数按参数名做字典序升序排列。（所谓字典序升序排列，直观上就如同在字典中排列单词一样排序，按照字母表或数字表里递增顺序的排列次序，即先考虑第一个“字母”，在相同的情况下考虑第二个“字母”，依此类推）。上述示例参数的排序结果如下：
{
"age" : 30,
"appCode" : "U8Q5BKRT27BI",
"name" : "admin"
"timeStamp" : 1545927421045
}
注意：参数排序时不需要加sign
**拼接请求字符串**
此步骤将生成请求字符串。
将把上一步排序好的请求参数格式化成“参数名称”=“参数值”的形式，如对 age 参数，其参数名称为"age"，参数值为"30"，因此格式化后就为 age=30
然后将格式化后的各个参数用"&"拼接在一起，最终生成的请求字符串为:
age=30&appCode=U8Q5BKRT27BI&name=admin&timeStamp=1545927421045
**生成签名串**
签名使用HmacSHA1 算法进行签名
使用签名算法HmacSHA1和secretKey对上一步中获得的**请求字符串** 进行签名，获得最终的签名串。
最终得到的签名串为:
3359CF98FE4BB6BDC99B157165E32B4E02651926
最后将生成的签名串作为sign的值传到后台。
# **接口描述**
## **查询短信模板 /msg/getTemplates**
**接口描述**
应用查看自己权限下的短信模板（需要中台管理台创建）
**接口地址**
http://\[url\]/msg/getTemplates
**业务参数描述**
仅需要传入公共参数，无业务参数
**返回值格式**
**返回值描述**
| 字段 | 类型 | 描述 | 备注 |
|:---------------:|:------:|:--------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| id | String | 短信模板Id | |
| applicationCode | String | 应用code | 同appCode |
| code | String | 短信模板Code | 发送短信时需要使用该code |
| name | String | 模板名称 | |
| type | String | 模板类型 | 模板类型 AC:验证码(auth code) SN:短信通知(short note) PS:推广短息(Promotion of SMS) VN：语音通知（voice notification） VC：语音验证码(Voice verification code) |
| templateCode | String | 阿里云模板Code | |
| content | String | 短信内容 | |
| state | Char | 模板状态 | Y：正常 N：禁用 |
| paramDesc | String | 参数描述 | |
| reserve1 | String | 备用字段1 | |
| reserve2 | String | 备用字段2 | |
| reserve3 | String | 备用字段3 | |
## **发送短信/msg/sendMessage**
**接口描述**
根据短信模板发送短信
**接口地址**
http://\[url\]/msg/sendMessage
**业务参数描述**
| 字段 | 类型 | 描述 | 是否必须 | 备注 |
|--------------|--------|----------------|----------|------------------------------------------|
| phoneNumbers | String | 手机号 | 是 | 多个手机号中间采用英文“；”间隔 |
| code | Sting | 短息模板 | 是 | |
| jsonParam | String | 短信参数JSON串 | 是 | |
| repeatSend | Char | 失败后是否重试 | 否 | Y：重试N：不重试（默认） |
| smsSignName | String | 短信签名 | 否 | 签名由管理员提供，默认为：“西部机场集团” |
**返回值描述**
| { "code": "1", "message": "短信发送请求成功！", "data":null} |
|-------------------------------------------------------------------|
返回成功为请求成功，具体短信发送是否成功需要查看发送记录
## **查看发送短信记录/msg/findSmsMsgs**
**接口描述**
应用查看发送过的短信记录；按照发生时间倒叙排
**接口地址**
http://\[url\]/msg/findSmsMsgs
**参数描述**
| 字段 | 类型 | 描述 | 是否必须 | 备注 |
|---------------|--------|--------------|----------|---------------------------|
| phoneNumber | String | 手机号 | 否 | |
| state | String | 发送状态 | 否 | Y：成功N：失败 |
| code | String | 短信模板Code | 否 | |
| sendStartTime | String | 发送起始时间 | 否 | 格式：yyyy-MM-dd HH:mm:ss |
| sendEndTime | String | 发送结束时间 | 否 | |
| pageNum | int | 分页页码 | 否 | 不能小于1，不填默认为1 |
| pageSize | int | 分页大小 | 是 | 不能大于200 |
**返回值格式**
| { "code": "1", "message": "OK", "total": 1, #总记录数 "pages": 1, #页数 "list": [ #查询分页的数据 { "id": "*******", "applicationCode": "****", "sender": "system", "phoneNumber": "****", "state": "Y", "bizId": "767103245924593448^0", "sendTime": "2018-12-27 23:29:53", "errCode": "DELIVERED", "errMsg": "用户接收成功", "content": "{\"customerName\":\"账户\",\"alarmvalue\":\"100\",\"residual\":\"50\",\"tel\":\"6966656\"}", "code": "****", "smsSize": 1, "times": 1, "reportTime": "2018-12-27 23:29:59", "reserve1": null, "reserve2": null, "reserve3": null, "remark": null, "createTime": "2018-12-27 23:30:01", "updateTime": "2018-12-27 23:30:01", "maintainer": "system" } ]} |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
**返回值描述**
| 字段 | 类型 | 描述 | 备注 |
|-----------------|--------|-----------------------|------------------|
| id | String | 短信发送的记录Id | |
| applicationCode | String | 应用Code | |
| sender | String | 短信发送者 | 默认为system |
| phoneNumber | String | 短信接收者手机号 | |
| state | String | 发送状态 | N：失败 Y：成功 |
| bizId | String | 阿里云短信ID | |
| sendTime | Date | 短信发送时间 | |
| errCode | String | 发送结果状态码 | |
| errMsg | String | 发送结果消息 | |
| content | String | 短信调用参数 | |
| code | String | 短信模板Code | |
| smsSize | int | 短信个数 | |
| times | int | 发送次数，失败会大于1 | |
| reportTime | Date | 短信回执时间 | |
| reserve1 | String | 备用字段1 | |
| reserve2 | String | 备用字段2 | |
| reserve3 | String | 备用字段3 | |
| remark | String | 备注 | |
| createTime | Date | 创建时间 | |
| updateTime | Date | 修改时间 | |
| maintainer | String | 维护人 | |
## **刷新短信记录状态/msg/refreshSmsMessageStatus**
**接口描述**
根据短信记录Id从阿里云刷新未成功状态的短信状态；
短信服务采用阿里云短信服务，发送状态结果回执为异步，存在及时性问题；因此如果通过接口/msg/findSmsMsgs查询到的短信记录存在等待回执状态的记录，则需要调用该接口从阿里云更新下状态。
**接口地址**
http://\[url\]/msg/refreshSmsMessageStatus
**参数描述**
| 字段 | 类型 | 描述 | 是否必须 | 备注 |
|-----------|--------|------------|----------|------|
| messageId | String | 短信记录Id | 是 | |
**返回值格式**
{
"code": "1",
"message": "OK",
"data": {
"id": "\*\*\*\*\*\*\*",
"applicationCode": "\*\*\*\*",
"sender": "system",
"phoneNumber": "\*\*\*\*",
"state": "Y",
"bizId": "767103245924593448^0",
"sendTime": "2018-12-27 23:29:53",
"errCode": "DELIVERED",
"errMsg": "用户接收成功",
"content": "{\\"customerName\\":\\"账户\\",\\"alarmvalue\\":\\"100\\",\\"residual\\":\\"50\\",\\"tel\\":\\"6966656\\"}",
"code": "\*\*\*\*",
"smsSize": 1,
"times": 1,
"reportTime": "2018-12-27 23:29:59",
"reserve1": null,
"reserve2": null,
"reserve3": null,
"remark": null,
"createTime": "2018-12-27 23:30:01",
"updateTime": "2018-12-27 23:30:01",
"maintainer": "system"
}
}
**返回值描述**
| 字段 | 类型 | 描述 | 备注 |
|-----------------|--------|-----------------------|------------------|
| id | String | 短信发送的记录Id | |
| applicationCode | String | 应用Code | |
| sender | String | 短信发送者 | 默认为system |
| phoneNumber | String | 短信接收者手机号 | |
| state | String | 发送状态 | N：失败 Y：成功 |
| bizId | String | 阿里云短信ID | |
| sendTime | Date | 短信发送时间 | |
| errCode | String | 发送结果状态码 | |
| errMsg | String | 发送结果消息 | |
| content | String | 短信调用参数 | |
| code | String | 短信模板Code | |
| smsSize | int | 短信个数 | |
| times | int | 发送次数，失败会大于1 | |
| reportTime | Date | 短信回执时间 | |
| reserve1 | String | 备用字段1 | |
| reserve2 | String | 备用字段2 | |
| reserve3 | String | 备用字段3 | |
| remark | String | 备注 | |
| createTime | Date | 创建时间 | |
| updateTime | Date | 修改时间 | |
| maintainer | String | 维护人 | |
