## **应用参数** 对接前，需要向中台申请两个参数 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 | 维护人 | |