短信验证码接口API文档
1、概要
本文档主要提供给互亿平台的用户对接短信验证码接口的使用说明，开发者可以利用接口调用短信验证码服务。接口包含短信发送、余额查询、发送回执推送、上行回复推送等能力。
API ID / API KEY获取方式：
登录用户中心，进入【验证码通知短信】模块，在【产品总揽】页面右上角，如下图所示：
1.6 短信模版
短信模板是对您将要发送的短信进行相似性提取后的内容。举个例子，
| A 用户在您平台注册会员，需要发送一条短信，内容如下: |
| 您好，您的验证码是：666666 |
| 同时，B 用户也在您的平台注册会员，发送了如下短信: |
| 您好，您的验证码是：888888 |
| 我们提取相似度以后，可以制作以下短信模板: |
| 您好，您的验证码是：【变量】 |
| 其中，变量是可变的，可以是 数字、字母、汉字。 |
注意:未付费用户仅可使用默认短信模板（您的验证码是：【变量】。请不要把验证码泄露给其他人。），付费用户可以通过左侧导航【验证码通知短信】 -【短信发送】-【签名/模版管理】新增短信模板，运营商审核通过之后即可正式使用。
2、短信单条发送
2.1 接口描述
短信接口支持两种提交方式，用户可根据实际需求任选其一：
- 完整内容方式（推荐）：直接传递完整的短信内容进行发送。
- 模板变量方式：使用预设模板，通过模板ID和变量实现短信发送，更便捷且更安全。
请求支持 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 | 接收短信的手机号码，每次只能提交一个号码 | 是 |
| templateid | 短信模板ID（使用模板变量方式发送时必填） 调试阶段可使用系统默认模板ID：1（模板内容为：您的验证码是：【变量】。请不要把验证码泄露给其他人。） |
否（使用模板变量方式时为必填） |
| content | 根据发送方式不同： 1、完整内容方式 提交完整的短信内容，如：您的验证码是：1234。请不要把验证码泄露给其他人。 2、模板变量方式 模板中的变量内容，多个变量以英文竖线（|）隔开 ①单变量示例 模板内容：您的验证码是：【变量】。请不要把验证码泄露给其他人。 参数写法：content=1234 最终短信为：您的验证码是：1234。请不要把验证码泄露给其他人。 ②多变量示例 模板内容：订单号：【变量1】，联系人：【变量2】，手机号：【变量3】，金额：【变量4】。 参数写法：content=20180515006|张三|136xxxxxxxx|100元 最终短信为：订单号：20180515006，联系人：张三，手机号：136xxxxxxxx，金额：100元。 支持500字以内的长短信，长短信按多条计费 |
是 |
| time | Unix时间戳（10位整型数字，使用动态密码方式时必填） | 否 |
| format | 返回数据格式（可选值：xml 或 json，默认xml） | 否 |
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 请求示例
（1）完整内容方式示例（推荐）：
https://106.ihuyi.com/webservice/sms.php?method=Submit&account=APIID&password=APIKEY&mobile=手机号码&content=您的验证码是：1234。请不要把验证码泄露给其他人。
（2）模板变量方式示例：
https://106.ihuyi.com/webservice/sms.php?method=Submit&account=APIID&password=APIKEY&mobile=手机号码&templateid=1&content=1234
示例中使用默认模板（ID=1），内容为：“您的验证码是：【变量】。请不要把验证码泄露给其他人。”
如使用自定义模板，模板含多个变量时，content需以竖线 | 隔开，如下所示：
https://106.ihuyi.com/webservice/sms.php?method=Submit&account=APIID&password=APIKEY&mobile=手机号码&templateid=144219&content=20180515006|张三|136xxxxxxxx|100元
请注意模板中变量与传入参数必须一一对应。
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时，表示提交成功 |
| batchid | string | 流水号（对应提交时返回的batchid） |
| 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） |
| batchid | 批量发送流水号（对应提交时返回的batchid） |
| report_time | 回执时间 例:2017-08-02 14:31:51 |
注意:
1、如多条批量发送，则会额外返回batchid。
2、成功接收请输出字符 “success” (不包含引号)结束推送，否则以接收失败处理。 每个回执最多推送 3 次。每次间隔叠加 60 秒。
6、上行回复推送
6.1 接口描述
用户先提供数据接收地址，然后绑定到互亿无线系统后台，平台会以 POST 方式实时的将 回复信息推送到此地址。
6.2 推送参数
| 参数名称 | 参数值描述 |
| mobilephone | 手机号码 |
| content | 上行内容 |
| smsid | 流水号(对应提交时返回的 smsid)(仅作参考) |
| batchid | 批量发送流水号（对应提交时返回的batchid） |
| reply_time | 上行时间 例:2017-05-24 17:46:50 |
注意:
1、如多条批量发送，则会额外返回batchid。
2、成功接收请输出字符 “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 | 模板内容 |
| content2 | 实际发送的内容（示例） |
| type | 1验证码 2通知 |
| scene | 使用场景 |
返回值 AddTemplateResult 结构说明:
| 参数名称 | 类型 | 描述 |
| code | int | 返回值为 2 时，表示添加成功 |
| msg | string | 提交状态描述 |
| templateid | int | 添加成功则返回模板 ID |
7.4 响应参数
| code | msg |
| 2 | 添加成功 |
| 400 | 非法ip访问 |
| 401 | 用户名不能为空 |
| 402 | 密码不能为空 |
| 404 | 模板内容不能为空 |
| 4041 | 模板内容长度不符合（15-500个字符） |
| 4042 | 使用场景长度为50个字符以内 |
| 4043 | 实际发送的内容（示例）不能为空 |
| 4044 | 实际发送的内容（示例）长度不符合（15-500个字符） |
| 405 | 用户名或密码不正确 |
| 4050 | 账号被冻结 |
| 406 | 未充值不能提交模板 |
| 4066 | 添加太频繁，支持1分钟10次请求 |
| 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
