一、应用场景
短信集成服务是物联网平台提供的用于客户自定义短信发送通道的功能。客户可以使用短信集成服务实现将物联网平台需要发送短信的业务通过客户指定的第三方短信平台进行发送。可用于以下业务场景：
- 客户已有自建的统一的短信系统，需要将物联网平台的短信通过客户自建的短信系统发送；
- 客户希望根据不同用户地区、用户短信类型采用不同的短信发送提供商的短信发送服务；
二、功能说明
客户在物联网平台管理台【应用中心->集成->短信服务->短信配置】中开启第三方短信平台功能，并填写URL与Token。其中URL是用来接收物联网平台发送的短信数据接口，URL必须为HTTPS接口；Token用作验证URL有效性。在物联云平台产生一条短信后，将使用第三方厂商平台发送短信，物联云平台会将短信 POST到第三方厂商短信平台，最终由第三方厂商平台将短信发出。
短信主要包含以下几种：
用户注册验证码
用户忘记密码
用户更新手机号码
用户短信登录
三、前提条件
- 参考管理台操作手册《应用中台操作手册》，在管理台【应用中心->集成->短信服务->短信配置】中选择使用第三方厂商短信；
- 在管理台正确配置第三方邮箱URL、Token；
- 第三方平台在配置的URL上实现验证接口和接收短信内容的接口；
- 点击【验证】按钮进行第三方优先系统对接验证，验证完成后点击【保存】按钮；
四、关键流程
4.1. 第三方短信系统对接流程
流程说明： 成员在管理台进行短信配置，填写第三方短信系统URL和Token，进行验证和保存。验证通过后，物联网平台的短信将发送到配置的第三方短信系统进行发送。
4.2 短信发送流程
流程说明： 短信发送者根据不同场景向物联网中台发起 发送短信 请求，物联网中台收到请求后根据请求信息找出企业下设置第三方短信系统的地址以及调用凭证，利用短信系统地址和调用凭证向第三方短信系统发送短信。
五、API列表
5.1 验证URL有效性
接口描述
在物联网平台配置完URL和Token后，物联网平台会通过配置的URL和Token向第三方厂商发起验证。
验证URL有效性: 需要符合以下规范，且由外部系统实现，其中请求地址可自定义，调用成功判断标准为HTTP响应状态码为200且返回对应的返回值。
请求方式
GET
请求地址
由用户在物联网平台管理台配置的URL
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Content-Type | true | String | application/json |
请求参数
| 名称 | 参数位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| timestamp | query | true | string | 时间戳 |
| signature | query | true | string | 物联网平台加密签名； 1.签名算法：signature=SHA1(corpId + Token + timestamp)， 2.corpId是企业在物联网平台的企业ID 3.Token由客户在物联网平台管理台填写 |
验证方法说明：第三方短信系统通过检验signature对GET请求验证，若自身通过签名算法【SHA1(corpId + Token + timestamp) 】加密得到的数据与请求的signature一致，则返回HTTP状态码 200 OK设置有效，否则设置无效，返回错误消息，统一按照返回消息格式响应。
请求示例：
GET http://tac.com/sms/iot?tumestamp=14342587903&signature=37975ef199e20f8b04fbdba750547e42b2e604f3返回参数说明
校验成功返回http 状态码 200。
返回示例：
http status code ：200错误返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| err_code | 是 | Integer | 错误码 |
| err_msg | 是 | String | 错误信息 |
错误返回示例：
{
"err_code":"4031003",
"err_msg":"Token验证失败"
}错误码：
| 错误码 | 描述 |
|---|---|
| 4031003 | 不合法的调用凭证 |
| 4041010 | 企业ID不合法 |
5.2 发送短信
接口描述
物联网根据短信模板生成短信，若管理台短信配置为【使用第三方厂商短信】，则将内容POST到管理台填写的URL中，内容为请求Body，第三方厂商负责将短信发出。此接口定义物联网平台发出短信格式；
发送短信: 需要符合以下规范，且由外部系统实现，其中请求地址可自定义，调用成功判断标准为HTTP响应状态码为200且返回对应的返回值。
请求方式
POST
请求地址
由用户在物联网平台管理台配置的URL
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Content-Type | true | String | application/json |
请求参数
| 名称 | 参数位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| to | body | true | String | 接收者手机号码，多个号码以英文逗号分隔，如： 17011223344,17022334455 |
| sms_param | body | true | Object | 短信参数 |
| sms_param.type | body | true | enum | 短信参数类型，参考5.3.1 短信参数类型说明 |
| sms_param.code | body | true | String | 验证码 |
| sms_param.minute | body | true | String | 验证码有效期, 单位 分钟 |
| area_code | body | false | String | 接收短信的手机区号 |
| plain_sms | body | false | String | 短信原文 |
| plugin_id | body | false | String | 短信关联的物理网中台应用网关标识 第三方系统可以根据此参数去确定不同的短信签名等 |
验证方法说明：第三方短信系统通过检验signature对GET请求验证，若自身通过签名算法【SHA1(corp_id + Token + timestamp) 】加密得到的数据与请求的signature一致，则返回HTTP状态码 200 OK设置有效，否则设置无效，返回错误消息，统一按照返回消息格式响应。
请求示例：
{
"area_code": "+86",
"to": "13838383388",
"plain_sms": "注册验证码为 85626",
"plugin_id": "5632265wfdsafdsf",
"sms_param": {
"type": 1,
"code": "85626",
"minute": 5
}
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| err_code | 是 | Integer | 错误码 |
| err_msg | 是 | String | 错误信息 |
返回示例：
{
"err_code":"4031003",
"err_msg":"Token验证失败"
}错误码：
| 错误码 | 描述 |
|---|---|
| 0 | 发送成功 |
| 4031003 | 不合法的调用凭证 |
| 4041010 | 企业ID不合法 |
| 4002001 | 短信内容不合法 |
| 4002002 | 短信接收号码不合法 |
| 4002003 | 国家码不合法 |
5.3 附录一：短信参数说明
5.3.1 短信参数类型说明
| Type枚举值 | 备注 |
|---|---|
| 1 | 用户注册验证码 |
| 2 | 用户忘记密码 |
| 3 | 用户更新手机号码 |
| 4 | 用户短信登录 |
5.3.2 各类型短信参数描述
5.3.2.1 用户注册验证码
{
"type": 1,
"code": "验证码",
"minute": "验证码有效期"
}5.3.2.2 用户忘记密码
{
"type": 2,
"code": "验证码",
"minute": "验证码有效期"
}5.3.2.3 用户更新手机号码
{
"type": 3,
"code": "验证码",
"minute": "验证码有效期"
}5.3.2.4 用户短信登录
{
"type": 4,
"code": "验证码",
"minute": "验证码有效期"
}