Skip to content

การยืนยันตัวตน ​

ทุก request (ยกเว้นลิงก์ redirect /s/:code) ต้องส่ง header Authorization มาด้วย ระบบรองรับ 3 รูปแบบ

รูปแบบHeaderสถานะ
API KeyAuthorization: Bearer smsk_...แนะนำ
BasicAuthorization: Basic base64(username:password)รองรับ (เข้ากันได้กับระบบเดิม)
Legacy tokenAuthorization: Bearer <JWT>รองรับเพื่อความเข้ากันได้กับระบบเดิม — ควรย้ายไปใช้ API Key

WARNING

คำว่า Bearer และ Basic ต้องสะกดตามนี้ (ตัวพิมพ์ใหญ่ตัวแรก) และคั่นด้วยช่องว่าง 1 ช่อง

API Key (แนะนำ) ​

API Key มีรูปแบบ smsk_ + ตัวอักษร 8 ตัว + _ + ตัวอักษร 32 ตัว (A–Z, a–z, 0–9) เช่น

text
smsk_Ab12Cd34_0123456789abcdefghijABCDEFGHIJ01
bash
curl 'https://public-api.smsup-plus.com/sms/senderlist' \
  -H 'Authorization: Bearer smsk_Ab12Cd34_0123456789abcdefghijABCDEFGHIJ01'
js
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

bash
curl 'https://public-api.smsup-plus.com/sms/senderlist' \
  -u 'myuser:mypassword'
# เทียบเท่า -H 'Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ='
js
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": "<ข้อความ>"}

HTTPerrorสาเหตุ
401missing authorization headerไม่ได้ส่ง header Authorization
401invalid authorization formatheader ไม่อยู่ในรูป <scheme> <ค่า>
401unsupported authorization schemescheme ไม่ใช่ Bearer หรือ Basic
401invalid api keyไม่พบ API Key นี้
401api key revokedAPI Key ถูกยกเลิกแล้ว
401api key expiredAPI Key หมดอายุ
403ip not allowedIP ต้นทางไม่อยู่ในรายการที่อนุญาตของ key
401session revokedผู้ใช้หรือบัญชีเจ้าของ credential ถูกระงับ
401invalid basic auth encodingค่า Basic ไม่ใช่ Base64 ที่ถูกต้อง
401invalid credentials formatค่าที่ถอดรหัสแล้วไม่มี :
401invalid credentialsusername หรือ password ไม่ถูกต้อง
401user account is inactiveผู้ใช้ถูกปิดใช้งาน
401account is inactiveบัญชีถูกปิดใช้งาน
401invalid tokenlegacy token ไม่ถูกต้องหรือหมดอายุ
401web session token not accepted, use an API keyใช้ token จากการล็อกอินหน้าเว็บ
401api token revokedlegacy token ถูกยกเลิก
401legacy api token disabled, use an API keyระบบปิดการรับ legacy token
500internal errorระบบขัดข้องชั่วคราว ลองใหม่อีกครั้ง

Rate limit ​

ใช้กับ endpoint กลุ่ม /sms/* และ /OTP/* นับแบบช่วงเวลา 1 วินาที

ขอบเขตค่าเริ่มต้น
ต่อ IP ต้นทาง (นับก่อนตรวจ credential)100 request/วินาที
ต่อบัญชี50 request/วินาที (ปรับรายบัญชีได้ — ติดต่อฝ่ายดูแลลูกค้า)
ต่อ API Keyไม่จำกัดแยก (นับรวมในโควตาต่อบัญชี)

เมื่อเกินจะได้ HTTP 429 พร้อม header Retry-After: 1

json
{
  "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 เดิม ระบบจะไม่ส่งซ้ำและไม่ตัดเครดิตซ้ำ

หัวข้อรายละเอียด
HeaderIdempotency-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 เดิมได้ทันที
bash
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"}]}'
HTTPResponseสาเหตุ
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