验证码通知短信API接口文档

1、概要

1.1 文档说明

本文档主要提供给互亿短信接口平台的用户对接接口的使用说明，开发者可以利用互亿短信接口平台提供的 HTTP 接口，调用互亿短信接口平台的短信验证码/通知服务。

1.2 接口内容

本验证码通知短信接口文档包含短信发送、余额查询、发送回执推送、上行回复推送等。

1.3 提交方式

GET / POST

1.4 加密方式

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

1.5 API ID / API KEY

登录用户中心，进入【验证码通知短信】->【产品总览】，再页面右侧查看：

1.6 短信模版

短信模板是从您计划发送的短信中提取出的标准化内容模式。例如，

当A用户在您的平台上注册成为会员时，您可能会发送如下短信：

您好，您的验证码是：666666

同时，B 用户也在您的平台注册会员，发送了如下短信:

您好，您的验证码是：888888

我们提取相似度以后，可以制作以下短信模板:

您好，您的验证码是：【变量】

这里的“变量”可以是数字、字母或汉字，具有可变性。

请注意：未付费用户只能使用默认的短信模板。付费用户可以通过导航菜单“验证码通知短信”-“短信发送”-“签名/模版管理”添加新的短信模板，一旦通过运营商审核，便可开始使用。

1.7 短信签名

短信签名是您在短信开始或结束部分加入的公司或店铺名称标识，格式如【互亿无线】。根据电信运营商的要求，每条短信都必须包含短信签名，否则将无法发送。

请注意：未付费用户只能使用默认短信签名【互亿无线】。付费用户则可以通过点击导航菜单“验证码通知短信”-“短信发送”-“签名/模版管理”来修改短信签名，审核通过后即可使用。

2、短信单条发送

2.1 接口描述

通过POST、 GET 方式进行短信提交，内容格式为：Content-Type: application/x-www-form-urlencoded，数据编码采用utf-8格式，24小时全天发送。

2.2 请求地址

    https://106.ihuyi.com/webservice/sms.php?method=Submit

2.3 请求参数

参数名称	参数值描述	必填
account	APIID(用户中心【验证码通知短信】-【产品纵览】查看)	是
password	1、APIKEY(用户中心【验证码通知短信】-【产品纵览】查看) 2、动态密码(生成动态密码方式请看该文档末尾的说明)	是
mobile	接收手机号码，只能提交1个号码	是
content	短信内容(编码格式为 UTF-8，支持 500 个字的长短信，长短信按多条计费) 例如:您的验证码是：1234。请不要把验证码泄露给其他人。	是
time	Unix时间戳（10位整型数字，当使用动态密码方式时为必填）	否
format	返回格式（可选值为：xml或json，系统默认为xml）	否

用户通过http 或 https提交发送短信请求到服务器后，服务器会返回一串xml格式的字符串，SubmitResult结构说明如下：

参数名称	类型	描述
code	int	返回值为2时，表示提交成功
smsid	string	当提交成功后，此字段为流水号，否则为0
msg	string	提交结果描述

2.4 响应示例

示例（成功）



  2 提交成功 14745625541233112231

示例（失败）



  405 account或password不正确 0

2.5 响应参数

code	msg
0	提交失败
2	提交成功
400	非法ip访问
401	帐号不能为空
402	密码不能为空
403	手机号码不能为空
4030	手机号码已被列入黑名单
404	短信内容不能为空
405	API ID 或 API KEY 不正确
4050	账号被冻结
40501	动态密码已过期
40502	动态密码校验失败
40504	超出每天最大发送量
40505	没有签定合同
4051	剩余条数不足
4052	访问 ip 与备案 ip 不符
4053	用户不存在
4054	帐户无效
406	手机格式不正确
407	短信内容含有敏感字符
4070	签名格式不正确
4071	没有提交备案模板
4072	提交的短信内容与审核通过的模板内容不匹配
40722	变量内容超过指定的长度【8】
4073	短信内容超出长度限制
4074	短信内容包含 emoji 符号
4075	签名未通过审核
4077	短信变量内容含有敏感字符
408	发送超限【50】条，已加入黑名单，可登入平台解除
4082	超出同一手机号一天之内【100】条短信限制
4085	同一手机号一天之内验证码短信发送超出【10】条

