เอกสาร API

ทุกคำขอต้องมี API key ของคุณ:

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

รูปแบบ header ทางเลือก: X-API-Key: jm_xxx…

สร้างและเพิกถอน key ได้ที่ /account/api-keys ผู้ใช้แต่ละคนถือ key ที่ใช้งานได้สูงสุด 10 ตัว token เต็มจะแสดงเพียงครั้งเดียวตอนสร้าง — กรุณาเก็บอย่างปลอดภัย

ข้อผิดพลาดทั้งหมดคืนค่าเป็น JSON:

{ "ok": false, "code": "RATE_LIMITED", "message": "..." }

ขีดจำกัด rate: ต่อ key ในหน้าต่างเลื่อน 60s endpoint สำหรับเขียน (orders, cancel, next-sms) 10 req/min; endpoint สำหรับอ่าน (account, services, prices, list) 60 req/min

ดูยอดเงินคงเหลือปัจจุบันและโปรไฟล์พื้นฐานของคุณ

curl https://jiema.my/api/v1/account \
  -H "Authorization: Bearer jm_xxx"

# 200 OK
{ "ok": true, "data": {
  "id": "clxxxxxxxxxxx",
  "balanceCents": "1200",       // string to preserve precision; $12.00
  "referralCode": "abc123",
  "displayName": "Alice",
  "lang": "en"
}}

รายการ service พร้อมสต็อก แคชฝั่งเซิร์ฟเวอร์ประมาณ 5 นาที

curl https://jiema.my/api/v1/services -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "code": "tg", "slug": "telegram", "name": "Telegram",
    "minCostUsd": 0.18, "totalCount": 1234, "countryCount": 24 },
  ...
] }}

ใช้ code (หรือ slug ที่อ่านง่าย) เป็น field service เมื่อสร้าง order

curl https://jiema.my/api/v1/countries -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "id": 7, "slug": "my", "name": "Malaysia" },
  ...
] }}

id คือ country id แบบตัวเลขของ upstream; slug คือรหัสสั้นสำหรับ SEO (เช่น "my" / "us") ทั้งสองรูปแบบใช้เป็น field country ได้

ราคาและสต็อกของแต่ละประเทศสำหรับ service ที่กำหนด ราคารวมการ markup/ส่วนลดที่ทีม ops ตั้งค่าไว้แล้ว

curl "https://jiema.my/api/v1/prices?service=tg" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "service": "tg",
  "items": [
    { "countryId": 7, "countrySlug": "my", "priceCents": "32", "count": 540 },
    ...
  ]
}}

สร้าง order ยืนยัน SMS ระบบจะจองเบอร์โทรจาก upstream และหักจำนวนเงินที่เรียกเก็บจากยอดเงินของคุณ

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_xxx" \
  -H "content-type: application/json" \
  -d '{ "service": "tg", "country": 7 }'

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "WAITING",
  "service": "tg",
  "country": "7",
  "phone": "+60123456789",
  "expiresAt": "2026-05-22T08:30:00.000Z",
  "chargedCents": "32"
}}

ไม่มีฟิลด์ตัวเลือกอื่นนอกจาก service / country

รหัสข้อผิดพลาดทั่วไป: INSUFFICIENT (ต้องเติมเงิน), NO_NUMBERS, BAD_SERVICE, BAD_COUNTRY

Polling จนกว่า status จะกลายเป็น RECEIVED และ smsBody ไม่เป็น null

curl https://jiema.my/api/v1/orders/ckxxxxx -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "RECEIVED",
  "phone": "+60123456789",
  "smsBody": "Your verification code is 123456",
  "smsHistory": [
    { "body": "Your verification code is 123456", "receivedAt": "..." }
  ],
  "smsReceivedAt": "2026-05-22T08:12:34.000Z",
  ...
}}

สถานะ: WAITING (เบอร์ใช้งาน รอ SMS) · RECEIVED (รหัสมาถึง) · COMPLETED / FAILED / CANCELLED เป็นสถานะสุดท้าย

แนะนำ polling: ทุก 3–5 วินาที การซิงค์ upstream ทำงานภายใน endpoint นี้ ดังนั้นการ polling จะขับเคลื่อนสถานะไปข้างหน้า แม้ background worker จะไม่ว่างก็ตาม

ยกเลิก order ที่ยังไม่ได้รับรหัส คืนเงินเต็มจำนวนเข้ายอดเงินของคุณ

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/cancel \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "CANCELLED" }}

ปฏิเสธด้วย CODE_RECEIVED หากเบอร์ได้รับ SMS ใด ๆ แล้ว หรือ ALREADY_CHANGED หากสถานะเปลี่ยนแปลงพร้อมกัน

หลังจาก RECEIVED ให้ขอ upstream เก็บเบอร์ให้ใช้งานต่อและรอ SMS อีกครั้ง (ไม่มีค่าใช้จ่ายเพิ่มภายในช่วงที่ใช้งานอยู่)

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/next-sms \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "WAITING" }}

รายการ order ล่าสุดของคุณ แบ่งหน้าด้วย cursor

curl "https://jiema.my/api/v1/orders?limit=20" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "items": [ { "id": "ck...", "status": "RECEIVED", "service": "tg", ... }, ... ],
  "nextCursor": "ck..." | null
}}

คิวรีตัวเลือก: status · limit 1–100 (ค่าเริ่มต้น 20) · cursor = nextCursor ของหน้าก่อนหน้า

1. เติมเงินผ่าน UI เว็บ → GET /v1/account เพื่อยืนยันยอดเงิน
2. เลือก service: GET /v1/services และ GET /v1/prices?service=tg
3. สร้าง order: POST /v1/orders พร้อม service + country
4. อ่าน data.phone แล้วทริกเกอร์ SMS upstream จาก client ของคุณ (เช่น วางในการลงทะเบียน Telegram)
5. Polling GET /v1/orders/:id ทุก 3–5 วินาที เมื่อ status === "RECEIVED" ให้อ่าน smsBody
6. หาก SMS ผิดหรือต้องการรหัสที่สอง: POST /v1/orders/:id/next-sms → กลับไปที่ WAITING
7. เสร็จสิ้น หากคุณยกเลิกก่อนที่ SMS ใด ๆ จะมาถึง: POST /v1/orders/:id/cancel เพื่อคืนเงินเต็มจำนวน