REST API

ตำแหน่งในพอร์ทัล: API reference ที่ https://<your-domain>/apidoc (สาธารณะ) และ API keys ที่ /api-keys ตำแหน่งในแอดมิน: Customers › API keys (/customers/apikeys) แสดงรายการคีย์ที่ลูกค้าสร้างขึ้น

What it does

ทุกการกระทำที่ลูกค้าสามารถทำได้ในพอร์ทัล ไม่ว่าจะเป็นการแสดงรายการและควบคุม VM อ่านใบแจ้งหนี้ จัดการ SSH Keys, Kubernetes, พื้นที่เก็บข้อมูล หรือตั๋วสนับสนุน ล้วนสามารถทำได้ผ่าน REST API ที่มีระบบจัดเก็บเวอร์ชันภายใต้ https://<your-domain>/v1/ ลูกค้าเรียกใช้งานผ่านสคริปต์และ CI ด้วย API key ที่กำหนดขอบเขตสิทธิ์ไว้ API ตัวเดียวกันนี้ยังขับเคลื่อน cmp command-line tool และ MCP server อีกทั้งคู่มืออ้างอิงยังถูกสร้างขึ้นจากระบบที่กำลังทำงานอยู่จริง จึงแสดงเฉพาะฟีเจอร์ที่คุณเปิดใช้งานไว้เท่านั้น

ข้อกำหนด

Item	Requirement
Public HTTPS address	API ให้บริการอยู่บนโดเมนหลักของคุณ (และบนโดเมนของรีเซลเลอร์แต่ละราย)
API key	สร้างโดยลูกค้าในพอร์ทัล ดูที่ API keys
Dependencies	ไม่มี Endpoint ของโมดูลที่คุณไม่ได้เปิดใช้งาน (เช่น Kubernetes หรือ Object Storage) จะถูกซ่อนจากคู่มืออ้างอิงและปฏิเสธการเข้าถึง

เตรียมโครงสร้างพื้นฐาน

ไม่ต้องติดตั้งอะไร หากมี Reverse Proxy อยู่หน้า NexCMP ให้ส่งต่อ /v1/, /mcp, /cli/ และ /apidoc ไปยังแผงควบคุม (การกำหนดค่า Nginx ของตัว설치โปรแกรมจะจัดการให้เรียบร้อยแล้ว)

เชื่อมต่อใน NexCMP

คู่มืออ้างอิงแบบอินเทอร์แอกทีฟ

เปิด https://cloud.example.com/apidoc (แทนที่โฮสต์ด้วยโดเมนของคุณ ลูกค้าของรีเซลเลอร์จะเห็นคู่มืออ้างอิงบนโดเมนของรีเซลเลอร์พร้อมชื่อของรีเซลเลอร์) ประกอบด้วยเอกสาร Endpoint พร้อมตัวอย่างคำขอและคำตอบในรูปแบบ curl, cmp CLI, JavaScript, Python และ Go ช่องค้นหา (Ctrl หรือ Cmd + K) และแผง Try it การทดลองใช้งานจะส่งคำขอไปยังเว็บไซต์เดียวกันเท่านั้น โดยใช้คีย์ที่ผู้เข้าชมวางลงไป (เก็บไว้ในเซสชันเบราว์เซอร์) ค่าเริ่มต้นจะเป็นแบบอ่านอย่างเดียว และการเรียกใช้งานที่มีการเขียนข้อมูลหรือมีค่าใช้จ่ายจะต้องใช้สวิตช์เพิ่มเติมและการยืนยัน

ไฟล์ดาวน์โหลดและเอกสารที่เครื่องอ่านได้

ทั้งหมดเป็นแบบสาธารณะ ไม่ต้องใช้คีย์ และสร้างขึ้นสำหรับแต่ละเว็บไซต์:

URL	เนื้อหา
`/apidoc`	คู่มืออ้างอิงแบบอินเทอร์แอกทีฟ
`/v1/public/openapi.json`	เอกสาร OpenAPI 3.1
`/v1/public/openapi.yaml`	รูปแบบเดียวกัน ในรูปแบบ YAML
`/v1/public/postman.json`	Postman collection
`/v1/public/insomnia.json`	Insomnia export
`/v1/public/api.md`	คู่มืออ้างอิงในรูปแบบไฟล์ Markdown เดี่ยว
`/v1/public/api-catalog`	JSON ขนาดกะทัดรัด: แบรนด์, base URL, คำนำหน้าคีย์, ทุก scope และทุก endpoint พร้อม method, path, scope และระบุว่าจำเป็นต้องใช้ `Idempotency-Key` หรือไม่

bash

curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40
curl -sO https://cloud.example.com/v1/public/openapi.yaml

ใน Postman ให้เลือก Import › Link แล้ววาง https://cloud.example.com/v1/public/postman.json หน้ารายการอ้างอิงยังมี API client แบบไฟล์เดียวสำหรับ JavaScript และ Python อีกด้วย

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