2.6 请求示例

            http://106.ihuyi.com/webservice/sms.php?method=Submit&account=APIID&password=APIKEY&mobile=手机号码&content=您的验证码是：1234。请不要把验证码泄露给其他人。

3、短信批量发送

3.1 接口描述

通过POST方式进行短信提交，内容格式为：Content-Type: application/x-www-form-urlencoded，数据编码采用utf-8格式，24小时全天发送。

3.2 请求地址

    https://106.ihuyi.com/webservice/sms.php?method=SubmitBatch

3.3 请求参数

参数名称	参数值描述	必填
account	APIID(用户中心【验证码通知短信】-【产品总览】查看)	是
password	1、APIKEY(用户中心【验证码通知短信】-【产品总览】查看) 2、动态密码(生成动态密码方式请看该文档末尾的说明)	是
mobile	手机号码（可参考下文示例）	是
templateid	模板ID	选填
content	短信内容	选填
time	Unix时间戳（10位整型数字，当使用动态密码方式时为必填）	否
format	返回格式（可选值为：xml或json，系统默认为xml）	否
sendTime	定时发送时间	否

用户通过http 或 https提交发送短信请求到服务器后，服务器会返回一串xml格式的字符串，SubmitBatchResult结构说明如下：

参数名称	类型	描述
code	int	返回值为2时，表示提交成功
smsid	string	流水号（对应提交时返回的smsid）
msg	string	回执状态说明

3.4 响应参数

