短信API服务文档及简易使用教程注意事项

一.接口文档

接口名称：短信api

接口地址：http://v.juhe.cn/sms/send

支持格式：json/xml

请求方式：http get

请求示例：http://v.juhe.cn/sms/send?mobile=手机号码&tpl_id=短信模板ID&tpl_value=%23code%23%3D654654&key=

请求参数说明：

名称	类型	必填	说明
mobile	string	是	接收短信的手机号码
tpl_id	int	是	短信模板ID，请参考个人中心短信模板设置
tpl_value	string	是	变量名和变量值对，如：#code#=431515，整串值需要urlencode。如果你的变量名或者变量值中带有#&=中的任意一个特殊符号，请先分别进行utf-8 urlencode编码后再传递
key	string	是	应用APPKEY(应用详细页查询)
dtype	string	否	返回数据的格式,xml或json，默认json

返回参数说明：

名称	类型	说明
error_code	int	返回码
reason	string	返回说明

短信api调用JSON返回示例：

/****失败示例**/
{
    "reason": "错误的短信模板ID,请通过后台确认!!!",
    "result": [],
    "error_code": 205402
}

/****成功示例**/
{
    "reason": "短信发送成功",
    "result": {
        "count": 1, /*发送数量*/
        "fee": 1, /*扣除条数*/
        "sid": 2029865577 /*短信ID*/
    },
    "error_code": 0 /*发送成功*/
}

二、相关注意事项

    1.为积极配合运营商治理垃圾短信，按运营商要求，聚合数据将有投诉记录或回复退订的手机号加入黑名单。

    2.[重要] 验证码客户请务必添加图片验证码等防恶意攻击的机制，以防短信轰炸。

    3.发送频率：验证码同一号码1分钟一次 1小时8次 一天10次

    4.短信签名：3到8个字符，应用名称或者公司名称，不能含有特殊字符，如：符号、空格

    5.短信内容：不能含有中括号，以及推销电话和链接

    6.字数限制：一条是70个字符限制。超过会按多条扣除，第二条起按67个字符算，中英文标点空格都算作一个字符，最多300字符.

二、基本使用流程

    1.通过注册成为聚合会员，进入个人中心，点击申请数据按钮。选择生活常用->短信API服务，即可成功申请并获得一定免费次数。目前暂只支持企业用户申请。

    2.申请短信模板

        2.1、聚合已经提供了几个常用的模板格式示例供参考，如果开发者还不能满足开发作者实际的需求，您可以自行添加（添加成功后会获得一个模板ID，用于请求API时使用），待审核通过后即可使用自定义模板发送短信，目前聚合短信API服务暂只支持验证码类、通知类信息，不支持营销类，订阅类，邀请类短信都不能发送，涉及关键词也不行，如房产，医疗等的短信内容，如不确定可与我们的在线客服联系确认。

        2.2、为什么需要通过模板发送短信？由于运营商对短信内容有一定的监管，会有部分关键字不允许发送。通过模板发送的短信，由于模板提前由聚合专业客服审核，短信内容被屏蔽的可能性非常小。 另外，由于模板已经审核过，使用模板发送不再需要重复做关键字检查，理论上速度会比普通发送的接口更快，非常适合内容相对固定、实时性要求高的触发类短信，如验证码的发送。

        2.3、模板变量设置说明：定义一个变量统一格式为：#code#，#号中间的code用户可以自行定义。   

    3.短信发送API的使用

        3.1、根据接口文档格式要求传递数据。个别参数的简易说明:

        tpl_id：即短信模板的ID，在短信模板中心可以查看。

        tpl_value:变量名和变量值对。变量名和变量值对。如果你的变量名或者变量值中带有#&=中的任意一个特殊符号，请先分别进行urlencode编码后再传递。比如您设定了#code# 和 #company#两个变量的模板，示例如下：

        参考变量示例：#code#=1234&#company#=聚合数据

        在POST参数时，无特殊字符的代码示例:tpl_value=urlencode("#code#=1234&#company#=聚合数据")

        带特殊字符的代码示例:tpl_value=urlencode("#code#=1234&#company#=urlencode('聚#合#数#据')")