Question

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

接口地址：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-id 和x-app-key来完成校验，为提高安全性，您也可以选择签名校验。

请求头

请求头	含义	备注
Content-Type	固定值 application/x-www-form-urlencoded
x-app-id	OTP 应用 ID，请在云片开发者控制台创建应用并获取
x-timestamp	时间戳，单位毫秒	服务器会对该时间做校验，与当前时间相差过大将无法完成校验
x-nonce	一次性随机数	调用方随机生成，应保证每次请求唯一
x-signature	签名，使用 HMAC-SHA256 加密算法	生成签名方法：拼接x-app-id、x-timestamp、x-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时，返回响应体code为0；HTTP 状态码非200时，返回响应体code非0。

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	请求过多，达到短信发送频率限制

服务端交互时序图