跳转至

One-Time Password(OTP) API

One-Time Password(OTP) 认证系统提供由 OTP 发送 和 OTP 验证 组成的 API，便于在游戏中应用 OTP 认证。

URL

服务器 URL
生产环境 https://otp.qpyou.cn
沙盒环境 https://sandbox-otp.qpyou.cn

认证方法

要使用 OTP 发送系统提供的 API，必须先签发认证令牌(API KEY)。当游戏注册到 AppCenter 后，会自动生成认证令牌。认证令牌遵循 JSON Web Token(JWT) 规范，没有过期时间，因此可以持续使用。

发送 OTP

OTP Short Message Service(SMS) 发送

  • 基本信息
方法 POST
URL /otp/send
  • 请求头
字段 类型
内容类型 application/json
授权 bearer
Topic 在 Hive 控制台 > 通知 > SMS OTP > 发送信息设置 中注册或修改的 发送 ID

  • 发送 OTP 短信时需要回调

    如果不是由 OTP 直接发送 OTP SMS，而是由应用开发公司自行发送，则可以通过回调接收发送所需的信息。在 Hive 控制台 > 通知 > SMS OTP > 发送信息设置 中选择 直接发送 后，下面的数据会以 JSON 形式传递到已注册回调 URL 的 Request Body 中。有关设置方法，请参见 直接发送。另请一并查看 回调请求示例 和 传递的数据。

  • 请求体

字段 类型 必需 描述
to 字符串 O 接收者的电话号码
toCountryNo 字符串 O 接收者的国家代码
retry 布尔值 X 此字段指示您尝试通过此 API 向同一接收者发送 OTP 短信的存在。如果此字段留空，则如果在过去 5 分钟内对同一接收者调用此 API 超过一次，则设置为 true，否则设置为 false。
lookup 布尔值 X 此字段指示是否验证 to 是否为有效的电话号码格式，默认值为 false。如果为 true，则由于验证过程，API 响应时间大约为 250ms ~ 2000ms，通常在 false 时在 200ms 内。
lang 字符串 X 这是语言代码，默认值为 en。
有效的语言代码:
  • ko
  • en
  • ja
  • zh-cn
  • zh-tw
  • zh-hans
  • zh-hant
  • de
  • fr
  • ru
  • es
  • pt
  • id
  • th
  • vi
  • it
  • tr
  • ar
  • 响应头
字段 类型
内容类型 application/json
  • 响应体
字段 类型 描述
otp 字符串 OTP号码
provider 字符串 短信提供商
expiry 字符串 OTP有效时间
expiryTimestamp Long OTP 有效期时间戳（秒）
  • 请求示例

以下示例用于调用 OTP SMS 发送 API，并包含 Topic 请求头和接收方信息。

//sample 1
curl --location 'https://otp.qpyou.cn/otp/send' 
--header 'Authorization: Bearer AUTH_TOKNE_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data '{
    "to" : "01012345678",
    "toCountryNo" : "82",
    "lang" : "ko"
}'
//sample 2
curl --location 'https://otp.qpyou.cn/otp/send' 
--header 'Authorization: Bearer AUTH_TOKNE_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data '{
    "to" : "01012345678",
    "toCountryNo" : "82",
    "lang" : "ko",
    "retry" : true,
    "lookup" : true
}'
  • 响应示例

OTP SMS 发送请求被正常处理后，会收到如下响应正文。

{
    "otp" : "123456",
    "provider" : "YOUR_SMS_PROVIDER",
    "expiry" : "2026-03-23T11:00:48.533695818+09:00",
    "expiryTimestamp" : 1774231248
}

回调示例

如果设置为由应用开发公司直接发送，则已注册的回调 URL 会收到如下请求正文。

curl --location 'https://{your_callback_url}' 
--header 'Content-Type: application/json' 
--data '{
"to":"01012345678",
"toCountryNo":"82",
"lang":"en",
"retry":null,
"lookup":false,
"serviceName":"LocalTest",
"otp":"809881",
"provider":"DIRECTSEND",
"expiry":"2024-06-26T11:36:29.680680500+09:00[Asia/Seoul]",
"expiryTimestamp":1719369389680
}'

