智码验证码批量业务API接口说明
最近修订日期：2018年5月13日
版本 v3.1.1
·1、接口请求说明
接口基地址：http://xunyaosoft.com/zsmcode/
编码：UTF-8
请求方式：HTTP GET
说明：所有请求以.php结尾
·1.1、注意事项
1、使用批量接口请求前请先在智码APP申请开发资格，系统会根据您的申请为您生成开发密钥，开发密钥是您请求数据的唯一凭据。
2、所有请求均只支持GET请求方式。
3、请求号码并使用后请主动释放，没主动释放的号码，系统会在10分钟内强制释放。
4、SESSION有效期为15分钟，如果SESSION失效，请重新验证密钥。
5、所有接口返回值都为STRING格式。
·2、验证密钥
地址：http://xunyaosoft.com/zsmcode/pkey/verification.php
功能：用于其他所有接口调用前的合法性开发者验证，只有验证通过的用户才是有效的开发者，才能进行后续接口调用。
·2.1、参数
| 名称 | 是否必须 | 缺省 | 描述 |
|---|---|---|---|
| account | 是 | 开发者账号 | |
| pkey | 是 | 申请开发者账号时设置的密钥 |
·2.2、返回值
| 名称 | 值 | 是否必定返回 | 描述 |
|---|---|---|---|
| valid | Y/N | 是 | 是否验证通过。Y：验证通过；N：验证不通过。 |
| leftQuantity | 整数，比如158 | 否 | 短信剩余数量，valid为Y时返回 |
| msg | 请求错误信息，比如“账户异常” | 否 | valid为N时返回此字段，描述错误信息 |
·2.3、备注
账户状态正常且密钥验证通过时，可在此SESSION中进行之后的各种操作。否则需要根据错误提示信息进行重新验证。
·3、获取项目信息
地址：http://xunyaosoft.com/zsmcode/items/details.php
功能：获取项目的当前可用信息、价格信息等。
·3.1、参数
| 名称 | 是否必须 | 缺省 | 描述 |
|---|---|---|---|
| itemId | 是 | 项目编号 |
·3.2、返回值
| 名称 | 值 | 是否必定返回 | 描述 |
|---|---|---|---|
| name | 项目名称 | 特殊可选 | 与itemId对应的项目的名称 |
| status | 项目状态 | 是 | 1-正常，2-已过期，3-其他异常 |
| price | 单条价格 | 特殊可选 | 格式：0.1(10000), 0.01(10001-30000), 0.08(+) 价格区间以“,”分开，“+”代表剩余所有段。 |
| type | 项目类型 | 特殊可选 | 1-每次请求只能获取一条 2-每次请求可以获取多条 3-可发送一条 4-可发送多条 5-可收发多条 6-可收发多条 |
| msg | 错误信息 | 否 | 比如“项目编号不存在”，status不为1时有效 |
·3.3、备注
可选接口，并非每次获使用短信都要调用。
·4、获取号码
地址：http://xunyaosoft.com/zsmcode/phoneNos/get.php
功能：获取随机或指定手机号码，是下一步接收短信的前提。
·4.1、参数
| 名称 | 是否必须 | 缺省 | 描述 |
|---|---|---|---|
| itemId | 是 | 项目编号 | |
| quantity | 是 | 1 | 本次获取数量 |
| phoneNo | 否 | 获取并锁定指定号码，不填则获取随机号码。 | |
| areaCode | 否 | 归属地编号，不填则随机归属地 | |
| international | 否 | N | Y-获取国际号码，不支持指定国家和区域。N-不获取国际号码。 |
| type | 否 | 运营商，国内号码可选：1-中国移动 2-中国联通 3-中国电信。不填则随机。 |
·4.2、返回值
| 名称 | 值 | 是否必定返回 | 描述 |
|---|---|---|---|
| phoneNos | 返回的号码 | 特殊可选 | 返回的号码。多个号码时以半角逗号“,”隔开。 |
| msg | 异常信息 | 否 | 比如“号码余量不足” |
·4.3、备注
如果没有返回请，请处理错误信息后重试。
·5、获取短信
地址：http://xunyaosoft.com/zsmcode/sms/get.php
功能：根据提交的项目编号和号码获取短信，从而进行下一步操作，比如读取验证码。
·5.1、参数
| 名称 | 是否必须 | 缺省 | 描述 |
|---|---|---|---|
| itemId | 是 | 项目编号 | |
| phoneNo | 是 | 要获取信息的手机号 |
·5.2、返回值
| 名称 | 值 | 是否必定返回 | 描述 |
|---|---|---|---|
| sm | 接收短信的内容 | 否 | 获取的对应号码短信内容。 |
| status | 接收状态 | 否 | 1-接收中 2-已接收 3-消息丢失 4-接收超时 5-其他错误 |
| msg | 异常信息 | 否 | 如果有异常信息则通过此字段返回。 |
·5.3、备注
建议每5秒请求一次，直到status不为1为止。
·6、发送短信与状态查询
地址：http://xunyaosoft.com/zsmcode/sms/send.php
功能：用于对指定项目指定号码发送短信，并用于查询发送状态。
·6.1、参数
| 名称 | 是否必须 | 缺省 | 描述 |
|---|---|---|---|
| itemId | 是 | 项目编号 | |
| phoneNo | 是 | 手机号 | |
| smcontent | 否 | 要发送的内容，querys为N时不能为空。 | |
| querys | 否 | N | Y-查询发送状态，N-发送短信。 |
·6.2、返回值
| 名称 | 值 | 是否必定返回 | 描述 |
|---|---|---|---|
| msg | 发送结果信息 | 是 | 为OK则说明发送成功，否则为异常信息。 |
·6.3、备注
查询是否发送成功，请将参数querys赋值为Y请求查询状态。
·7、释放手机号
地址：http://xunyaosoft.com/zsmcode/sms/release.php
功能：用于释放指定的号码。用过的号码释放后可以进行后续使用，适用于支持一手机号绑定多个账户的项目。
·7.1、参数
| 名称 | 是否必须 | 缺省 | 描述 |
|---|---|---|---|
| phoneNo | 是 | 项目编号 | |
| phoneNo | 是 | 要释放的号码，多个号码用半角逗号“,”隔开。 | |
| itemId | 否 | 要释放的号码所在的项目。如果为空，则释放在所有项目中的锁定。 |
·7.2、返回值
| 名称 | 值 | 是否必定返回 | 描述 |
|---|---|---|---|
| msg | 释放信息 | 是 | 值为OK时释放成功，否则请根据返回信息判断异常。 |
·7.3、备注
不同项目号码释放时请分开进行。
·8、释放所有号码
地址：http://xunyaosoft.com/zsmcode/sms/releaseAll.php
功能：释放所有的号码，包括同一开发者请求过的所有的号码。
·8.1、参数
| 名称 | 是否必须 | 缺省 | 描述 |
|---|---|---|---|
·8.2、返回值
| 名称 | 值 | 是否必定返回 | 描述 |
|---|---|---|---|
| msg | 释放信息 | 是 | 值为OK时释放成功，否则请根据返回信息判断异常。 |
·8.3、备注
使用过的号码如果没有被及时释放，系统会在30分钟后自动释放。
·9、加入黑名单
地址：http://xunyaosoft.com/zsmcode/sms/block.php
功能：将号码加入黑名单。加入黑名单的号码不会再在此项目中出现，避免重复获取。适用于使用手机号码注册的情况。
·9.1、参数
| 名称 | 是否必须 | 缺省 | 描述 |
|---|---|---|---|
| itemId | 是 | 项目编号 | |
| phoneNo | 是 | 要加入黑名单的号码。 |
·9.2、返回值
| 名称 | 值 | 是否必定返回 | 描述 |
|---|---|---|---|
| msg | 加入黑名单信息 | 是 | 值为OK时加入黑名单成功，否则请根据返回信息判断异常。 |
·9.3、备注
加入黑名单后在指定项目中将无法再请求到此号码，请慎重操作。