## **應用參數**
對接前，需要向中臺申請兩個參數
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 | 維護人 | |
