发送短信验证码
接口描述：发送短信验证码到指定手机号
接口地址：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 | 请求过多，达到短信发送频率限制 |
服务端交互时序图
