Developer

API Docs

เรียกใช้งานทุกอย่างผ่าน HTTP GET เดียว ไม่ต้องติดตั้ง SDK ตอบกลับเป็น text หรือ JSON

ภาพรวม

API ของ GodOTP เป็น REST แบบ GET ทุก action ใช้ endpoint เดียวกัน และแยกด้วยพารามิเตอร์ action ส่วนการยืนยันตัวตนใช้พารามิเตอร์ api_key

Base URL

https://godotp.app/api

ทุก request ต้องเรียกผ่าน HTTPS เท่านั้น

เริ่มต้นใช้งานใน 3 คำสั่ง

# 1. ขอเบอร์
curl "https://godotp.app/api?api_key=sk_live_xxx&action=getNumber&service=tg&country=52"
ACCESS_NUMBER:123456:+66912345678

# 2. poll จนกว่าจะได้รหัส
curl "https://godotp.app/api?api_key=sk_live_xxx&action=getStatus&id=123456"
STATUS_WAIT_CODE
STATUS_OK:123456

# 3. ถ้าไม่ต้องการแล้ว ยกเลิกเพื่อคืนเครดิต
curl "https://godotp.app/api?api_key=sk_live_xxx&action=setStatus&id=123456&status=cancel"
ACCESS_CANCEL

ราคาที่ระบบเรียกเก็บคือราคาที่แสดงในตารางราคาเสมอ และระบบเลือกเส้นทางเครือข่ายที่ดีที่สุดให้อัตโนมัติ API จึงไม่มีพารามิเตอร์สำหรับกำหนดเพดานราคาหรือเลือกเส้นทางเอง

วิธีสร้าง API key

1สมัครสมาชิกและยืนยันอีเมล จากนั้นเข้าสู่ระบบ
2ไปที่ ตั้งค่า → API Keys แล้วกดสร้าง key ใหม่
3ตั้งชื่อ key ให้สื่อถึงระบบที่จะเรียกใช้ และระบุ IP whitelist หากต้องการจำกัดต้นทาง
4คัดลอกค่า key ทันทีหลังสร้าง ระบบแสดงค่าเต็มเพียงครั้งเดียว หลังจากนั้นจะเห็นเฉพาะรูปแบบที่ปิดบังไว้
5เก็บ key ไว้ฝั่งเซิร์ฟเวอร์เท่านั้น หากรั่วไหลให้กด revoke แล้วสร้าง key ใหม่

รูปแบบของ key

key ขึ้นต้นด้วย sk_live_ และถูกแสดงแบบปิดบังหลังสร้างเสร็จ เช่น sk_live_ab••••••••••

สมัครสมาชิกเพื่อสร้าง key

รูปแบบการเรียกและ response

ทุก request เป็น GET /api พร้อม api_key และ action ค่าเริ่มต้นตอบกลับเป็น plain text บรรทัดเดียวเพื่อให้ parse ได้ง่ายในสคริปต์ หากต้องการ JSON ให้เติม &json=1

พารามิเตอร์	จำเป็น	คำอธิบาย
api_key	จำเป็น	API key ของบัญชี ส่งจากฝั่งเซิร์ฟเวอร์เท่านั้น
action	จำเป็น	คำสั่งที่ต้องการเรียก ดูรายการทั้งหมดในหัวข้อถัดไป
json	ไม่จำเป็น	ใส่ 1 เพื่อรับ response เป็น JSON

เปลี่ยนเป็น JSON ด้วย &json=1

curl "https://godotp.app/api?api_key=sk_live_xxx&action=getNumber&service=tg&country=52&json=1"

{
  "success": true,
  "orderId": "123456",
  "phoneNumber": "+66912345678",
  "price": 15,
  "currency": "THB",
  "status": "waiting_sms"
}

Endpoint ทั้งหมด

GETaction=getBalance

ตรวจสอบยอดเครดิตคงเหลือ

คืนยอดเครดิตที่ใช้ได้ในขณะนั้น ไม่รวมยอดที่ถูกกันไว้กับออเดอร์ที่ยังไม่ปิด

ไม่มีพารามิเตอร์เพิ่มเติมนอกจาก api_key และ action

Request

GET https://godotp.app/api?api_key=sk_live_xxx&action=getBalance

Response — text

ACCESS_BALANCE:1250.00

Response — JSON (&json=1)

{
  "success": true,
  "balance": 1250,
  "currency": "THB"
}

GETaction=getNumber

ขอเบอร์ใหม่

สร้างออเดอร์ กันเครดิตตามราคาที่แสดงในตารางราคา แล้วคืนหมายเลขที่พร้อมรับ SMS ระบบเลือกเส้นทางเครือข่ายให้อัตโนมัติ

พารามิเตอร์	จำเป็น	คำอธิบาย
service	จำเป็น	service code จาก action=getServices
country	จำเป็น	country code จาก action=getCountries

Request

GET https://godotp.app/api?api_key=sk_live_xxx&action=getNumber&service=tg&country=52

Response — text

