互亿无线 · 文档中心

短信营销 - 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用户在您平台注册会员,需要发送一条短信,内容如下:
尊敬的王先生,互亿无线双旦活动,送您100元优惠券!回T退订
同时,B用户也在您的平台注册会员,发送了如下短信:
尊敬的李先生,互亿无线双旦活动,送您100元优惠券!回T退订
我们提取相同部分以后,可以制作以下短信模板:
尊敬的${name},互亿无线双旦活动,送您100元优惠券!回T退订
其中,${name}为变量部分,可以是数字、字母、汉字。

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

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 是/否 template_id为空使必填;
短信签名,如:互亿无线
content string 是/否 template_id为空使必填; 短信内容,如:您的短信群发功能已开通,请在3个工作日之内至平台进行企业认证! 短信内容和模板ID必须传入1个;当短信内容和模板ID都传入时,传入内容生效,模板ID属性失效;
template_id int 是/否 content为空时候必填;

 

模板ID
template_var Array 选择模板时,且模板是变量模板时,可以传入变量值,需要传入json格式;
key value 格式存储,如:["${name}":"张三","${order_no}":"202009041156181103"]
send_time string 定时发送时间 2020-08-26 16:08:14

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格式)

参数 类型 说明
task_id string 下发批次ID,推送回执相关会用作关联
code string 状态码,OK表示发送成功,其他则是错误
message string 消息内容
data array 多个数组方式返回
DataItem结构:
参数 类型 描述
product_id int 产品ID
product_name string 产品名称
balance float 余额

示例:

 

{

    "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 说明
Success 请求成功
ParamError 参数错误
AccessKeyIDNotExist AccessKeyID不存在
UserIDNotExist 用户ID不存在
AmountError 数额错误(超出许可范围)
TimestampError 时间错误(超出许可范围)
ProductIDNotExist 产品ID不存在
TypeNotExist 类型不存在
RemarkError 备注错误
RequestIDExisted 请求ID已存在
NonceExisted 随机数已存在
SingError 签名错误
SignExpired 签名过期
BalanceNotEnough 余额不足
PackIDExisted 资源包ID已存在
SystemError 系统异常
InputDataInvalid 请求参数异常

现在注册,即享新用户礼包!

服务热线:
4008 808 898