OTP検証システム

OTP検証システムは、ゲームにOTP検証を適用するためのOTP送信とOTP検証からなるAPIを提供します。

URL

サーバー	URL
プロダクション	https://otp.qpyou.cn
サンドボックス	https://sandbox-otp.qpyou.cn

---

認証方法

OTP送信システムが提供するAPIを実装するには、認証トークン（API KEY）が必要です。認証トークンは、ゲームがAppCenterに登録された後に自動的に発行されます。JWT（JSON Web Token: https://jwt.io）仕様に従った認証トークンは、有効期限を制限しないため、このトークンを引き続き使用することができます。

---

OTPを送信

OTP SMSを送信

• 基本情報

メソッド	POST
URL	/otp/sms

• リクエストヘッダー

フィールド	タイプ
コンテンツタイプ	application/json
認証	bearer
トピック	Hive コンソール > 通知 > SMS OTP > 送信情報設定 > 登録または変更 > 送信ID

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

OTP SMSがOTPによって直接送信されず、自分自身によって送信される場合、OTP SMSを送信するために必要な情報をコールバック経由で受け取ることができます。_Hive コンソール > 通知 > SMS OTP > 送信情報設定_で、直接送信を選択すると、以下のデータが登録されたコールバックURLにJSON形式でリクエストボディ内に送信されます。コールバックリクエストの例およびコールバックデータを参照してください。

• リクエストボディ

フィールド	タイプ	必須	説明
to	文字列	O	受信者の電話番号
toCountryNo	文字列	O	受信者の国コード
retry	ブール	X	このフィールドは、同じ受信者に対してこのAPIを使用してOTP SMSを送信する試行の存在を示します。このフィールドが空白のままにされている場合、過去5分間に同じ受信者に対してこのAPIが2回以上呼び出された場合は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	文字列	SMSプロバイダー
expiry	文字列	OTPの有効期限

• リクエストサンプル

//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" : "123456",
    "provider" : "YOUR SMS PROVIDER",
    "expiry" : "2022-07-20T15:18:06.885195100+09:00[Asia/Seoul]"
}

コールバックの例

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	長整数	はい	OTPの有効期限のタイムスタンプ (例: 1719283183076)
lang	文字列	いいえ	言語コード、デフォルトはen
lookup	ブール値	いいえ	to値が有効な電話番号形式かどうかを確認、デフォルトはfalse
otp	文字列	はい	OTP番号
provider	文字列	はい	SMSプロバイダー、直接送信には固定値DIRECTSENDが使用されます
retry	ブール値	いいえ	再試行オプション
serviceName	文字列	はい	送信情報設定メニューに設定されたサービス名 (英語)
to	文字列	はい	受取人の電話番号
toCountryNo	文字列	はい	受取人の国コード

OTPメールを送信

メソッド	POST
URL	/otp/email

• リクエストヘッダー

フィールド	タイプ
コンテンツタイプ	application/json
認証	bearer
トピック	Hive コンソール > 通知 > SMS OTP > 送信情報設定 > 登録または変更 > 送信ID

• リクエストボディ

フィールド	タイプ	必須	説明
sender	文字列	O	送信者のメールアドレス
senderName	文字列	O	メールの送信者名
receiver	文字列	O	受信者のメールアドレス
subject	文字列	O	メールのタイトル
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番号
expiry	文字列	OTPの有効時間

• リクエストサンプル

//sample
curl --location 'https://otp.qpyou.cn/otp/email/send' 
--header 'Authorization: bearer AUTH_TOKEN_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data-raw '{
    "sender" : "staging-no-reply@withhive.com",
    "senderName" : "YOUR SERVICE NAME",
    "receiver" : "com2us@com2us.com",
    "subject" : "OTP EMAIL SEND",
    "lang" : "ko"
}'

• レスポンスサンプル

{
    "otp" : "123456",
    "expiry" : "2022-07-20T15:19:19.305116+09:00[Asia/Seoul]"
}

---

OTPを確認する

メソッド	POST
URL	/otp/verify

• リクエストヘッダー

フィールド	タイプ
コンテンツタイプ	application/json
認証	bearer
トピック	Hive コンソール > 通知 > SMS OTP > 送信情報設定 > 登録または変更 > 送信ID

• リクエストボディ

フィールド	タイプ	必須	説明
toCountryNo	文字列	X	受信した国コード（SMSでOTPを受信する場合は必須）
to	文字列	X	受信した電話番号（SMSでOTPを受信する場合は必須）
receiver	文字列	X	受信したメールアドレス（メールでOTPを受信する場合は必須）
otp	文字列	O	受信したOTP

• レスポンスヘッダー

フィールド	タイプ
コンテンツタイプ	application/json

• レスポンスボディ

フィールド	種類	説明
result	ブール値	OTP検証結果

• リクエストサンプル 1

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

• リクエストサンプル 2

//sample 2
curl --location 'https://otp.qpyou.cn/otp/verify' 
--header 'Authorization: bearer AUTH_TOKEN_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data-raw '{
    "receiver" : "com2us@com2us.com",
    "otp" : "123456"
}'

• レスポンスサンプル

{
    "result" : true (or false)
}

---