本文档主要提供给互亿平台的用户对接接口的使用说明,开发者可以利用 ihuyi 提供的 HTTP 接口,调用 ihuyi 的短信验证码/通知服务。
本文档包含短信发送、余额查询、发送回执推送、上行回复推送等。
GET / POST
1、采用HTTPS协议提交请求
2、通过MD5动态签名方式加密
登录用户中心,进入【验证码通知短信】模块,在【产品总揽】页面右上角,如下图所示:
短信模板是对您将要发送的短信进行相似性提取后的内容。举个例子,
A 用户在您平台注册会员,需要发送一条短信,内容如下: |
您好,您的验证码是:666666 |
同时,B 用户也在您的平台注册会员,发送了如下短信: |
您好,您的验证码是:888888 |
我们提取相似度以后,可以制作以下短信模板: |
您好,您的验证码是:【变量】 |
其中,变量是可变的,可以是 数字、字母、汉字。 |
注意:未付费用户仅可使用默认短信模板(您的验证码是:【变量】。请不要把验证码泄露给其他人。),付费用户可以通过左侧导航【验证码通知短信】 -【短信发送】-【签名/模版管理】新增短信模板,运营商审核通过之后即可正式使用。
短信签名是加在短信的开头或结尾,在【】加上您的公司名称或店铺名称的标识符,例如:【互亿无线】。 根据电信基础运营商的规定,每条短信必须附加短信签名,否则将无法正常发送。
注意:未付费用户仅可使用默认短信签名【互亿无线】,付费用户可以通过点击左侧导航【验证码通知短信】-【短信发送】-【签名/模版管理】修改签名,运营商审核通过之后即可正式使用。
通过POST、 GET 方式进行短信提交,内容格式为:Content-Type: application/x-www-form-urlencoded,数据编码采用utf-8格式,24小时全天发送。
https://106.ihuyi.com/webservice/sms.php?method=Submit
参数名称 | 参数值描述 | 必填 |
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
提交成功 14745625541233112231
示例(失败)
405
account或password不正确 0
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】条 |
http://106.ihuyi.com/webservice/sms.php?method=Submit&account=APIID&password=APIKEY&mobile=手机号码&content=您的验证码是:1234。请不要把验证码泄露给其他人。
通过POST方式进行短信提交,内容格式为:Content-Type: application/x-www-form-urlencoded,数据编码采用utf-8格式,24小时全天发送。
https://106.ihuyi.com/webservice/sms.php?method=SubmitBatch
参数名称 | 参数值描述 | 必填 |
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时,表示提交成功 |
batchid | string | 流水号(对应提交时返回的batchid) |
msg | string | 回执状态说明 |
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 | 计费错误 |
1、不含变量
手机号格式: 号码之间使用英文逗号隔开,如:136xxxx1111,136xxxx2222,136xxxx3333
模板ID: 对应您在平台报备过的模板ID,如:624452
模板内容:您有新的订单,请注意查收。
2、含变量
手机号格式: 变量之间用半|符号隔开,如:136xxxx1111|11111111|菜鸟,136xxxx2222|22222222|京东,136xxxx3333|3333333333|顺丰
模板ID: 对应您在平台报备过的模板ID,如:624452
模板内容:您的订单号是:【变量】。已由【变量】快递发出,请注意查收。
注意:
单次提交最少2个号码,最多5000个号码
模板ID和模板内容二选一,如果传模板内容或者号码数量超过500都会进入人工审核流程。
通过POST、 GET 方式查询你的账户验证码通知短信剩余条数,内容格式为:Content-Type: application/x-www-form-urlencoded,数据编码采用utf-8格式。
http://106.ihuyi.com/webservice/sms.php?method=GetNum
参数名称 | 参数值描述 | 是否必填 |
account | APIID(请登录用户中心【验证码通知短信】-【产品总览】查看) | 是 |
password | 1、APIKEY(请登录用户中心【验证码通知短信】-【产品总览】查看) 2、动态密码(生成动态密码方式请看该文档末尾的说明) |
是 |
time | Unix时间戳(10位整型数字,当使用动态密码方式时为必填) | 否 |
format | 返回格式(可选值为:xml或json,系统默认为xml) | 否 |
用户通过http 或 https提交帐户余额查询请求到服务器后,服务器会返回一串xml格式的字符串,GetNumResult结构说明如下:
参数名称 | 类型 | 描述 |
code | int | 状态返回值 |
msg | string | 查询结果描述 |
num | string | 剩余数量 |
示例(成功)
2
查询成功 856
示例(失败)
405
account或password不正确 0
code | msg |
2 | 查询成功 |
400 | 非法ip访问 |
401 | 帐号不能为空 |
402 | 密码不能为空 |
405 | 用户名或密码不正确 |
4050 | 账号被冻结 |
http://106.ihuyi.com/webservice/sms.php?method=GetNum&account=APIID&password=APIKEY
用户先提供数据接收地址,然后绑定到互亿无线系统后台,平台会以POST方式实时的将回执信息推送到此地址,内容格式为:Content-Type: application/x-www-form-urlencoded。
参数名称 | 参数值描述 |
code | 状态值(2成功 其他为失败) |
msg | 回执状态说明 |
mobilephone | 手机号码 |
smsid | 单条发送流水号(对应提交时返回的smsid) |
batchid | 批量发送流水号(对应提交时返回的batchid) |
report_time | 回执时间 例:2017-08-02 14:31:51 |
注意:
1、如多条批量发送,则会额外返回batchid。
2、成功接收请输出字符 “success” (不包含引号)结束推送,否则以接收失败处理。 每个回执最多推送 3 次。每次间隔叠加 60 秒。
用户先提供数据接收地址,然后绑定到互亿无线系统后台,平台会以 POST 方式实时的将 回复信息推送到此地址。
参数名称 | 参数值描述 |
mobilephone | 手机号码 |
content | 上行内容 |
smsid | 流水号(对应提交时返回的 smsid)(仅作参考) |
batchid | 批量发送流水号(对应提交时返回的batchid) |
reply_time | 上行时间 例:2017-05-24 17:46:50 |
注意:
1、如多条批量发送,则会额外返回batchid。
2、成功接收请输出字符 “success” (不包含引号)结束推送,否则以接收失败处理。每个回执最多推送 3 次。每次间隔叠加 60 秒。
通过 POST、 GET 方式提交短信模版,内容格式为:Content-Type: application/x-www-form-urlencoded,数据编码采用 utf-8 格式。
http://106.ihuyi.com/webservice/sms.php?method=AddTemplate&account=APIID&password=APIKEY&content=您的验证码是:【变量】。请不要把验证码泄露给其他人。
参数名称 | 参数值描述 |
method | AddTemplate |
account | 提交账户 |
password | 提交账户密码 (可以明文密码或使用 32 位 MD5 加密) |
content | 模板内容 |
type | 1验证码 2通知 |
scene | 使用场景 |
返回值 AddTemplateResult 结构说明:
参数名称 | 类型 | 描述 |
code | int | 返回值为 2 时,表示添加成功 |
msg | string | 提交状态描述 |
templateid | int | 添加成功则返回模板 ID |
code | msg |
2 | 添加成功 |
400 | 非法ip访问 |
401 | 用户名不能为空 |
402 | 密码不能为空 |
404 | 模板内容不能为空 |
405 | 用户名或密码不正确 |
4050 | 账号被冻结 |
407 | 模板内容含有敏感字符 |
408 | 模板己存在 |
在遵守 HTTP 协议规范的前提下,通过 POST 方式将回执推送到用户指定的 URL 地址。
参数说明:
参数名称 | 参数值描述 |
code | 状态值(2 成功 0 驳回) |
msg | 审核状态描述 |
templateid | 模板 ID |
注意:
1.成功接收请输出字符 “success” (不包含引号)结束推送,否则以接收失败处理。
2.每个回执最多推送 3 次。每次间隔叠加 60 秒。
3.code 值说明
2 成功
0 驳回(原因请看 msg 字段)
通过POST、 GET 方式提交短信模版,内容格式为:Content-Type: application/x-www-form-urlencoded,数据编码采用utf-8格式。
http://106.ihuyi.com/webservice/sms.php?method=DelTemplate&account=APIID&password=APIKEY&templateid=123
参数名称 | 参数值描述 |
method | DelTemplate |
account | 提交账户 |
password | 提交账户密码 (可以明文密码或使用 32 位 MD5 加密) |
templateid | 模板id |
返回值 AddTemplateResult 结构说明:
参数名称 | 类型 | 描述 |
code | int | 返回值为 2 时,表示删除成功 |
msg | string | 提交状态描述 |
code | msg |
2 | 删除成功 |
400 | 非法ip访问 |
401 | 用户名不能为空 |
402 | 密码不能为空 |
404 | 模板ID不能为空或模板ID不存在 |
405 | 用户名或密码不正确 |
4050 | 账号被冻结 |
以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
说明: 将短信内容( 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());
语言 | 代码 |
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) |
易语言 | 时间_到时间戳() |
互亿无线提供各种语言的短信接口DEMO,详情请点击:短信验证码/通知短信接口示例
互亿无线提供近百种主流系统的短信插件,能帮助你快速接入验证码短信,详情请点击:短信验证码插件
提供验证码通知短信接入、使用中的常见问题,请点击浏览
自助开通验证码/通知短信接口
开通即赠免费试用短信,免费试用不限时长
短信套餐报价 免费开通试用账户 验证码通知短信产品介绍
验证码已发送到您的手机,请查收!
输入验证码后,点击“开通体验账户”按钮可立即开通体验账户。