回调数据通知

名称 类型 必需 描述
expiry 字符串 是 OTP 有效期（例如，2024-06-25T11:39:43.076573600+09:00[Asia/Seoul]）
expiryTimestamp Long O OTP 有效期时间戳（毫秒）
（示例：1719283183076）
lang 字符串 否 语言代码，默认为 en
lookup 布尔值 否 验证 to 值是否为有效的电话号码格式，默认为 false
otp 字符串 是 OTP 号码
provider 字符串 是 短信提供商，固定值 DIRECTSEND 用于直接发送
retry 布尔值 否 重试选项
serviceName 字符串 是 在发送信息设置菜单中设置的服务名称（英文）
to 字符串 是 收件人电话号码
toCountryNo 字符串 是 收件人国家代码

错误响应代码

HTTP Status id error 说明
400 40004 VALIDATION_FAIL 请求正文有效性验证失败时会发生此错误。
400 40003 INVALID_PHONE_NUMBER 电话号码有效性验证失败时会发生此错误。
422 42202 NO_TOPIC 请求头中的 Topic 传递的值无效时会发生此错误。
409 40902 DUPLICATE_OTP_EXISTS 如果检测到针对同一认证对象在一定时间内重复请求签发 OTP，则会返回 DUPLICATE_OTP_EXISTS 错误。请等待最多 15 秒后重试。
429 42903 SMS_LIMIT_EXCEEDED 在 24 小时内使用同一号码请求次数超过已设置的发送上限时会发生此错误。响应消息中可能包含已设置的上限值。

Topic 值无效时

如果请求头中的 Topic 值与 Hive 控制台中注册的发送 ID 不一致，则会发生此错误。请检查 Topic 请求头值，以及在 Hive 控制台 > 通知 > SMS OTP > 发送信息设置 中注册的 发送 ID。

{
    "id" : 42202,
    "error" : "NO_TOPIC",
    "reason" : "No such 'Topic' Data"
}

相同 OTP 被重复生成时

如果在同一时间区间内两次发送相同请求，则会生成相同的 OTP。此时第一次请求会成功，第二次请求会因 DUPLICATE_OTP_EXISTS 失败。请在当前时间区间结束后的下一个区间重新发送相同请求。

{
    "id" : 40902,
    "error" : "DUPLICATE_OTP_EXISTS",
    "reason" : "Already sent OTP to this phone number."
}

超过 24 小时发送上限时

同一电话号码在 24 小时内超过允许的发送次数时，会发生此错误。该上限不是固定值。下面示例响应消息中包含的次数，仅用于展示所设置的上限值。请在 Hive 控制台 > 通知 > SMS OTP > 发送信息设置 中确认每日发送上限。

{
    "id" : 42903,
    "error" : "SMS_LIMIT_EXCEEDED",
    "reason" : "Too many requests in 24 hours. (Can not exceed 10 times)"
}

验证 OTP

方法 POST
URL /otp/verify
  • 请求头
字段 类型
内容类型 application/json
授权 bearer
Topic 在 Hive 控制台 > 通知 > SMS OTP > 发送信息设置 中注册或修改的 发送 ID
  • 请求体
字段 类型 必需 描述
toCountryNo String O 接收国家代码
to String O 接收电话号码
otp 字符串 O 接收的OTP
  • 响应头
字段 类型
内容类型 application/json
  • 响应体
字段 类型 描述
result 布尔值 OTP 验证结果
  • 请求示例 1

以下示例用于传递接收电话号码和 OTP 号码以验证 OTP。

// sample 1
curl --location 'https://otp.qpyou.cn/otp/verify' 
--header 'Authorization: bearer AUTH_TOKEN_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data '{
    "toCountryNo" : "82",
    "to" : "01036012891",
    "otp" : "123456"
}'
  • 响应示例

OTP 匹配时，响应正文如下。

{
    "result" : true
}