ACCESS_NUMBER:123456:+66912345678

# กรณีผิดพลาด
NO_NUMBERS
NO_BALANCE
BAD_SERVICE
BAD_COUNTRY

Response — JSON (&json=1)

{
  "success": true,
  "orderId": "123456",
  "phoneNumber": "+66912345678",
  "price": 15,
  "currency": "THB",
  "status": "waiting_sms"
}

GETaction=getStatus

ตรวจสอบสถานะออเดอร์และดึงรหัส OTP

เรียกซ้ำเพื่อ poll สถานะ จนกว่าจะได้รับข้อความ หรือจะใช้ webhook แทนการ poll ก็ได้

พารามิเตอร์	จำเป็น	คำอธิบาย
id	จำเป็น	order id ที่ได้จาก getNumber

Request

GET https://godotp.app/api?api_key=sk_live_xxx&action=getStatus&id=123456

Response — text

STATUS_WAIT_CODE     # ยังไม่มีข้อความเข้า
STATUS_OK:123456     # ได้รับ SMS แล้ว ตัวเลขท้ายคือรหัส OTP

# กรณีผิดพลาด
BAD_KEY

Response — JSON (&json=1)

{
  "success": true,
  "orderId": "123456",
  "phoneNumber": "+66912345678",
  "status": "sms_received",
  "otpCode": "123456",
  "message": "Your code is 123456",
  "receivedAt": "2026-09-17T15:00:00Z"
}

GETaction=setStatus

ยกเลิกออเดอร์

ยกเลิกออเดอร์ที่ยังรอ SMS อยู่ ระบบจะคืนเครดิตที่กันไว้กลับเข้า Wallet ทันที

พารามิเตอร์	จำเป็น	คำอธิบาย
id	จำเป็น	order id ที่ต้องการเปลี่ยนสถานะ
status	จำเป็น	ค่าที่รองรับ: cancel

Request

GET https://godotp.app/api?api_key=sk_live_xxx&action=setStatus&id=123456&status=cancel

Response — text

ACCESS_CANCEL

# กรณีผิดพลาด
ORDER_NOT_FOUND

Response — JSON (&json=1)

{
  "success": true,
  "orderId": "123456",
  "status": "cancelled",
  "refunded": 15,
  "currency": "THB"
}

GETaction=getPrices

ดึงตารางราคา

คืนราคาขายและจำนวนเบอร์ที่พร้อมใช้งาน กรองด้วย service และ country ได้ ราคาที่ได้คือราคาสุดท้ายที่จะถูกกันเมื่อสั่งซื้อ

พารามิเตอร์	จำเป็น	คำอธิบาย
service	ไม่จำเป็น	กรองเฉพาะบริการที่ระบุ
country	ไม่จำเป็น	กรองเฉพาะประเทศที่ระบุ

Request

GET https://godotp.app/api?api_key=sk_live_xxx&action=getPrices&service=tg&country=52

Response — text

52:tg:15.00:1420

Response — JSON (&json=1)

{
  "success": true,
  "prices": [
    {
      "country": "52",
      "service": "tg",
      "price": 15,
      "currency": "THB",
      "available": 1420,
      "avgWaitSeconds": 45
    }
  ]
}

GETaction=getCountries

ดึงรายการประเทศ

รายการ country code ทั้งหมดที่เปิดให้บริการอยู่

ไม่มีพารามิเตอร์เพิ่มเติมนอกจาก api_key และ action

Request

GET https://godotp.app/api?api_key=sk_live_xxx&action=getCountries

Response — text

52:Thailand
6:Indonesia
10:Vietnam

Response — JSON (&json=1)

{
  "success": true,
  "countries": [
    { "code": "52", "name": "Thailand", "available": 1420 },
    { "code": "6", "name": "Indonesia", "available": 2850 }
  ]
}

GETaction=getServices

ดึงรายการบริการ

รายการ service code ทั้งหมดที่เปิดให้บริการอยู่

ไม่มีพารามิเตอร์เพิ่มเติมนอกจาก api_key และ action

Request

GET https://godotp.app/api?api_key=sk_live_xxx&action=getServices

Response — text

tg:Telegram
wa:WhatsApp
ot:Other

Response — JSON (&json=1)

{
  "success": true,
  "services": [
    { "code": "tg", "name": "Telegram", "available": 980 },
    { "code": "ot", "name": "Other", "available": 5200 }
  ]
}

Error code

คอลัมน์แรกคือรหัสภายในที่ปรากฏใน response แบบ JSON ส่วนคอลัมน์ถัดมาคือข้อความที่ได้รับเมื่อใช้ response แบบ text