code	msg
0	提交失败
2	提交成功
400	非法ip访问
401	帐号不能为空
402	密码不能为空
403	手机号码不能为空
4031	手机号码必须大于1个
4032	手机号码必须小于5000个
404	模板ID模和模板内容二选一
4041	模板ID不正确
405	API ID 或 API KEY 不正确
4050	账号被冻结
40501	动态密码已过期
40502	动态密码校验失败
40505	没有签定合同
4051	剩余条数不足
4052	访问 ip 与备案 ip 不符
4053	用户不存在
4054	帐户无效
406	手机格式不正确
407	短信内容含有敏感字符
4070	签名格式不正确
4074	短信内容包含 emoji 符号
4075	签名未通过审核
4077	短信变量内容含有敏感字符
408	定时发送时间无效(大于当时间10分钟，小于当前时间7天
409	计费错误

3.5 传参说明

1、不含变量

手机号格式：号码使用英文逗号分隔，例如：136xxxx1111,136xxxx2222,136xxxx3333
模板ID：选用您之前在平台注册的模板ID，例如：624452
模板内容：您有新的订单，请注意查收。

2、含变量

手机号格式：各变量使用半角竖线“|”分隔，例如：136xxxx1111|11111111|菜鸟,136xxxx2222|22222222|京东,136xxxx3333|3333333333|顺丰
模板ID：选用您之前在平台注册的模板ID，例如：624452
模板内容：您的订单号是：【变量】。已由【变量】快递发出，请注意查收。

注意：

单次提交的手机号数量应不少于2个，且不超过5000个。
提交时可选择使用模板ID或直接提供模板内容。若选择传递模板内容或手机号数量超过500，将会触发人工审核流程。

4、余额查询

4.1 接口描述

通过POST、 GET 方式查询你的账户验证码通知短信剩余条数，内容格式为：Content-Type: application/x-www-form-urlencoded，数据编码采用utf-8格式。

4.2 请求地址

            http://106.ihuyi.com/webservice/sms.php?method=GetNum

4.3 请求参数

参数名称	参数值描述	是否必填
account	APIID（请登录用户中心【验证码通知短信】-【产品总览】查看）	是
password	1、APIKEY（请登录用户中心【验证码通知短信】-【产品总览】查看） 2、动态密码（生成动态密码方式请看该文档末尾的说明）	是
time	Unix时间戳（10位整型数字，当使用动态密码方式时为必填）	否
format	返回格式（可选值为：xml或json，系统默认为xml）	否

用户通过http 或 https提交帐户余额查询请求到服务器后，服务器会返回一串xml格式的字符串，GetNumResult结构说明如下：

参数名称	类型	描述
code	int	状态返回值
msg	string	查询结果描述
num	string	剩余数量

4.4 响应示例

示例（成功）



  2 查询成功 856

示例（失败）



  405 account或password不正确 0

4.5 响应参数

code	msg
2	查询成功
400	非法ip访问
401	帐号不能为空
402	密码不能为空
405	用户名或密码不正确
4050	账号被冻结

4.6 GET请求示例

            http://106.ihuyi.com/webservice/sms.php?method=GetNum&account=APIID&password=APIKEY

5、发送回执推送

5.1 接口描述

用户先提供数据接收地址，然后绑定到互亿无线系统后台，平台会以POST方式实时的将回执信息推送到此地址，内容格式为：Content-Type: application/x-www-form-urlencoded。

5.2 推送参数

参数名称	参数值描述
code	状态值（2成功其他为失败）
msg	回执状态说明
mobilephone	手机号码
smsid	流水号（对应提交时返回的smsid）
report_time	回执时间例:2017-08-02 14:31:51
batchid	批量发送短信时，才会返回此参数

注意: 成功接收请输出字符 “success” (不包含引号)结束推送，否则以接收失败处理。每个回执最多推送 3 次。每次间隔叠加 60 秒。

6、上行回复推送

6.1 接口描述

用户先提供数据接收地址，然后绑定到互亿无线系统后台，平台会以 POST 方式实时的将回复信息推送到此地址。

6.2 推送参数

参数名称	参数值描述
mobilephone	手机号码
content	上行内容
smsid	流水号(对应提交时返回的 smsid)(仅作参考)
reply_time	上行时间例:2017-05-24 17:46:50

注意: 成功接收请输出字符 “success” (不包含引号)结束推送，否则以接收失败处理。每个回执最多推送 3 次。每次间隔叠加 60 秒。

7、提交模板

7.1 接口描述

通过 POST、 GET 方式提交短信模版，内容格式为：Content-Type: application/x-www-form-urlencoded，数据编码采用 utf-8 格式。

7.2 请求地址

            http://106.ihuyi.com/webservice/sms.php?method=AddTemplate&account=APIID&password=APIKEY&content=您的验证码是：【变量】。请不要把验证码泄露给其他人。

7.3 请求参数

参数名称	参数值描述
method	AddTemplate
account	提交账户
password	提交账户密码 (可以明文密码或使用 32 位 MD5 加密)
content	模板内容
type	1验证码 2通知
scene	使用场景

返回值 AddTemplateResult 结构说明:

参数名称	类型	描述
code	int	返回值为 2 时，表示添加成功
msg	string	提交状态描述
templateid	int	添加成功则返回模板 ID

7.4 响应参数

code	msg
2	添加成功
400	非法ip访问
401	用户名不能为空
402	密码不能为空
404	模板内容不能为空
405	用户名或密码不正确
4050	账号被冻结
407	模板内容含有敏感字符
408	模板己存在

7.5 模板审核状态推送

在遵守 HTTP 协议规范的前提下，通过 POST 方式将回执推送到用户指定的 URL 地址。

参数说明:

参数名称	参数值描述
code	状态值(2 成功 0 驳回)
msg	审核状态描述
templateid	模板 ID

注意:

1.成功接收请输出字符 “success” (不包含引号)结束推送，否则以接收失败处理。

2.每个回执最多推送 3 次。每次间隔叠加 60 秒。

3.code 值说明

2 成功

0 驳回(原因请看 msg 字段)

8、删除模板

8.1 接口描述

通过POST、 GET 方式提交短信模版，内容格式为：Content-Type: application/x-www-form-urlencoded，数据编码采用utf-8格式。

8.2 请求地址

            http://106.ihuyi.com/webservice/sms.php?method=DelTemplate&account=APIID&password=APIKEY&templateid=123

8.3 请求参数

参数名称	参数值描述
method	DelTemplate
account	提交账户
password	提交账户密码 (可以明文密码或使用 32 位 MD5 加密)
templateid	模板id

返回值 AddTemplateResult 结构说明:

参数名称	类型	描述
code	int	返回值为 2 时，表示删除成功
msg	string	提交状态描述

8.4 响应参数

code	msg
2	删除成功
400	非法ip访问
401	用户名不能为空
402	密码不能为空
404	模板ID不能为空或模板ID不存在
405	用户名或密码不正确
4050	账号被冻结

9、生成动态密码方式

以PHP为例，提交短信验证码的生成方式：

    $time = time();
    $password = md5($account.$apikey.$mobile.$content.$time);

例如：

    APIID： test
    APIKEY：1q784322ba1d9bb88d50cf5cdfd89k7d
    手机号：138xxxxxxxx
    内容：您的验证码是：2546。请不要把验证码泄露给其他人。
    time：1451544941
    结果：$password=md5('test1q784322ba1d9bb88d50cf5cdfd89k7d138xxxxxxxx 您的 验证码是:2546。请不要把验证码泄露给其他人。1451544941');

注意:因为短信内容会包含中文，所以字符编码统一为 UTF-8

查询剩余条数的生成方式：

    $time = time();
    $password = md5($account.$apikey.$time);

例如：

    APIID： test
    APIKEY：1q784322ba1d9bb88d50cf5cdfd89k7d
    手机号：138xxxxxxxx
    time：1451544941
    结果：$password=md5('test1q784322ba1d9bb88d50cf5cdfd89k7d1451544941');

Unix时间戳参考地址：http://tool.chinaz.com/Tools/unixtime.aspx

10、常见问题

10.1 如何处理乱码

说明: 将短信内容( content)进行 UTF-8 编码后提交。

PHP 乱码:

$content = iconv("GBK","UTF-8",$content);

JAVA 乱码:

sb.append("&content="+URLEncoder.encode(content,"UTF-8"));

C#乱码:

byte[] bTemp = System.Text.Encoding.GetEncoding("GBK").GetBytes(sbTemp.ToString());

10.2 如何实现 UNIX 时间戳

语言	代码
JAVA	String date = new java.text.SimpleDateFormat("dd/MM/yyyy HH:mm:ss").format(new java.util.Date(Unix timestamp *1000))
Linux	date -d @Unix timestamp
C	strptime(datetime, "%Y-%m-%d %H:%M:%S", &tm_time); unixtime = mktime(&tm_time);
C++	std::time_t t = std::time(0);
DELPHI	uses DateUtils; DateTimeToUnix(Now)
GO	import "time" cur := time.Now() timestamp := cur.UnixNano() / 1000000
Perl	先 my $time = Unix timestamp 然后 my ($sec, $min, $hour, $day, $month, $year) = (localtime($time))[0,1,2,3,4,5,6]
PHP	date('r', Unix timestamp)
Node.js	var date = new Date( time * 1000 ); var time = date.getTime()/1000;
Python	先 import time 然后 time.gmtime(Unix timestamp)
Ruby	Time.at(Unix timestamp)
SHELL	date +%s //UNIX 的时间戳;
VBScript / ASP	DateAdd("s", Unix timestamp, "01/01/1970 00:00:00")
VB6	DateDiff("s", "1970-1-1 0:0:0", ToUnixTime)
易语言	时间_到时间戳()

使用指南

使用指南