融云短信服务开发指南

    概述

    为满足应用中短信验证业务需求,融云与优质短信平台合作,提供具有全网覆盖能力的短信验证码发送、验证功能接口,详细开通及使用说明如下:

    短信功能使用流程

    开发者在使用短信验证功能前,需前往融云官方网站注册创建融云开发者帐号。

    image
    使用流程

    短信服务使用说明

    认证企业开发者

    在融云开发者后台,选择需要开通短信功能的应用,进入应用详情页面,点击 “短信服务 > 服务设置” 进行企业认证,提交认证信息后,会在 5 个工作日内审核完成。

    image
    认证企业开发者

    短信资费、扣费说明

    认证成功后,需要充值购买短信才能使用短信服务,短信价格如下:

    充值为 100 的整数倍 例如:100, 200, 1100, 1200…

    1. 充值金额 < 1000 元时,短信单价为 0.060 元/条
    2. 1000 ≤ 充值金额 < 5000 元时,短信单价为 0.055 元/条
    3. 充值金额 ≥ 5000 元时,短信单价为 0.050 元/条

    短信扣费说明:

    1. 金额充值成功后,实时兑换成相应短信条数。
    2. 短信条数将在短信发送后 48 小时内完成扣除,短信实际扣除条数以运营商结算为准。

    短信签名

    每条短信都必须带有签名,可以在开发者后台 “短信服务 > 服务设置” 中进行添加。

    签名说明

    • 根据中国基础运营商的相关规定,每条短信的最后必须包含签名,如果没有签名,则短信肯定无法正常发送。
    • 签名格式为中文括号加公司简称或者店铺名称等:例如:【融云即时通讯云】,建议使用 3-7 个汉字。
    • 可以包含数字、汉字、英文,不能为纯数字、纯英文或数字+英文的组合,不能包含其他特殊符号。
    • 签名会自动附加,因此会占用短信的字数,请注意控制内容长度。
    • 受运营商限制,正常审核时间为 3 个工作日以内。

    图片验证

    开发者可选择开启或关闭图片验证功能,开启后可通过 获取图验接口 获取图验 URL 地址,在发送短信验证码时会对图验进行验证,验证通过才会下发短信验证码,否则不会下发短信验证码,防止短信骚扰。

    短信模板

    融云默认为提供用户注册密码找回修改密码身份验证等 4 个短信模板,如果用户有新的模板需求,可提交模板申请添加。

    需要说明模板名称、短信用途及内容,短信内容中需要标出签名位置(只能在短信内容前面或最后)及验证码位置。

    短信号码

    短信号码说明

    1. 短信号码在每创建一个应用后,系统会自动分配一个短信端口号码。
    2. 因受政策限制,已分配的短信端口号码某些时候不可用。
    3. 暂不提供自定义短信号码。

    获取图片验证码方法

    开发者后台开通图片验证功能后,才能获取图片验证码。

    示例

    HTTP 请求方式: GET

    http://api.sms.ronghub.com/getImgCode.json?appKey=uwd1c0sxdlx2
    

    表单参数

    名称 类型 说明
    appKey String 应用 AppKey。(必传)

    返回值

    名称 类型 说明
    code int 返回码,200 为正常。
    url String 返回的图片验证码 URL 地址。
    verifyId String 返回图片验证标识 Id。

    json格式:

    {
      "code": 200,
      "url": "xxxxxxxxxxxxx",
      "verifyId": "xxxxxxxx"
    }
    

    发送短信验证码方法

    方法名:/sendCode

    签名方法:请参考 通用 API 接口签名规则

    URL:http://api.sms.ronghub.com/sendCode.json

    HTTP 方法:POST

    示例

    HTTP 请求:

    POST /sendCode.json HTTP/1.1
    Host: api.sms.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/x-www-form-urlencoded
    
    mobile=13500000000&verifyId=1408706337&verifyCode=890b422b&templateId=dsfdsfd&region=86
    

    表单参数

    名称 类型 说明
    mobile String 接收短信验证码的目标手机号,每分钟同一手机号只能发送一次短信验证码。(必传)
    verifyId String 图片验证标识 Id ,开启图片验证功能后此参数必传,否则可以不传。在获取图片验证码方法返回值中获取。
    verifyCode String 图片验证码,开启图片验证功能后此参数必传,否则可以不传。
    templateId String 短信模板 Id,在“开发者后台->短信服务->服务设置->短信模版”中获取。(必传)
    region String 手机号码所属国家区号,目前只支持中国区号 86(必传)

    返回值

    名称 类型 说明
    code int 返回码,200 为正常。
    sessionId String 短信验证码唯一标识。

    json格式:

    {
     "code": 200,
     "sessionId": "xxxxxxx"
    }
    
    注:每分钟同一手机号只能发送一次短信验证码,短信验证码有效期为 15 分钟,短信验证成功后验证码失效。开通图片验证功能后,如果此条图片验证不成功则用户不会收到验证短信。

    返回值请参考 API 方法返回值说明

    验证码验证方法

    方法名:/verifyCode

    签名方法:请参考 通用 API 接口签名规则

    URL:http://api.sms.ronghub.com/verifyCode.json

    HTTP 方法:POST

    示例

    HTTP 请求:

    POST /verifyCode.json HTTP/1.1
    Host: api.sms.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/x-www-form-urlencoded
    
    sessionId=2312312&code=3122
    

    表单参数

    名称 类型 说明
    sessionId String 短信验证码唯一标识,在发送短信验证码方法,返回值中获取。(必传)
    code String 短信验证码内容。(必传)

    返回值

    名称 类型 说明
    code int 返回码,200 为正常。
    success Boolean true 验证成功,false 验证失败。

    json格式:

    {"code":200,"success":true}
    

    返回值请参考 API 方法返回值说明

    发送通知类短信方法

    方法名:/sendNotify

    签名方法:请参考 通用 API 接口签名规则

    URL:http://api.sms.ronghub.com/sendNotify.json

    HTTP 方法:POST

    示例

    HTTP 请求:

    POST /sendNotify.json HTTP/1.1
    Host: api.sms.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/x-www-form-urlencoded
    
    mobile=13500000000&templateId=dsfdsfd&region=86&p1=aa&p2=bb&p3=cc
    

    表单参数

    名称 类型 说明
    mobile String 接收通知短信的目标手机号。(必传)
    templateId String 短信模板 Id,在“开发者后台->短信服务->服务设置->短信模版”中获取。(必传)
    region String 手机号码所属国家区号,目前只支持中国区号 86(必传)
    p1 String 短信模板中,自定义变量值,如果在通知短信模板中定义了 {p1} 则在发送通知短信时必须传入此参数,替换模板中的 {p1},否则此参数可以不传。
    p2 String 短信模板中,自定义变量值,如果在通知短信模板中定义了 {p2} 则在发送通知短信时必须传入此参数,替换模板中的 {p2},否则此参数可以不传。
    p3 String 短信模板中,自定义变量值,如果在通知短信模板中定义了 {p3} 则在发送通知短信时必须传入此参数,替换模板中的 {p3},否则此参数可以不传。
    注:发送的通知短信内容不能超过 210 个字节。

    返回值

    名称 类型 说明
    code int 返回码,200 为正常。
    sessionId String 短信唯一标识。

    json格式:

     {
      "code": 200,
      "sessionId": "xxxxxxx"
     }
    

    返回值请参考 API 方法返回值说明

    API 方法返回值说明

    code 描述 HTTP 状态码
    1009 没有开启图验功能 400
    1010 未使用已开启的图验功能 400
    1000 内部逻辑错误 500
    1003 参数错误 400
    1005 参数长度超出限制 400
    1008 调用超过频率上限 429
    1002 缺少参数 400
    1004 验证签名错误 401
    1050 内部服务响应超时 504
    1012 图片验证码不正确 430
    1011 剩余条数不足,需要充值 430
    1013 短信通道不可用 430
    1014 短信验证码已验证过,再次验证失效 430
    1015 短信验证码过期无效 430