信信客短信接入指南

信信客短信通道 API 接口是面向有一定技术开发能力的企业或者个人用户而单独研发的短信通道通讯协议。本接口采用了通用的 HTTP 形式，支持 GET 或者 POST 方式接入，可以支持各种操作系统和开发语言，为您提供了 ASP 、 ASP.net 、 Java 、 PHP 、 C#等语言的例子代码，在您注册了平台账号后获得开发者标识即可通过简单的调试后，把短信通道接口嵌入到您自己的系统中，快速拥有无线应用，完善您的企业服务！

准备工作接入前请在“开发者设置”中设置“开发者状态”为“启用”，并获取“开发者标识”和“开发者密钥”。为保证信息安全，切勿将开发者信息告知他人。
调用流程根据接口约定：填充参数 > 生成签名 > 拼装 HTTP 请求 > 发起 HTTP 请求 > 得到 HTTP 响应 > 解析 JSON 结果。
公共参数调用任何一个 API 接口都必须传入的参数，目前的公共参数有：参数名称参数类型是否必须参数描述 dev_id String 必须开发者标识 sign String 必须参数签名参数说明：
参数签名：为防止 API 调用过程中被恶意篡改，调用任何一个 API 都需要携带签名，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。
接口调用 4.1 短信发送接口接口地址 http://www.xinxinke.com/api/send 调用方式 GET, POST 4.1.1 短信发送请求参数名称参数类型是否必须参数描述 dev_id String 必须开发者标识 sign String 必须参数签名 sms_template_code String 必须短信模板代码 sms_param JSON 可选短信模板变量 rec_num String 必须接收号码 ext_num Number 可选扩展子号参数说明：
参数签名：算法 md5(dev_id + dev_key + rec_num)。示例： md5("b7d5107d782d4033v35047d4a448089b" + "e35c7a885v0144e79ef9541a36382f21" + "13800138000,18900189000,18600186000")
短信模板变量：传参规则{"key":"value"}， key 的名字须和申请模板中的变量名一致，多个变量之间以逗号隔开。示例：针对模板“验证码${code}，您正在进行${product}身份验证，打死不要告诉别人哦！”，传参时需传入{"code":"1234","product":"xinxinke"}
接收号码：支持单个或多个手机号码，传入号码为 11 位手机号码，以英文逗号分隔，一次调用最多传入 1000 个号码。示例： 13800138000,18900189000,18600186000 4.1.2 短信发送响应状态码描述 25010 正确 45001 非法 IP 45010 参数个数不合法 45020 开发者标识不合法 45030 参数签名(md5)格式不正确 45040 短信模板代码不合法 45050 扩展子号不合法 45060 接收号码不能为空 45070 不存在有效接收号码 45080 接收号码过多 45090 开发者状态异常 45100 短信签名不合法 45110 参数签名(md5)错误 45120 短信模板不存在 45130 短信模板状态异常 45140 短信参数不合法 45150 短信内容过长 45160 帐户余额不足 4.2 短信发送状态报告接口接口地址 http://www.xinxinke.com/api/report 调用方式 GET, POST 4.2.1 短信发送状态报告请求参数名称参数类型是否必须参数描述 dev_id String 必须开发者标识 sign String 必须参数签名 rec_num String 可选接收号码 index String 可选号码提交记录索引参数说明：
参数签名：算法 md5(dev_id + dev_key)。示例： md5("b7d5107d782d4033v35047d4a448089b" + "e35c7a885v0144e79ef9541a36382f21")
接收号码：传入号码为 11 位手机号码。示例： 13800138000 4.2.2 短信发送状态报告响应状态码描述 25010 正确 45001 非法 IP 45010 开发者标识不合法 45020 参数签名(md5)格式不正确 45030 接收号码不合法 45040 开发者状态异常 45050 参数签名(md5)错误 45060 号码提交记录索引不合法 4.3 短信接收接口接口地址 http://www.xinxinke.com/api/receive 调用方式 GET, POST 4.3.1 短信接收请求参数名称参数类型是否必须参数描述 dev_id String 必须开发者标识 sign String 必须参数签名 src_num String 可选发送号码参数说明：
参数签名：算法 md5(dev_id + dev_key)。示例： md5("b7d5107d782d4033v35047d4a448089b" + "e35c7a885v0144e79ef9541a36382f21")
发送号码：传入号码为 11 位手机号码。示例： 13800138000 4.3.2 短信接收响应状态码描述 25010 正确 45001 非法 IP 45010 开发者标识不合法 45020 参数签名(md5)格式不正确 45030 发送号码不合法 45040 开发者状态异常 45050 参数签名(md5)错误 4.4 短信模板接口接口地址 http://www.xinxinke.com/api/template 调用方式 GET, POST 4.4.1 短信模板请求参数名称参数类型是否必须参数描述 dev_id String 必须开发者标识 sign String 必须参数签名 action String 必须请求动作 sms_template_code String 区分动作模板代码 content String 区分动作模板内容参数说明：
请求动作：

