短信营销 - API文档
1.概要
1.1文档说明
本文档主要提供给互亿平台的用户对接接口的使用说明，开发者可以利用 ihuyi 提供的 HTTP 接口，调用 ihuyi 的营销短信服务。
1.2接口内容
本文档包含短信批量提交、余额查询、短信模板提交、回执推送、上行推送、模板审核推送。
1.3提交方式
POST
1.4加密方式
1、采用HTTPS协议提交请求
2、通过MD5动态签名方式加密
1.5 api id / api key
登录用户中心，进入“营销短信”模块，在产品概览页面右侧获取，如下图所示：
1.6短信模版
举个例子，
A用户在您平台注册会员，需要发送一条短信，内容如下：
注意：付费用户可以通过左侧导航【营销短信】-【短信发送】-【模版管理】新增短信模板，运营商审核通过之后即可正式使用。
1.7短信签名
短信签名是加在短信的开头或结尾，在【】加上您的公司名称或店铺名称的标识符，例如：【互亿无线】。 根据电信基础运营商的规定，每条短信必须附加短信签名，否则将无法正常发送。
2. 公共请求参数(json格式)
| 参数 | 类型 | 是否必填 | 说明 |
| api_id | string | 是 | Api的ID 如:sms-yx******* |
| signature | string | 是 |
请求验证加密签名(非短信签名);
|
| timestamp | int | 是 | 东八时区;10位时间戳,时间允许相差±60S golang: time.Now().Unix() php: time() |
| request_id | string | 是 | 请求方请求ID,建议使用唯一ID,比如使用uuid;我方系统会2小时内去重验证处理,防止网络重放攻击; |
3. 短信批量提交接口
3.1协议说明
| 协议类目 | 说明 |
| 请求方式 | POST |
| 编码格式 | UTF-8 |
| Content-Type | application/json |
3.2请求地址
https://api.ihuyi.com/sms-yx/v1/batchSend
3.3请求参数（json格式,需要包含公共请求参数）
| 参数 | 类型 | 是否必填 | 说明 |
| product_id | int | 是 | 产品ID,如:1001（获取方式见下文） |
| phone | array |
是 | 手机号数组(最多1万个号码),如:["18800000000","18800000001"] |
| sign_name | string | 是 | 短信签名,如:互亿无线 |
| content | string | 是/否 | template_id为空时必填； 短信内容,如:您的短信群发功能已开通,请在3个工作日之内至平台进行企业认证! 短信内容和模板ID必须传入1个;当短信内容和模板ID都传入时,传入内容生效,模板ID属性失效; |
| template_id | int | 是/否 | content为空时必填； 模板ID |
| template_var | object |
否 | 选择模板时,且模板是变量模板时,可以传入变量值,需要传入json格式; key value 格式存储,如:{"${name}":"\u5f20\u4e09","${order_no}":"202009041156181103"} |
| send_time | string | 否 | 定时发送时间 2020-08-26 16:08:14 |
*product_id获取：登录到控制台，进入“云通讯 -> 营销短信 -> 产品总览 -> 我的资源包”页面查看。
3.4返回参数(json格式)
| 参数 | 类型 | 说明 |
| task_id | string | 下发批次ID,推送回执相关会用作关联 |
| code | string | 状态码,OK表示发送成功,其他则是错误 |
| message | string | 消息内容 |
4. 余额查询接口
4.1请求地址
https://api.ihuyi.com/sms-yx/v1/balance
4.2请求参数（json格式,需要包含公共请求参数）
4.3返回参数(json格式)
| 参数 | 类型 | 说明 | ||||||||||||
| task_id | string | 下发批次ID,推送回执相关会用作关联 | ||||||||||||
| code | string | 状态码,OK表示发送成功,其他则是错误 | ||||||||||||
| message | string | 消息内容 | ||||||||||||
| data | array |
多个数组方式返回 DataItem结构:
|
示例：
{
"code": "OK",
"message": "请求成功",
"data": [
{
"product_id": 1018,
"product_name": "营销短信-房产类",
"balance": 188888
},
{
"product_id": 1020,
"product_name": "营销短信-商超类",
"balance": 200000
}
]
}
5. 短信模板提交接口
5.1协议说明
| 协议类目 | 说明 |
| 请求方式 | POST |
| 编码格式 | UTF-8 |
| Content-Type | application/json |
5.2请求地址
https://api.ihuyi.com/sms-yx/v1/templateCreate
5.3请求参数(json格式,需要包含公共请求参数)
| 参数 | 类型 | 是否必填 | 说明 |
| title | string | 是 | 模板标题(用于标识,不会出现在短信内容中) |
| content | string | 是 | 模板内容(变量请使用变量标识方式:${变量名称}, 如: ${name} ) |
| purpose | string | 是 | 应用场景描述 |
| is_variable | int | 是 | 0表示不带变量，1表示带变量 |
5.4返回参数(json格式)
| 参数 | 类型 | 说明 |
| template_id | int | 模板ID |
| code | string | 状态码,OK表示发送成功,其他则是错误 |
| message | string | 消息内容 |
6. 回执推送
6.1协议说明
| 协议类目 | 说明 |
| 调用方式 | 主动回调 |
| 请求方式 | POST |
| 编码格式 | UTF-8 |
| Content-Type | application/json |
| 数据格式 | json |
注意：接口推送后请记录数据并及时返回结果，业务逻辑采用异步处理，避免接口响应超时而导致重复推送。
6.2回执数据定义
| 参数 | 类型 | 说明 |
| task_id | string | 下发批次ID |
| phone | string | 手机号码 |
| code | string | 状态码,DELIVERED则是成功,其他则是失败 |
| message | string | 返回消息,用户接收成功 |
| send_time | string | 发送时间 |
| report_time | string | 回执时间 |
响应说明:
成功接收请输出字符 “success” （不包含引号）结束推送，否则以接收失败处理。每个回执最多推送3次。每次间隔叠加60秒。
7. 上行推送
7.1协议说明
| 协议类目 | 说明 |
| 调用方式 | 主动回调 |
| 请求方式 | POST |
| 编码格式 | UTF-8 |
| Content-Type | application/json |
| 数据格式 | json |
注意：接口推送后请记录数据并及时返回结果，业务逻辑采用异步处理，避免接口响应超时而导致重复推送。
7.2回执数据定义
| 参数 | 类型 | 说明 |
| task_id | string | 下发批次ID |
| phone | string | 手机号码 |
| content | string | 上行内容 |
| dest_code | string | 上行通道扩展号 |
| send_time | string | 发送时间 |
| receive_time | string | 收取时间 |
响应说明:
成功接收请输出字符 “success” （不包含引号）结束推送，否则以接收失败处理。每个回执最多推送3次。每次间隔叠加60秒。
8.模板审核推送
8.1协议说明
| 协议类目 | 说明 |
| 调用方式 | 主动回调 |
| 请求方式 | POST |
| 编码格式 | UTF-8 |
| Content-Type | application/json |
| 数据格式 | json |
注意：接口推送后请记录数据并及时返回结果，业务逻辑采用异步处理，避免接口响应超时而导致重复推送。
8.2模板审核数据定义
| 参数 | 类型 | 说明 |
| template_id | int | 模板ID |
| code | string | 状态值(SUCCESS审核通过,FAIL审核失败) |
| message | string | 审核消息 |
9.错误码查询
| Code | 说明 |
| OK | 请求成功 |
| ParamError | 参数错误 |
| AccessKeyIDNotExist | AccessKeyID不存在 |
| UserIDNotExist | 用户ID不存在 |
| AmountError | 数额错误(超出许可范围) |
| TimestampError | 时间错误(超出许可范围) |
| ProductIDNotExist | 产品ID不存在 |
| TypeNotExist | 类型不存在 |
| RemarkError | 备注错误 |
| RequestIDExisted | 请求ID已存在 |
| NonceExisted | 随机数已存在 |
| SingError | 签名错误 |
| SignExpired | 签名过期 |
| BalanceNotEnough | 余额不足 |
| PackIDExisted | 资源包ID已存在 |
| SystemError | 系统异常 |
| InputDataInvalid | 请求参数异常 |
