跳轉至

One-Time Password(OTP) API

One-Time Password(OTP) 驗證系統提供由 發送 OTP 與 驗證 OTP 組成的 API，可將 OTP 驗證套用至遊戲。

網址

伺服器 URL
生產環境 https://otp.qpyou.cn
沙盒環境 https://sandbox-otp.qpyou.cn

認證方法

若要使用 OTP 發送系統提供的 API，必須先取得驗證權杖(API KEY)。當遊戲註冊到 App Center 時，驗證權杖會自動產生。驗證權杖遵循 JSON Web Token(JWT) 規範，且沒有到期時間，因此可持續使用。

發送 OTP

OTP Short Message Service(SMS) 發送

  • 基本信息

| 方法 | POST |

#### **回調數據資訊** { #callback-data }

| 名稱 | 類型 | 必填 | 描述 |
| --- | --- | --- | --- |
| expiry | 字串 | 是 | OTP 有效期（例如：2024-06-25T11:39:43.076573600+09:00[Asia/Seoul]） |
| expiryTimestamp | Long | O | OTP 到期時間戳記（毫秒） <br> (範例: `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 Console 中註冊的發送 ID 不一致，就會發生此錯誤。請確認 `Topic` 標頭值，以及在 <u>Hive Console > 通知 > SMS OTP > 發送資訊設定</u> 中註冊的 <b>發送 ID</b>。

```java
{
    "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 Console > 通知 > SMS OTP > 發送資訊設定 中確認每日發送上限。

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

"lang" : "ko",
"retry" : true,
"lookup" : true

}' * **回應範例** OTP SMS 發送請求若已正常處理，會收到如下回應本文。java { "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 Console 中註冊的發送 ID 不一致，就會發生此錯誤。請確認 Topic 標頭值，以及在 Hive Console > 通知 > 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 Console > 通知 > 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 Console > 通知 > 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" : "01012345678",
    "otp" : "123456"
}'
  • 回應範例

OTP 一致時，回應本文如下。

{
    "result" : true
}