群发营销短信API接口文档

1.概要

1.1文档说明

本文档主要提供给互亿无线短信接口平台的用户对接接口的使用说明，开发者可以利用互亿无线短信接口平台提供的 HTTP 接口，调用互亿无线短信接口平台的营销短信服务。

1.2接口内容

本群发营销短信API接口文档包含短信批量提交、余额查询、短信模板提交、回执推送、上行推送、模板审核推送。

1.3提交方式

POST

1.4加密方式

1、采用HTTPS协议提交请求
2、通过MD5动态签名方式加密

1.5 api id / api key

登录用户中心，进入“营销短信”模块，在产品概览页面右侧获取，如下图所示：

1.6短信模版

注意：付费用户可以通过左侧导航【营销短信】-【短信发送】-【模版管理】新增短信模板，运营商审核通过之后即可正式使用。

1.7短信签名

短信签名是加在短信的开头或结尾，在【】加上您的公司名称或店铺名称的标识符，例如：【互亿无线】。 根据电信基础运营商的规定，每条短信必须附加短信签名，否则将无法正常发送。

2. 公共请求参数(json格式)

参数	类型	是否必填	说明
api_id	string	是	Api的ID 如:sms-yx*******
signature	string	是	请求验证加密签名(非短信签名); 签名生成方式: 32位小写; 如:
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结构: 参数 类型 描述 product_id int 产品ID product_name string 产品名称 balance float 余额

示例：

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	请求参数异常