ส่งคีย์ในเฮดเดอร์ Authorization:

bash

curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"

คีย์ของลูกค้าจะขึ้นต้นด้วย vk_ โดยคีย์จะถูก ผูกกับไซต์ (site-bound): คีย์ที่สร้างขึ้นบน cloud.example.com จะไม่สามารถใช้งานบนโดเมนของผู้ค้าต่อได้
โทเค็นเซสชันของเบราว์เซอร์ (pt_...) มีไว้สำหรับพอร์ทัลเท่านั้น โปรดใช้คีย์สำหรับงานอัตโนมัติ
สิทธิ์ scopes ของคีย์จะเป็นตัวกำหนดสิ่งที่คีย์นั้นสามารถเรียกใช้งานได้ โดยหากไม่มีสิทธิ์จะได้รับข้อผิดพลาด HTTP 403 scope_required ดูข้อมูลเพิ่มเติมได้ที่ API keys.
คุณสามารถตรวจสอบคีย์ได้ด้วย GET /v1/apikeys/self ซึ่งจะส่งคืนชื่อสิทธิ์ขอบเขต วันหมดอายุ และโควต้าอัตราการเรียกใช้งานที่เหลือของคีย์นั้น (ทุกคีย์สามารถเรียกใช้งานได้)

ตัวอย่าง

bash

# List virtual machines
curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX"

# Start one (needs vm:write)
curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \
  -H "Authorization: Bearer vk_XXXX"

# Create a VM (paid: needs vm:create and an Idempotency-Key)
curl -s -X POST https://cloud.example.com/v1/vm \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @vm.json

ดูฟิลด์คำขอที่แน่นอนของแต่ละการดำเนินการได้จาก /apidoc.

ข้อผิดพลาด

ข้อผิดพลาดทุกรายการจะอยู่ในรูปแบบ JSON ซึ่งประกอบด้วยรหัส code ที่เสถียรและข้อความอธิบายที่มนุษย์อ่านเข้าใจ message:

json

