การยืนยันตัวตน
ทุก request (ยกเว้นลิงก์ redirect /s/:code) ต้องส่ง header Authorization มาด้วย ระบบรองรับ 3 รูปแบบ
| รูปแบบ | Header | สถานะ |
|---|---|---|
| API Key | Authorization: Bearer smsk_... | แนะนำ |
| Basic | Authorization: Basic base64(username:password) | รองรับ (เข้ากันได้กับระบบเดิม) |
| Legacy token | Authorization: Bearer <JWT> | รองรับเพื่อความเข้ากันได้กับระบบเดิม — ควรย้ายไปใช้ API Key |
WARNING
คำว่า Bearer และ Basic ต้องสะกดตามนี้ (ตัวพิมพ์ใหญ่ตัวแรก) และคั่นด้วยช่องว่าง 1 ช่อง
API Key (แนะนำ)
API Key มีรูปแบบ smsk_ + ตัวอักษร 8 ตัว + _ + ตัวอักษร 32 ตัว (A–Z, a–z, 0–9) เช่น
smsk_Ab12Cd34_0123456789abcdefghijABCDEFGHIJ01curl 'https://public-api.smsup-plus.com/sms/senderlist' \
-H 'Authorization: Bearer smsk_Ab12Cd34_0123456789abcdefghijABCDEFGHIJ01'const res = await fetch('https://public-api.smsup-plus.com/sms/senderlist', {
headers: { Authorization: `Bearer ${process.env.SMSUP_API_KEY}` },
})
console.log(await res.json())| คุณสมบัติ | รายละเอียด |
|---|---|
| สร้างที่ไหน | พอร์ทัลลูกค้า |
| การเก็บ | ระบบเก็บเฉพาะค่า hash ของ key — key เต็มแสดงเพียงตอนสร้าง หากทำหายให้สร้างใหม่ |
| จำนวน | ผู้ใช้ 1 คนมี key ที่ใช้งานอยู่ได้สูงสุด 10 key |
| อายุ | ไม่หมดอายุ หรือ 30 / 90 / 180 / 365 วัน |
| จำกัด IP | กำหนดรายการ IP หรือ CIDR ที่อนุญาตต่อ key ได้ — ถ้าไม่กำหนด ใช้ได้ทุก IP |
| สิทธิ์ | key ทำงานในนามผู้ใช้ที่สร้าง ผู้ใช้และบัญชีต้องยังเปิดใช้งานอยู่ |
| การยกเลิก | ยกเลิก (revoke) ได้ในพอร์ทัล มีผลภายในประมาณ 10 วินาที |
Basic
ส่ง username:password ของผู้ใช้พอร์ทัลลูกค้า เข้ารหัส Base64
curl 'https://public-api.smsup-plus.com/sms/senderlist' \
-u 'myuser:mypassword'
# เทียบเท่า -H 'Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ='const auth = Buffer.from('myuser:mypassword').toString('base64')
const res = await fetch('https://public-api.smsup-plus.com/sms/senderlist', {
headers: { Authorization: `Basic ${auth}` },
})
console.log(await res.json())ผู้ใช้ต้องเปิดใช้งานอยู่ และบัญชีของผู้ใช้ต้องเปิดใช้งานอยู่
TIP
แนะนำให้ใช้ API Key แทน Basic — API Key ยกเลิกได้ทีละ key, จำกัด IP ได้ และไม่ต้องฝังรหัสผ่านไว้ในระบบของคุณ
Legacy token (JWT)
token แบบ JWT ที่ออกให้ระบบเชื่อมต่อรุ่นเก่ายังใช้ได้ผ่าน Authorization: Bearer <JWT> โดยมีเงื่อนไข
- token ที่ได้จากการล็อกอินหน้าเว็บพอร์ทัลใช้กับ API นี้ไม่ได้ (
web session token not accepted, use an API key) - ผู้ใช้และบัญชีต้องยังเปิดใช้งานอยู่ และ token ต้องไม่ถูกยกเลิก
สำหรับการเชื่อมต่อใหม่ ให้ใช้ API Key
Error การยืนยันตัวตน
ทุก error ในขั้นนี้ตอบเป็น {"error": "<ข้อความ>"}
| HTTP | error | สาเหตุ |
|---|---|---|
| 401 | missing authorization header | ไม่ได้ส่ง header Authorization |
| 401 | invalid authorization format | header ไม่อยู่ในรูป <scheme> <ค่า> |
| 401 | unsupported authorization scheme | scheme ไม่ใช่ Bearer หรือ Basic |
| 401 | invalid api key | ไม่พบ API Key นี้ |
| 401 | api key revoked | API Key ถูกยกเลิกแล้ว |
| 401 | api key expired | API Key หมดอายุ |
| 403 | ip not allowed | IP ต้นทางไม่อยู่ในรายการที่อนุญาตของ key |
| 401 | session revoked | ผู้ใช้หรือบัญชีเจ้าของ credential ถูกระงับ |
| 401 | invalid basic auth encoding | ค่า Basic ไม่ใช่ Base64 ที่ถูกต้อง |
| 401 | invalid credentials format | ค่าที่ถอดรหัสแล้วไม่มี : |
| 401 | invalid credentials | username หรือ password ไม่ถูกต้อง |
| 401 | user account is inactive | ผู้ใช้ถูกปิดใช้งาน |
| 401 | account is inactive | บัญชีถูกปิดใช้งาน |
| 401 | invalid token | legacy token ไม่ถูกต้องหรือหมดอายุ |
| 401 | web session token not accepted, use an API key | ใช้ token จากการล็อกอินหน้าเว็บ |
| 401 | api token revoked | legacy token ถูกยกเลิก |
| 401 | legacy api token disabled, use an API key | ระบบปิดการรับ legacy token |
| 500 | internal error | ระบบขัดข้องชั่วคราว ลองใหม่อีกครั้ง |
Rate limit
ใช้กับ endpoint กลุ่ม /sms/* และ /OTP/* นับแบบช่วงเวลา 1 วินาที
| ขอบเขต | ค่าเริ่มต้น |
|---|---|
| ต่อ IP ต้นทาง (นับก่อนตรวจ credential) | 100 request/วินาที |
| ต่อบัญชี | 50 request/วินาที (ปรับรายบัญชีได้ — ติดต่อฝ่ายดูแลลูกค้า) |
| ต่อ API Key | ไม่จำกัดแยก (นับรวมในโควตาต่อบัญชี) |
เมื่อเกินจะได้ HTTP 429 พร้อม header Retry-After: 1
{
"error": {
"statusCode": "429",
"description": "rate limit exceeded: max 50 requests per second per account",
"message": "TOO_MANY_REQUESTS"
}
}ข้อความ description ลงท้ายด้วย per IP, per account หรือ per API key ตามขอบเขตที่เกิน ให้รออย่างน้อยตาม Retry-After (วินาที) แล้วลองใหม่
Idempotency-Key (ป้องกันส่งซ้ำ)
ใช้กับ POST /sms/send และ POST /OTP/requestotp เท่านั้น — เมื่อ retry ด้วย key เดิม ระบบจะไม่ส่งซ้ำและไม่ตัดเครดิตซ้ำ
| หัวข้อ | รายละเอียด |
|---|---|
| Header | Idempotency-Key: <ค่า> (ไม่บังคับ — ไม่ส่งก็ทำงานตามปกติ) |
| รูปแบบ | A–Z a–z 0–9 _ - ยาว 1–128 ตัว เช่น UUID |
| ขอบเขต | แยกตามบัญชี — key เดียวกันจากคนละบัญชีไม่ชนกัน |
| เก็บผลไว้ | 24 ชั่วโมง เฉพาะผลที่สำเร็จ (HTTP 2xx) |
| Replay | ได้ HTTP status และ body เดิมกลับมา พร้อม header Idempotent-Replayed: true |
| ผลไม่สำเร็จ | ระบบไม่เก็บ key — retry ด้วย key เดิมได้ทันที |
curl -X POST 'https://public-api.smsup-plus.com/sms/send' \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 7d9f2c1e-4b8a-4e0f-9a3b-1c2d3e4f5a6b' \
-d '{"messages":[{"from":"MYBRAND","destinations":[{"to":"0812345678"}],"text":"hello"}]}'| HTTP | Response | สาเหตุ |
|---|---|---|
| 400 | {"error":"invalid Idempotency-Key"} | ค่า header ไม่ตรงรูปแบบ |
| 409 | {"error":"request with this Idempotency-Key is in progress"} | request ก่อนหน้าที่ใช้ key เดียวกันยังทำงานไม่เสร็จ — รอสักครู่แล้วลองใหม่ |
WARNING
ระบบไม่เปรียบเทียบ body — ถ้าใช้ key เดิมกับข้อมูลใหม่ภายใน 24 ชั่วโมง จะได้ผลลัพธ์ของ request แรกกลับมาโดยไม่ส่งข้อความใหม่ ใช้ key ใหม่ทุกครั้งที่เป็นการส่งใหม่
บันทึกการเรียก API
ทุก request ที่เข้ามายัง endpoint ที่ต้องยืนยันตัวตนจะถูกบันทึกเป็นประวัติการเรียก API (รวมถึง request ที่ credential ไม่ผ่าน) โดยไม่บันทึกค่า API Key