查询： action = query ，模板代码为可选项
新增： action = create ，模板代码、模板内容为必须项
删除： action = delete ，模板代码为必须项

参数签名：

查询：算法 md5(dev_id + dev_key)。示例： md5("b7d5107d782d4033v35047d4a448089b" + "e35c7a885v0144e79ef9541a36382f21")
新增、删除：算法 md5(dev_id + dev_key + sms_template_code)。示例： md5("b7d5107d782d4033v35047d4a448089b" + "e35c7a885v0144e79ef9541a36382f21" + "dynamic_code") 4.4.2 短信模板响应状态码描述 25010 正确 45001 非法 IP 45010 开发者标识不合法 45020 参数签名(md5)格式错误 45030 模板代码格式错误 45040 模板内容格式错误 45050 开发者状态异常 45060 参数签名(md5)错误 45070 模板代码已存在 45080 待审核模板过多 45090 请求动作不合法 4.5 帐户信息查询接口接口地址 http://www.xinxinke.com/api/account 调用方式 GET, POST 4.5.1 帐户信息查询请求参数名称参数类型是否必须参数描述 dev_id String 必须开发者标识 sign String 必须参数签名参数说明：

参数签名：算法 md5(dev_id + dev_key)。示例： md5("b7d5107d782d4033v35047d4a448089b" + "e35c7a885v0144e79ef9541a36382f21") 4.5.2 帐户信息查询响应状态码描述 25010 正确 45001 非法 IP 45010 开发者标识不合法 45020 参数签名(md5)格式不正确 45030 开发者状态异常 45040 参数签名(md5)错误
调用示例请求： JAVA 示例(POST) import java.io.BufferedReader; import java.io.DataOutputStream; import java.io.InputStreamReader; import java.net.HttpURLConnection; import java.net.URL; import java.net.URLEncoder;

/**

接口测试
以下代码只是为了方便开发者测试而提供的样例代码，开发者可以根据自己的业务需要，按照技术文档编写，并非一定要使用该代码。
该代码仅供学习和研究信信客接口使用，只是提供一个参考。
@author chenfan
@version 1.0, 2015/10/07

*/ public class HTTPTest {

// 转码
public String encode(String input) throws Exception {
	return URLEncoder.encode(input, "UTF-8");
}

// 发起 POST 请求
public void post() throws Exception {

	// 参数拼装
	StringBuffer param = new StringBuffer();
	param.append("").append(encode("dev_id")).append("=").append(encode("sdded54uu9374b2it62e3e35271ec6eu"));
	param.append("&").append(encode("sign")).append("=").append(encode("se0vna60e4dd453e870ww67mwd6ee0vc"));

	// 打开连接
	URL url = new URL("http://www.xinxinke.com/api/account");
	HttpURLConnection conn = (HttpURLConnection) url.openConnection();
	conn.setDoOutput(true);
	conn.setDoInput(true);
	conn.setRequestMethod("POST");
	conn.setUseCaches(false);
	conn.connect();

	// 输出参数
	DataOutputStream dos = new DataOutputStream(conn.getOutputStream());
	dos.writeBytes(param.toString());
	dos.flush();
	dos.close();

	// 读取响应
	BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "UTF-8"));
	String line = br.readLine();
	br.close();

	// 关闭连接
	conn.disconnect();

	System.out.println(line);

}

