接入文档

发送短信验证码

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

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

请求方法：POST

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

请求头：

请求参数：

请求和响应示例：

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": {}
}

响应体字段说明：

校验短信验证码

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

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

请求方法：POST

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

请求头：

请求参数：

请求和响应示例：

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
  }
}

响应体字段说明：

注意：

验证码失效策略

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

附录

API 签名校验

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

请求头

签名计算方法示例

假设

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。

服务端交互时序图