OTP短信验证接入文档

发送短信验证码

接口描述:发送短信验证码到指定手机号

接口地址:https://otp.yunpian.com/api/sms/sendCode

请求方法:POST

内容类型:application/x-www-form-urlencoded

请求头:

请求头 含义 备注
Content-Type 固定值 application/x-www-form-urlencoded
x-app-id OTP应用ID,请在云片开发者控制台创建应用并获取
x-app-key OTP应用Key,创建应用后自动生成的appKey 为提高安全性,可以用签名取代appKey,请参考附录API签名校验
x-timestamp 时间戳,单位毫秒
x-nonce 一次性随机数,调用方随机生成,应保证每次请求唯一

请求参数:

请求参数 含义
phone 手机号,建议使用E164格式,暂时仅支持中国大陆手机号

请求和响应示例:

curl -X POST \
  'https://otp.yunpian.com/api/sms/sendCode?phone=%2B86139XXXXYYYY' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-app-id: 7bc548ae10394f23b7d76a48cec23dec' \
  -H 'x-app-key: 5d2ae085c72f4ac8b91562d9b628c1e5' \
  -H 'x-timestamp: 1575129600000' \
  -H 'x-nonce: rl29sm2df'
{
    "code": 0,
    "msg": "ok",
    "meta": {
        "rateLimitStats": {
            "appNaturalDay": {
                "count": 1,
                "limit": 1000,
                "enabled": true
            },
            "appToPhonePerMinute": {
                "count": 1,
                "limit": 10,
                "enabled": true
            },
            "appToPhonePerHour": {
                "count": 1,
                "limit": 30,
                "enabled": true
            },
            "appToPhonePerDay": {
                "count": 1,
                "limit": 30,
                "enabled": true
            }
        }
    },
    "data": {}
}

响应体字段说明:

字段 含义 备注
code 响应码,0 - 成功,其他 - 失败,详情参考附录响应码
msg 响应码对应的描述语
meta 元信息,格式不固定的对象 包括当前限流信息rateLimitStats,取决于接口调用次数和您在开发者控制台的短信频率配置
data 保留字段,暂无数据

校验短信验证码

接口描述:校验短信验证码是否正确

接口地址:https://otp.yunpian.com/api/sms/verifyCode

请求方法:POST

内容类型:application/x-www-form-urlencoded

请求头:

请求头 含义 备注
Content-Type 固定值 application/x-www-form-urlencoded
x-app-id OTP应用ID,请在云片开发者控制台创建应用并获取
x-app-key OTP应用Key,创建应用后自动生成的appKey 为提高安全性,可以用签名取代appKey,请参考附录API签名校验
x-timestamp 时间戳,单位毫秒
x-nonce 一次性随机数,调用方随机生成,应保证每次请求唯一

请求参数:

请求参数 含义
phone 手机号,建议使用E164格式,暂时仅支持中国大陆手机号
code 验证码

请求和响应示例:

curl -X POST \
  'https://otp.yunpian.com/api/sms/verifyCode?phone=%2B86139XXXXYYYY&code=123456' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-app-id: 40685513ea3446debdd5e04d03301e2a' \
  -H 'x-app-key: 1f63ee1d8e4547b7b9060fb9fa44a766' \
  -H 'x-timestamp: 1575129600000' \
  -H 'x-nonce: rl29sm2df'
{
    "code": 40033,
    "msg": "验证码不正确",
    "meta": {
        "verifySuccessCount": 0,
        "verifyFailLimit": 5,
        "verifyFailCount": 1
    }
}

响应体字段说明:

字段 含义 备注
code 响应码,0 - 成功,其他 - 失败,详情参考附录响应码
msg 响应码对应的描述语
meta 元信息,格式不固定的对象 包括待验证的验证码的验证失败次数、验证失败次数限制、验证成功次数等

注意:

验证码失效策略

  • 成功验证过一次后立即失效
  • 验证失败次数达到限制立即失效
  • 验证码超时未验证自然过期
  • 生成了新验证码后,旧验证码(未验证通过)自动失效

附录

API签名校验

服务端接口需要校验调用方的身份,这些信息放在请求头中,您可以通过x-app-idx-app-key来完成校验,为提高安全性,您也可以选择签名校验。

请求头

请求头 含义 备注
Content-Type 固定值 application/x-www-form-urlencoded
x-app-id OTP应用ID,请在云片开发者控制台创建应用并获取
x-timestamp 时间戳,单位毫秒 服务器会对该时间做校验,与当前时间相差过大将无法完成校验
x-nonce 一次性随机数 调用方随机生成,应保证每次请求唯一
x-signature 签名,使用HMAC-SHA256加密算法 生成签名方法:拼接x-app-idx-timestampx-nonce的值作为消息,appKey的值作为密钥,生成消息摘要。

签名计算方法示例

假设

x-app-id=40685513ea3446debdd5e04d03301e2a

x-timestamp=1575129600000

x-nonce=rl29sm2df

appKey=1f63ee1d8e4547b7b9060fb9fa44a766

拼接字符串得到消息40685513ea3446debdd5e04d03301e2a1575129600000rl29sm2df,以1f63ee1d8e4547b7b9060fb9fa44a766作为密钥计算得到消息摘要为32aca2e5745357e3fe423226a14681f78d8cf69ae5469c89ff08f1c2778dadcc

Java代码示例:

String appId = "40685513ea3446debdd5e04d03301e2a";
long timeMillis = System.currentTimeMillis();
String nonce = UUID.randomUUID().toString();
String msgToDigest = appId + timeMillis + nonce;
String appKey = "1f63ee1d8e4547b7b9060fb9fa44a766";
HmacUtils hmacUtils = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, appKey);
String hmacHex = hmacUtils.hmacHex(msgToDigest);
System.out.println(hmacHex);

这里,HmacUtils类来自于commons-codec

响应码

响应码是指响应体(JSON格式)中的code字段,0表示成功,其他表示失败,具体参照下表。

注:HTTP状态码为200时,返回响应体code0;HTTP状态码非200时,返回响应体code0

HTTP状态码 响应码(code) 描述
200 0 成功
400 40012 应用不存在
400 40022 短信模板状态异常,一般是短信模板未设置或未审核通过
400 40023 短信模板内容不包含验证码占位符(#code#),请修改短信模板
400 40024 短信内容过长,不应超过70个字,请更改短信模板
400 40031 验证码已过期,请重新获取验证码
400 40032 验证失败次数达到上限,请重新获取验证码
400 40033 验证码不正确,请重新提交验证码
400 40100 未通过身份验证,appKey或签名错误导致
400 42900 请求过多,达到短信发送频率限制

服务端交互时序图

otp

results matching ""

    No results matching ""