public static void main(String[] args) throws Exception {
	HTTPTest t = new HTTPTest();
	t.post();
}

} 5.1 短信发送接口响应：成功示例 /**

返回参数说明
"index"：号码提交记录索引
"mobile"：短信接收号码（用来查询状态报告）

/ { "data" : { "message" : "提交成功", "mobiles" : [ { "index" : "146131537016435203", "mobile" : "13800138000" }, { "index" : "146131537017600000", "mobile" : "18600186000" }, { "index" : "146131537017988006", "mobile" : "18100181000" } ] }, "code" : "25010" } 响应：失败示例 { "data" : { "message" : "短信模板不存在 ", "mobiles" : "[]" }, "code" : "45120" } 5.2 短信发送状态报告接口响应：成功示例 /*

返回参数说明
"index"：状态报告记录索引
"status"：短信提交状态
"receiveMobile"：短信接收号码（与发送接口接收号码对应）
"receiveTime"：短信接收时间

/ { "data" : { "message" : "查询成功", "reports" : [ { "index" : "145949642039488565", "status" : "1", "receiveMobile" : "13800138000", "receiveTime" : "2016-04-05 15:57:01" } ] }, "code" : "25010" } 响应：失败示例 { "data" : { "message" : "开发者标识不合法", "reports" : "[]" }, "code" : "45010" } 5.3 短信接收接口响应：成功示例 /*

返回参数说明
"content"：短信内容
"to"：接收号码
"receiveTime"：接收时间
"from"：发送号码

/ { "data" : { "message" : "查询成功", "receives" : [ { "content" : "你好，信信客", "to" : "106905544", "receiveTime" : "2016-03-12 15:31:17", "from" : "13800138000" } ] }, "code" : "25010" } 响应：失败示例 { "data" : { "message" : "发送号码不合法", "receives" : "[]" }, "code" : "45030" } 5.4 短信模板接口响应：成功示例（查询所有） /*

返回参数说明
"sms_template_code"：模板代码
"content"：模板内容
"status"：模板状态： 1=启用， 2=待审核， 3=驳回
"created_date"：模板创建时间

*/ { "data" : { "message" : "查询成功", "templates" : [ { "sms_template_code" : "dynamic_code", "content" : "您好，您当前的动态密码是：${code}，请尽快提交。", "status" : "1", "created_date" : "2016-04-11 18:11:56" }, { "sms_template_code" : "safe_mobile", "content" : "验证码是：${code}，用于绑定密保手机，请尽快提交。", "status" : "1", "created_date" : "2016-03-26 17:25:27" } ] }, "code" : "25010" }

响应：成功示例（查询单个） { "data" : { "message" : "查询成功", "templates" : [ { "sms_template_code" : "dynamic_code", "content" : "您好，您当前的动态密码是：${code}，请尽快提交。", "status" : "1", "created_date" : "2016-04-11 18:11:56" } ] }, "code" : "25010" } 响应：成功示例（新增） { "data" : "保存成功", "code" : "25010" } 响应：成功示例（删除） { "data" : "删除成功", "code" : "25010" } 响应：失败示例 { "data" : "模板代码已经存在", "code" : "45070" } 5.5 帐户信息查询接口响应：成功示例 /**

返回参数说明
"balance"：账户余额

*/ { "data" : { "message" : "查询成功", "balance" : "10935" }, "code" : "25010" } 响应：失败示例 { "data" : { "message" : "参数签名(md5)错误", "balance" : "" }, "code" : "45040" }

注意事项
为防止 API 调用过程中被黑客恶意篡改，调用任何一个 API 都需要携带签名，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。
所有的请求和响应数据编码皆为 UTF-8 格式， URL 里的所有参数名和参数值请做 UTF-8 编码。
参数名与参数值拼装起来的 URL 长度小于 1024 个字符时，可以用 GET 发起请求；拼装好的请求 URL 过长时，必须用 POST 发起请求。所有 API 都可以用 POST 发起请求。
为避免乱码问题，建议使用 POST 方式发起请求。
为保证帐户安全，建议绑定安全 IP 地址。