信信客短信平台接入指南

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

1.   准备工作

接入前请在“开发者设置”中设置“开发者状态”为“启用”，并获取“开发者标识”和“开发者密钥”。

为保证信息安全，切勿将开发者信息告知他人。

2.   调用流程

根据接口约定：填充参数 > 生成签名 > 拼装HTTP请求 > 发起HTTP请求 > 得到HTTP响应 > 解析JSON结果。

3.   公共参数

调用任何一个API接口都必须传入的参数，目前的公共参数有：

参数名称	参数类型	是否必须	参数描述
dev_id	String	必须	开发者标识
sign	String	必须	参数签名

参数说明：

1.  参数签名：为防止API调用过程中被恶意篡改，调用任何一个API都需要携带签名，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。

4.   接口调用

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	可选	扩展子号

参数说明：

1.  参数签名：算法md5(dev_id + dev_key +rec_num)。示例：md5("b7d5107d782d4033v35047d4a448089b"+ "e35c7a885v0144e79ef9541a36382f21" + "13800138000,18900189000,18600186000")

2.  短信模板变量：传参规则{"key":"value"}，key的名字须和申请模板中的变量名一致，多个变量之间以逗号隔开。示例：针对模板“验证码${code}，您正在进行${product}身份验证，打死不要告诉别人哦！”，传参时需传入{"code":"1234","product":"xinxinke"}

3.  接收号码：支持单个或多个手机号码，传入号码为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	可选	号码提交记录索引

参数说明：

1.  参数签名：算法md5(dev_id + dev_key)。示例：md5("b7d5107d782d4033v35047d4a448089b"+ "e35c7a885v0144e79ef9541a36382f21")

2.  接收号码：传入号码为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	可选	发送号码

参数说明：

1.  参数签名：算法md5(dev_id + dev_key)。示例：md5("b7d5107d782d4033v35047d4a448089b"+ "e35c7a885v0144e79ef9541a36382f21")

2.  发送号码：传入号码为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	区分动作	模板内容

参数说明：

1.  请求动作：

1)  查询：action = query，模板代码为可选项

2)  新增：action = create，模板代码、模板内容为必须项

3)  删除：action = delete，模板代码为必须项

2.  参数签名：

1)  查询：算法md5(dev_id + dev_key)。示例：md5("b7d5107d782d4033v35047d4a448089b"+ "e35c7a885v0144e79ef9541a36382f21")

2)  新增、删除：算法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	必须	参数签名

参数说明：

1.  参数签名：算法md5(dev_id + dev_key)。示例：md5("b7d5107d782d4033v35047d4a448089b"+ "e35c7a885v0144e79ef9541a36382f21")

4.5.2 帐户信息查询响应

状态码	描述
25010	正确
45001	非法IP
45010	开发者标识不合法
45020	参数签名(md5)格式不正确
45030	开发者状态异常
45040	参数签名(md5)错误

5.   调用示例

请求：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" }

6.   注意事项

1.  为防止API调用过程中被黑客恶意篡改，调用任何一个API都需要携带签名，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。

2.  所有的请求和响应数据编码皆为UTF-8格式，URL里的所有参数名和参数值请做UTF-8编码。

3.  参数名与参数值拼装起来的URL长度小于1024个字符时，可以用GET发起请求；拼装好的请求URL过长时，必须用POST发起请求。所有API都可以用POST发起请求。

4.  为避免乱码问题，建议使用POST方式发起请求。

为保证帐户安全，建议绑定安全 IP 地址。