功能示例 / Example
验证码【变量】,您正在注册成为【变量】用户,感谢您的支持!
验证码【变量】,您正在注册成为新用户,感谢您的支持!
![验证码短信](/images/code_sms.png)
开发流程 / Process
-
注册开发者账号
-
免费测试短信发送
-
购买短信套餐
-
快速调用接口
-
完成开发
接口介绍 / Introduction
-
轻松开发
支持HTTPS、CMPP、SMPP协议标准,提供多种开发语言文档
-
稳定发送
智能运维系统实时监控,一主四备短信通道,保障超高到达率
-
专业服务
7*24小时售后服务,专业运维实时监控
应用场景 / Scenes
-
用户注册/登录
适用于登录/注册等需要身份校验的场景,快速高效地保护用户信息财产安全
-
支付校验
适用于线上支付环节,有效确保用户支付安全
-
账号绑定
适用于网站/APP的身份校验场景,简单高效地维护企业账号体系安全
- 概要
- 短信发送
- 余额查询
- 发送回执推送
- 上行回复推送
- 提交模板
- 生成动态密码
- 常见问题
- 短信插件
1、概要
1.1 文档说明
本文档主要提供给互亿平台的用户对接接口的使用说明,开发者可以利用 ihuyi 提供的 HTTP 接口,调用 ihuyi 的短信验证码/通知服务。
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 方式进行短信提交,数据编码采用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,支持 300 个字的长短信,长短信 按多条计费) 例如:您的验证码是: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
用户名或密码不正确 0
2.5 响应参数
code | msg |
0 | 提交失败 |
2 | 提交成功 |
400 | 非法ip访问 |
401 | 帐号不能为空 |
402 | 密码不能为空 |
403 | 手机号码不能为空 |
4030 | 手机号码已被列入黑名单 |
404 | 短信内容不能为空 |
405 | API ID 或 API KEY 不正确 |
4050 | 账号被冻结 |
40501 | 动态密码已过期 |
40502 | 动态密码校验失败 |
4051 | 剩余条数不足 |
4052 | 访问 ip 与备案 ip 不符 |
406 | 手机格式不正确 |
407 | 短信内容含有敏感字符 |
4070 | 签名格式不正确 |
4071 | 签名格式不正确 |
4072 | 签名格式不正确 |
40722 | 变量内容超过指定的长度【8】 |
4073 | 短信内容超出长度限制 |
4074 | 短信内容包含 emoji 符号 |
4075 | 签名未通过审核 |
408 | 发送超限([20]条),已加入黑名单,可登入平台解除 |
4080 | 同一手机号码同一秒钟之内发送频率不能超过 1 条 |
4082 | 超出同一手机号一天之内【5】条短信限制 |
4085 | 同一手机号验证码短信发送超出【5】条 |
2.6 请求示例
http://106.ihuyi.com/webservice/sms.php?method=Submit&account=APIID&password=APIKEY&mobile=手机号码&content=您的验证码是:1234。请不要把验证码泄露给其他人。
3、余额查询
3.1 接口描述
通过接口可以方便的查询你的账户验证码通知短信剩余条数。
3.2 请求地址
http://106.ihuyi.com/webservice/sms.php?method=GetNum
3.3 请求参数
参数名称 | 参数值描述 | 是否必填 |
account | APIID(请登录用户中心【验证码通知短信】-【产品纵览】查看) | 是 |
password | 1、APIKEY(请登录用户中心【验证码通知短信】-【产品纵览】查看) 2、动态密码(生成动态密码方式请看该文档末尾的说明) |
是 |
time | Unix时间戳(10位整型数字,当使用动态密码方式时为必填) | 否 |
format | 返回格式(可选值为:xml或json,系统默认为xml) | 否 |
用户通过http 或 https提交帐户余额查询请求到服务器后,服务器会返回一串xml格式的字符串,GetNumResult结构说明如下:
参数名称 | 类型 | 描述 |
code | int | 状态返回值 |
msg | string | 查询结果描述 |
num | string | 剩余数量 |
3.4 响应示例
示例(成功)
2
查询成功 856
示例(失败)
405
用户名或密码不正确 0
3.5 响应参数
code | msg |
2 | 查询成功 |
400 | 非法ip访问 |
401 | 帐号不能为空 |
402 | 密码不能为空 |
405 | 用户名或密码不正确 |
4050 | 账号被冻结 |
3.6 GET请求示例
http://106.ihuyi.com/webservice/sms.php?method=GetNum&account=APIID&password=APIKEY
4、发送回执推送
4.1 接口描述
用户先提供数据接收地址,然后绑定到互亿无线系统后台,平台会以POST方式实时的将回执信息推送到此地址。
4.2 推送参数
参数名称 | 参数值描述 |
code | 状态值(2成功 其他为失败) |
msg | 回执状态说明 |
mobilephone | 手机号码 |
smsid | 流水号(对应提交时返回的smsid) |
report_time | 回执时间 例:2017-08-02 14:31:51 |
注意: 成功接收请输出字符 “success” (不包含引号)结束推送,否则以接收失败处理。 每个回执最多推送 3 次。每次间隔叠加 60 秒。
5、上行回复推送
5.1 接口描述
用户先提供数据接收地址,然后绑定到互亿无线系统后台,平台会以 POST 方式实时的将 回复信息推送到此地址。
5.2 推送参数
参数名称 | 参数值描述 |
mobilephone | 手机号码 |
content | 上行内容 |
smsid | 流水号(对应提交时返回的 smsid)(仅作参考) |
reply_time | 上行时间 例:2017-05-24 17:46:50 |
注意: 成功接收请输出字符 “success” (不包含引号)结束推送,否则以接收失败处理。每个回执最多推送 3 次。每次间隔叠加 60 秒。
6、提交模板
6.1 接口描述
通过 POST、 GET 方式提交短信模版,数据编码采用 utf-8 格式,24 小时全天发送。
6.2 请求地址
http://106.ihuyi.com/webservice/sms.php?method=AddTemplate&account=APIID&password=APIKEY&content=您的验证码是:【变量】。请不要把验证码泄露给其他人。
6.3 请求参数
参数名称 | 参数值描述 |
method | AddTemplate |
account | 提交账户 |
password | 提交账户密码 (可以明文密码或使用 32 位 MD5 加密) |
模板内容 | 模板内容 |
返回值 AddTemplateResult 结构说明:
参数名称 | 类型 | 描述 |
code | int | 返回值为 2 时,表示添加成功 |
msg | string | 提交状态描述 |
templateid | int | 添加成功则返回模板 ID |
6.4 响应参数
code | msg |
2 | 添加成功 |
400 | 提交状态描述 |
401 | 添加成功则返回模板 ID |
402 | 密码不能为空 |
404 | 模板内容不能为空 |
405 | 用户名或密码不正确 |
4050 | 账号被冻结 |
407 | 模板内容含有敏感字符 |
6.5 模板审核状态推送
在遵守 HTTP 协议规范的前提下,通过 POST 方式将回执推送到用户指定的 URL 地址。
参数说明:
参数名称 | 参数值描述 |
code | 状态值(2 成功 0 驳回) |
msg | 审核状态描述 |
templateid | 模板 ID |
注意:
1.成功接收请输出字符 “success” (不包含引号)结束推送,否则以接收失败处理。
2.每个回执最多推送 3 次。每次间隔叠加 60 秒。
3.code 值说明
2 成功
0 驳回(原因请看 msg 字段)
7、生成动态密码方式
以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
8、常见问题
8.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());
8.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) |
易语言 | 时间_到时间戳() |
9、短信插件
短信发送错误码参照:
code | msg |
0 | 提交失败 |
2 | 提交成功 |
400 | 非法ip访问 |
401 | 帐号不能为空 |
402 | 密码不能为空 |
403 | 手机号码不能为空 |
4030 | 手机号码已被列入黑名单 |
404 | 短信内容不能为空 |
405 | API ID 或 API KEY 不正确 |
4050 | 账号被冻结 |
40501 | 动态密码已过期 |
40502 | 动态密码校验失败 |
4051 | 剩余条数不足 |
4052 | 访问 ip 与备案 ip 不符 |
406 | 手机格式不正确 |
407 | 短信内容含有敏感字符 |
4070 | 签名格式不正确 |
4071 | 签名格式不正确 |
4072 | 签名格式不正确 |
40722 | 变量内容超过指定的长度【8】 |
4073 | 短信内容超出长度限制 |
4074 | 短信内容包含 emoji 符号 |
4075 | 签名未通过审核 |
408 | 发送超限([20]条),已加入黑名单,可登入平台解除 |
4080 | 同一手机号码同一秒钟之内发送频率不能超过 1 条 |
4082 | 超出同一手机号一天之内【5】条短信限制 |
4085 | 同一手机号验证码短信发送超出【5】条 |
余额查询错误码参照:
code | msg |
2 | 查询成功 |
400 | 非法ip访问 |
401 | 帐号不能为空 |
402 | 密码不能为空 |
405 | 用户名或密码不正确 |
4050 | 账号被冻结 |
提交模板错误码参照:
code | msg |
2 | 添加成功 |
400 | 提交状态描述 |
401 | 添加成功则返回模板 ID |
402 | 密码不能为空 |
404 | 模板内容不能为空 |
405 | 用户名或密码不正确 |
4050 | 账号被冻结 |
407 | 模板内容含有敏感字符 |
代码示例
常见问题
客户服务
内容 | 联系方式 |
400热线 | 400-880-8898 |
联系电话 | 021-5169 8929 |
邮箱 | service@ihuyi.com |
邮政编码 | 201203 |
市场合作/渠道代理
内容 | 联系方式 |
联系电话 | 15902129325 |
邮箱 | linsn@ihuyi.com |
技术支持
内容 | 联系方式 |
联系电话 | 4008 808 898 |
邮箱 | support@ihuyi.com |
公司地址
内容 | 联系方式 |
上海总公司 | 上海市浦东新区纳贤路800号A座401 |
南京分公司 | 南京市秦淮区瞻园路19号 |
成都分公司 | 中国(四川)自由贸易试验区成都高新区天府街69号 |