error code	text response	ความหมาย
NO_NUMBER_AVAILABLE	NO_NUMBERS	ไม่มีเบอร์ว่างสำหรับประเทศและบริการที่ขอในขณะนั้น ลองใหม่อีกครั้งหรือเปลี่ยนประเทศ
INSUFFICIENT_CREDIT	NO_BALANCE	เครดิตใน Wallet ไม่พอสำหรับราคาของออเดอร์นี้
INVALID_API_KEY	BAD_KEY	API key ไม่ถูกต้อง ถูกเพิกถอน หรือเรียกจาก IP ที่ไม่อยู่ใน whitelist
COUNTRY_NOT_SUPPORTED	BAD_COUNTRY	country code ไม่ถูกต้องหรือยังไม่เปิดให้บริการ
SERVICE_NOT_SUPPORTED	BAD_SERVICE	service code ไม่ถูกต้องหรือยังไม่เปิดให้บริการ
ORDER_NOT_FOUND	ORDER_NOT_FOUND	ไม่พบออเดอร์ตาม id ที่ส่งมา หรือออเดอร์ไม่ได้เป็นของบัญชีนี้
SMS_NOT_RECEIVED_YET	STATUS_WAIT_CODE	ออเดอร์ยังรอ SMS อยู่ ยังไม่ถือเป็นข้อผิดพลาด ให้ poll ซ้ำหรือรอ webhook
ORDER_EXPIRED	ORDER_EXPIRED	ออเดอร์หมดเวลารอแล้ว ระบบคืนเครดิตให้อัตโนมัติ
RATE_LIMITED	RATE_LIMITED	เรียก API ถี่เกินเพดานที่กำหนด ให้หน่วงเวลาแล้วลองใหม่
PROVIDER_TIMEOUT	NO_NUMBERS	เส้นทางเครือข่ายตอบกลับช้าเกินกำหนด ระบบพยายามใช้เส้นทางสำรองแล้วไม่สำเร็จ
PROVIDER_API_ERROR	NO_NUMBERS	เส้นทางเครือข่ายตอบกลับผิดพลาด เครดิตที่กันไว้จะถูกคืนให้อัตโนมัติ
UNKNOWN_ERROR	UNKNOWN_ERROR	ข้อผิดพลาดที่ไม่ได้ระบุไว้ กรุณาติดต่อฝ่ายสนับสนุนพร้อมแจ้ง order id

ตัวอย่าง error ในรูปแบบ JSON

{
  "success": false,
  "code": "NO_BALANCE",
  "message": "เครดิตคงเหลือไม่พอสำหรับออเดอร์นี้"
}

Rate limit

เพดานคิดแยกตาม API key เมื่อถึงเพดาน ระบบตอบกลับ RATE_LIMITED แนะนำให้ทำ exponential backoff ก่อนเรียกซ้ำ

ขอบเขต	เพดาน	หมายเหตุ
ทุก action รวมกันต่อ API key	60 ครั้ง / นาที	เกินเพดานจะได้รับ RATE_LIMITED จนกว่าจะพ้นหน้าต่างเวลา
action=getNumber	20 ครั้ง / นาที	ป้องกันการสั่งซื้อรัวและรักษาคุณภาพของกลุ่มเบอร์
action=getStatus (poll)	1 ครั้ง / 3 วินาที ต่อหนึ่งออเดอร์	แนะนำให้ใช้ webhook แทนการ poll ถี่ ๆ

Webhook

ตั้งค่า Webhook URL และ secret ได้จากหน้า ตั้งค่า → Webhooks ระบบจะส่ง HTTP POST พร้อม payload แบบ JSON และลงลายเซ็น HMAC-SHA256 ของ raw body ไว้ในเฮดเดอร์ X-GodOTP-Signature

event	ส่งเมื่อ
sms.received	มีข้อความเข้าและระบบแยกรหัส OTP ได้แล้ว เครดิตถูกตัดตามราคาออเดอร์
order.expired	ออเดอร์หมดเวลารอโดยไม่มีข้อความเข้า
order.refunded	เครดิตที่กันไว้ถูกคืนกลับเข้า Wallet เรียบร้อยแล้ว

ตัวอย่าง payload

POST https://your-server.example.com/hooks/godotp
Content-Type: application/json
X-GodOTP-Signature: sha256=<hmac ของ raw body ด้วย secret ของคุณ>

{
  "event": "sms.received",
  "orderId": "123456",
  "phoneNumber": "+66912345678",
  "message": "Your code is 123456",
  "receivedAt": "2026-09-17T15:00:00Z"
}

ตอบกลับสถานะ 2xx ภายใน 10 วินาที มิฉะนั้นระบบจะลองส่งซ้ำแบบถอยเวลาเพิ่มขึ้นเรื่อย ๆ
ตรวจสอบลายเซ็นก่อนเชื่อถือ payload เสมอ โดยคำนวณ HMAC-SHA256 ของ raw body ด้วย secret ของคุณแล้วเทียบกับเฮดเดอร์
ออกแบบตัวรับให้ idempotent เพราะ event เดียวกันอาจถูกส่งซ้ำได้

พร้อมเชื่อมต่อ API แล้วหรือยัง?

สมัครสมาชิกเพื่อสร้าง API key และเริ่มทดสอบ integration ได้ทันที

สมัครสมาชิกฟรี ดูตารางราคา