One-Time Password(OTP) API¶

One-Time Password(OTP)認証システムは、ゲームにOTP認証を適用できるように、OTP送信とOTP検証で構成されたAPIを提供します。

URL¶

認証方法¶

OTP送信システムが提供するAPIを使用するには、まず認証トークン(API KEY)の発行を受ける必要があります。認証トークンは、App Centerにゲームが登録されると自動的に生成されます。認証トークンはJSON Web Token(JWT)仕様に従い、有効期限がないため固定で使用できます。

OTPを送信¶

OTP Short Message Service(SMS) 送信¶

• 基本情報

• リクエストヘッダー

• OTP SMSを直接送信する際にコールバックが必要です

  OTPでOTP SMSを直接送信するのではなく、アプリ開発会社が直接送信する場合は、送信に必要な情報をコールバックで受け取れます。Hive Console > Notification > SMS OTP > 送信情報設定で直接送信を選択すると、登録したコールバックURLに以下のデータがRequest BodyにJSON形式で渡されます。設定方法は直接送信を参照してください。コールバックリクエストの例と送信されるデータもあわせて確認してください。

• リクエストボディ

• レスポンスヘッダー

• レスポンスボディ

• リクエストサンプル

次の例は、Topicヘッダーと受信者情報を含めてOTP SMS送信APIを呼び出すときに使用します。

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

コールバックデータ情報¶

エラーレスポンスコード¶

Topic値が有効でない場合¶

リクエストヘッダーのTopic値がHive Consoleに登録した送信IDと一致しない場合、このエラーが発生します。Topicヘッダー値とHive Console > Notification > SMS OTP > 送信情報設定に登録した送信IDを確認してください。

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

同じOTPが重複して生成された場合¶

同じリクエストを同じ区間内で2回送信すると、同じOTPが生成されます。このとき、1回目のリクエストは成功し、2回目のリクエストはDUPLICATE_OTP_EXISTSで失敗します。現在の区間が終了した後、次の区間で同じリクエストを再送信してください。

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

24時間送信上限を超過した場合¶

同じ電話番号に対して24時間の間に許可された送信回数を超えると、このエラーが発生します。この上限は固定値ではありません。以下の例のレスポンスメッセージに含まれる回数は、設定した上限値を示す例です。Hive Console > Notification > SMS OTP > 送信情報設定で1日の送信上限を確認してください。

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

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
}