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)
}