ขอ OTP POST
ใช้สร้างรหัส OTP และส่งทาง SMS ไปยังเบอร์ผู้ใช้ ระบบตอบกลับ otpId (ใช้ตอน ยืนยัน OTP และ ส่ง OTP ซ้ำ) และ referenceCode (ให้แสดงบนหน้าจอให้ผู้ใช้เทียบกับ SMS) — ตัวรหัส OTP จะไม่ถูกส่งกลับใน response
Authorization
ใช้ API Key (การยืนยันตัวตน) ส่งใน header Authorization: Bearer <API_KEY>
รองรับ header Idempotency-Key (ไม่บังคับ) เพื่อกันการส่ง OTP ซ้ำเมื่อ retry — กติกาเหมือน ส่ง SMS: ตัวอักษร A-Z a-z 0-9 _ - ยาว 1–128 ตัว, เก็บผลที่สำเร็จ 24 ชั่วโมง, คำขอซ้ำได้ผลเดิมพร้อม header Idempotent-Replayed: true, ถ้าคำขอแรกไม่สำเร็จ (รวมกรณีตอบ HTTP 200 แบบมี error) key ใช้ซ้ำได้ทันที
HTTP Request
POST https://public-api.smsup-plus.com/OTP/requestotpContent Type
application/json (รับเฉพาะ JSON)
Parameter Description
| Property | Type | Required | Description |
|---|---|---|---|
otcid | string | Required | รหัสการตั้งค่า OTP (OTP config) ของบัญชีคุณ สร้างได้ที่เมนู OTP บนเว็บ SMSUP Plus — กำหนดชื่อผู้ส่ง ข้อความ ความยาวรหัส อายุ และจำนวนครั้งที่ยืนยันได้ |
mobile | string | Required | เบอร์มือถือไทย รูปแบบเดียวกับ to ใน ส่ง SMS เช่น 0812345678 |
notifyUrl | string | Optional | รับค่าไว้เพื่อความเข้ากันได้กับระบบเดิม ปัจจุบันไม่มีผล |
notifyContentType | string | Optional | รับค่าไว้เพื่อความเข้ากันได้กับระบบเดิม ปัจจุบันไม่มีผล |
callbackData | string | Optional | รับค่าไว้เพื่อความเข้ากันได้กับระบบเดิม ปัจจุบันไม่มีผล |
vp | string | Optional | รับค่าไว้เพื่อความเข้ากันได้กับระบบเดิม ปัจจุบันไม่มีผล (อายุ OTP มาจาก OTP config) |
พฤติกรรมของ OTP
| เรื่อง | ค่า |
|---|---|
| รหัส OTP | ตัวเลขตามความยาวใน OTP config (ค่าเริ่มต้น 6 หลัก, ตั้งได้ตั้งแต่ 4 หลัก) นำหน้าด้วย prefix ถ้ากำหนดไว้ |
| Reference code | ตัวอักษรภาษาอังกฤษพิมพ์ใหญ่ 6 ตัว เช่น KQZPWD คงเดิมแม้ ส่ง OTP ซ้ำ |
| อายุ OTP | ตาม OTP config (ค่าเริ่มต้น 300 วินาที, ขั้นต่ำ 30 วินาที) นับจากเวลาที่ขอ |
| จำนวนครั้งที่ยืนยันผิดได้ | ตาม OTP config (ค่าเริ่มต้น 3 ครั้ง) |
| จำนวนครั้งที่ส่งซ้ำได้ | 3 ครั้งต่อ otpId |
| ข้อความ SMS | จาก template ใน OTP config — {Code OTP} ถูกแทนด้วยรหัส, {Ref Code} ด้วย reference code, {...} อื่นถูกลบทิ้ง (ค่าเริ่มต้น Your OTP code is {Code OTP}. Ref: {Ref Code}) |
| จำกัดการขอ | สูงสุด 3 ครั้งต่อเบอร์ต่อบัญชี ภายใน 10 นาที |
| เครดิต | บัญชี prepaid ต้องมีเครดิตอย่างน้อย 1 — SMS OTP แต่ละครั้งคิดเครดิตตามความยาวข้อความเหมือน ส่ง SMS |
SMS OTP ไม่ถูกบล็อกจากรายการผู้รับที่ขอยกเลิกรับ SMS ทั่วไป (opt-out) หรือการกำหนดให้ต้องมี consent
Response Description
ตอบ HTTP 200 ทั้งกรณีสำเร็จและบางกรณีที่ล้มเหลว — ให้ตรวจว่ามี success หรือ error
| Property | Type | Description |
|---|---|---|
otcId | string | otcid ที่ส่งมา |
otpId | string | รหัสของ OTP นี้ (UUID) ใช้กับ ยืนยัน OTP และ ส่ง OTP ซ้ำ |
referenceCode | string | Reference code 6 ตัวอักษร |
success.code | string | "200" |
success.message | string | SUCCESS |
success.description | string | OTP has been sent successfully |
ตัวอย่าง Request
curl -X POST 'https://public-api.smsup-plus.com/OTP/requestotp' \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 5a0e2d4c-1f3b-4e6a-8c9d-7b2a1e0f3c4d' \
-d '{
"otcid": "c2a4e6f8-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
"mobile": "0812345678"
}'const res = await fetch('https://public-api.smsup-plus.com/OTP/requestotp', {
method: 'POST',
headers: {
Authorization: 'Bearer <API_KEY>',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
otcid: 'c2a4e6f8-1b3d-4f5a-9c7e-0d2b4f6a8c1e',
mobile: '0812345678',
}),
})
console.log(await res.json())ตัวอย่าง Response
{
"otcId": "c2a4e6f8-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
"otpId": "7f3c9a1e-2b4d-4c6e-8a0f-1e3d5b7c9a2f",
"referenceCode": "KQZPWD",
"success": {
"code": "200",
"message": "SUCCESS",
"description": "OTP has been sent successfully"
}
}Error ที่อาจเจอ
ข้อผิดพลาดของ OTP อยู่ในรูป {"error":{"code","message","description"}} (ยกเว้น Idempotency-Key, rate limit และ การยืนยันตัวตน) ดูภาพรวมที่ รหัสข้อผิดพลาด
| HTTP | Response | สาเหตุ |
|---|---|---|
| 200 | {"error":{"code":"500","message":"INTERNAL_SERVER_ERROR","description":"Failed to process OTP request"}} | เบอร์ไม่ถูกต้อง, ขอเกิน 3 ครั้งใน 10 นาทีสำหรับเบอร์นี้ หรือระบบขัดข้องชั่วคราว — ไม่มี OTP ถูกสร้าง |
| 400 | {"error":{"code":"400","message":"BAD_REQUEST","description":"Invalid request body"}} | body ไม่ใช่ JSON ที่ถูกต้อง หรือไม่มี otcid / mobile |
| 400 | {"error":"invalid Idempotency-Key"} | Idempotency-Key มีอักขระไม่อนุญาตหรือยาวเกิน 128 |
| 402 | {"error":{"code":"402","message":"INSUFFICIENT_CREDIT","description":"insufficient credit: required 1.00, available 0.00"}} | บัญชี prepaid มีเครดิตไม่ถึง 1 |
| 403 | {"error":{"code":"403","message":"ACCOUNT_INACTIVE","description":"account is inactive"}} | บัญชีถูกปิดใช้งาน |
| 403 | {"error":{"code":"403","message":"ACCOUNT_HELD","description":"account is on credit hold"}} | บัญชีถูกระงับเครดิต |
| 403 | {"error":{"code":"403","message":"SERVICE_NOT_ALLOWED","description":"OTP is not enabled for this account"}} | บัญชียังไม่เปิดสิทธิ์ใช้ OTP |
| 404 | {"error":{"code":"404","message":"OTP_CONFIG_NOT_FOUND","description":"OTP config not found for this account"}} | ไม่พบ otcid หรือไม่ใช่ของบัญชีคุณ |
| 409 | {"error":"request with this Idempotency-Key is in progress"} | คำขอที่ใช้ key เดียวกันยังทำงานอยู่ |
| 429 | {"error":{"statusCode":"429","description":"rate limit exceeded: max 50 requests per second per account","message":"TOO_MANY_REQUESTS"}} | เรียกถี่เกินกำหนด — รอตาม header Retry-After |
| 500 | {"error":{"code":"500","message":"INTERNAL_SERVER_ERROR","description":"Failed to validate OTP request"}} | ระบบตรวจสอบคำขอไม่สำเร็จชั่วคราว |
