One-Time Password(OTP) API¶

ระบบการยืนยันตัวตนแบบ One-Time Password(OTP) มี API ที่ประกอบด้วย การส่ง OTP และ การตรวจสอบ OTP เพื่อให้สามารถนำการยืนยันตัวตนด้วย OTP ไปใช้กับเกมได้

URL¶

วิธีการตรวจสอบสิทธิ์¶

หากต้องการใช้ API ที่ระบบส่ง OTP มีให้ คุณต้องได้รับโทเค็นยืนยันตัวตน(API KEY) ก่อน โทเค็นยืนยันตัวตนจะถูกสร้างขึ้นโดยอัตโนมัติเมื่อมีการลงทะเบียนเกมใน App Center โทเค็นยืนยันตัวตนเป็นไปตามข้อกำหนด JSON Web Token(JWT) และสามารถใช้งานได้อย่างต่อเนื่องเนื่องจากไม่มีเวลาหมดอายุ

ส่ง OTP¶

การส่ง OTP ทาง Short Message Service(SMS)¶

• ข้อมูลพื้นฐาน

• ส่วนหัวของคำขอ

• ต้องมีการเรียกกลับเมื่อคุณส่ง SMS OTP โดยตรง

  หากไม่ได้ให้ระบบ OTP ส่ง OTP SMS โดยตรง แต่ให้นักพัฒนาแอปส่งเอง คุณสามารถรับข้อมูลที่จำเป็นสำหรับการส่งผ่าน callback ได้ เมื่อเลือก ส่งด้วยตนเอง ใน Hive Console > การแจ้งเตือน > SMS OTP > การตั้งค่าข้อมูลการส่ง ข้อมูลด้านล่างจะถูกส่งไปยัง callback URL ที่ลงทะเบียนไว้ในรูปแบบ JSON ใน Request Body สำหรับวิธีตั้งค่า โปรดดู ส่งด้วยตนเอง และโปรดดู ตัวอย่างคำขอ callback กับ ข้อมูลที่ส่ง ร่วมกัน.

• เนื้อหาคำขอ

• ส่วนหัวของการตอบกลับ

• เนื้อหาการตอบกลับ

• ตัวอย่างคำขอ

ตัวอย่างต่อไปนี้ใช้เมื่อเรียก API ส่ง OTP SMS โดยระบุเฮดเดอร์ 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
}

ตัวอย่างการเรียกกลับ¶

หากตั้งค่าให้นักพัฒนาแอปส่งเอง callback URL ที่ลงทะเบียนไว้จะได้รับ request body ดังต่อไปนี้

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 ของ request header ไม่ตรงกับ รหัสการส่ง ที่ลงทะเบียนไว้ใน Hive Console ข้อผิดพลาดนี้จะเกิดขึ้น โปรดตรวจสอบค่าเฮดเดอร์ Topic และ รหัสการส่ง ที่ลงทะเบียนไว้ใน Hive Console > การแจ้งเตือน > SMS OTP > การตั้งค่าข้อมูลการส่ง.

{
    "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¶

• ส่วนหัวของคำขอ

• เนื้อหาคำขอ

• ส่วนหัวการตอบกลับ

• เนื้อหาการตอบกลับ

• ตัวอย่างคำขอ 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
}