{"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}}

HTTP	ค่าทั่วไป `code`	ความหมาย
401	`unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled`	คีย์ไม่ถูกต้องหรือไม่มีอยู่ ถูกเพิกถอน หมดอายุ IP ของผู้เรียกอยู่นอกรายการที่อนุญาตของคีย์ คีย์จากไซต์อื่น หรือปิดใช้งาน API keys ไว้
403	`scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden`	คีย์ไม่มีสิทธิ์ที่จำเป็น, ปลายทางไม่เปิดให้คีย์ใช้งาน, บัญชีถูกล็อค, ถึงขีดจำกัด quota แล้ว, หรือไม่อนุญาตให้ดำเนินการในเซสชันที่มีการสวมสิทธิ์
404	`not_found`	ไม่พบข้อมูล — รวมถึงส่งคืนสำหรับทรัพยากรที่เป็นของผู้อื่นด้วย
422	`invalid_argument`	ข้อผิดพลาดในการตรวจสอบความถูกต้อง (ระบุชื่อฟิลด์ไว้ในผลลัพธ์)
429	`rate_limited`	มีการส่งคำขอมากเกินไป กรุณารอจนถึง `Retry-After`.
503	`maintenance`	โหมดบำรุงรักษาเปิดใช้งานอยู่: สามารถอ่านข้อมูลได้ แต่จะปฏิเสธการเขียนข้อมูล

อัตราการจำกัดคำขอ

ขีดจำกัด	ค่าเริ่มต้น
ต่อคีย์	120 คำขอต่อนาที
ต่อบัญชี (รวมคีย์ทั้งหมด)	300 คำขอต่อนาที

การตอบกลับทุกรายการจะมี X-RateLimit-Limit, X-RateLimit-Remaining และ X-RateLimit-Reset ส่วนข้อผิดพลาด 429 จะเพิ่ม Retry-After.

Idempotency

คำสั่งที่ต้องเสียเงินหรือ000ที่ไม่สามารถทำซ้ำได้ (สร้าง, เปลี่ยนแผน, ซื้อ, ลบ ...) จำเป็นต้องมี ส่วนหัว Idempotency-Key (สตริงใดก็ได้ที่มีความยาวไม่เกิน 200 ตัวอักษร โดย UUID เหมาะสมที่สุด) หากส่งคีย์เดิมซ้ำหลังจากหมดเวลา เซิร์ฟเวอร์จะส่งคืนผลลัพธ์ ดั้งเดิม (พร้อมกับ Idempotency-Replayed: 1) แทนที่จะทำซ้ำการดำเนินการนั้น การนำคีย์ไปใช้กับคำสั่งอื่นจะตอบกลับด้วย 422 ส่วนคำขอที่ยังดำเนินการอยู่จะตอบกลับด้วย 409/Retry-After หากไม่มีส่วนหัวดังกล่าว การเรียกใช้งานที่มีค่าใช้จ่ายจะถูกปฏิเสธ

ตรวจสอบ

สร้างคีย์ที่มีสิทธิ์ vm:read ในพอร์ทัล (API keys › Create key).
รันคำสั่ง:
bash
```
curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"
```
คุณจะได้รับ HTTP 200 พร้อมกับส่วนหัวอัตราการจำกัดคำขอ
curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" แสดงรายการ VM ของบัญชี ในพอร์ทัล คอลัมน์ Last used ของคีย์และ Key usage log จะแสดงการเรียกใช้งานทั้งหมด

ขีดจำกัดและหมายเหตุ

ไม่สามารถใช้งานผ่านคีย์ได้: การเติมเงิน, ถอนเงิน, เปลี่ยนบัตรหรือเติมเงินอัตโนมัติ, เปลี่ยนรหัสผ่าน, อีเมลหรือ 2FA, ลบบัญชี, รวมถึงการสร้าง แก้ไข หรือเพิกถอนคีย์อื่นๆ สิ่งเหล่านี้จำเป็นต้องใช้เซสชันเบราว์เซอร์ที่เข้าสู่ระบบแล้ว
โมดูลที่ซ่อนอยู่: คู่มืออ้างอิงและเอกสาร OpenAPI จะแสดงเฉพาะฟีเจอร์ที่เปิดใช้งานบนไซต์นั้นๆ เท่านั้น
ขนาดการตอบกลับและการแบ่งหน้า: ปลายทางรายการจะมีการแบ่งหน้า (page, per_page) โปรดอ่านเอกสาร OpenAPI สำหรับแต่ละปลายทาง
เวลาและเงิน: จำนวนเงินจะแสดงเป็นเซนต์ USD เว้นแต่ชื่อฟิลด์จะระบุไว้เป็นอย่างอื่น
Admin API: คอนโซลผู้ดูแลระบบมีหน้า System › Admin › API ของตัวเองและคีย์ผู้ดูแลระบบ (ofw_...) สำหรับการจัดการ ซึ่งจะแยกต่างหากจาก API ของลูกค้าที่อธิบายไว้ที่นี่
การจัดการเวอร์ชัน: คำนำหน้าเส้นทาง /v1 มีความเสถียร แต่อาจมีการเพิ่มฟิลด์ใหม่ลงในการตอบกลับ

การแก้ Problme

อาการ	สาเหตุ	วิธีแก้ปัญหา
401 บนคีย์ใหม่	คีย์มาจากโดเมนอื่น หมดอายุ หรือพิมพ์เว้นวรรค	สร้างคีย์บนโดเมนที่คุณเรียกใช้งาน และตรวจสอบส่วนหัว `Authorization: Bearer vk_...`
403 `scope_required`	สิทธิ์การใช้งาน (Scope) ไม่ครบถ้วน	แก้ไขคีย์ในพอร์ทัลและเพิ่มสิทธิ์การใช้งาน
401 `key_ip_denied` หรือ `site_mismatch`	คีย์ถูกจำกัดให้ใช้เฉพาะ IP อื่น ("allowed IPs") หรือสร้างบนโดเมนอื่น	เพิ่ม IP ของเซิร์ฟเวอร์คุณไปยัง IP ที่อนุญาตของคีย์ หรือเรียกไปยังโดเมนที่สร้างคีย์นั้นขึ้นมา
404 บน VM ที่มีอยู่จริง	VM นี้เป็นของบัญชีอื่น	ใช้คีย์ของเจ้าของบัญชี
400/422 ขอ `Idempotency-Key`	การดำเนินการที่มีค่าใช้จ่ายโดยไม่มีส่วนหัว	เพิ่ม `Idempotency-Key: <uuid>`
429	เกินขีดจำกัด	หยุดพักการทำงานและใช้ `Retry-After`
`/apidoc` แสดงผลน้อยกว่าที่คาดไว้	โมดูลถูกปิดใช้งาน	เปิดใช้งานโมดูลใน License & updates

REST API ​

What it does ​

ข้อกำหนด ​

เตรียมโครงสร้างพื้นฐาน ​

เชื่อมต่อใน NexCMP ​

คู่มืออ้างอิงแบบอินเทอร์แอกทีฟ ​

ไฟล์ดาวน์โหลดและเอกสารที่เครื่องอ่านได้ ​

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

ตัวอย่าง ​

ข้อผิดพลาด ​

อัตราการจำกัดคำขอ ​

Idempotency ​

ตรวจสอบ ​

ขีดจำกัดและหมายเหตุ ​

การแก้ Problme ​

REST API

What it does

ข้อกำหนด

เตรียมโครงสร้างพื้นฐาน

เชื่อมต่อใน NexCMP

คู่มืออ้างอิงแบบอินเทอร์แอกทีฟ

ไฟล์ดาวน์โหลดและเอกสารที่เครื่องอ่านได้

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

ตัวอย่าง

ข้อผิดพลาด

อัตราการจำกัดคำขอ

Idempotency

ตรวจสอบ

ขีดจำกัดและหมายเหตุ

การแก้ Problme