---
title: REST API
description: เรียกใช้งาน Customer API ของการติดตั้ง NexCMP ของคุณ: การยืนยันตัวตน คู่มืออ้างอิงแบบอินเทอร์แอกทีฟ การดาวน์โหลด OpenAPI และ Postman ข้อผิดพลาด อัตราการเรียกใช้งาน และตัวอย่าง curl
url: https://nexcmp.com/th/docs/developers/api/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# REST API

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

## What it does {#what-it-does}

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

## ข้อกำหนด {#requirements}

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

## เตรียมโครงสร้างพื้นฐาน {#prepare-the-infrastructure}

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

## เชื่อมต่อใน NexCMP {#connect-in-nexcmp}

### คู่มืออ้างอิงแบบอินเทอร์แอกทีฟ {#the-interactive-reference}

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


### ไฟล์ดาวน์โหลดและเอกสารที่เครื่องอ่านได้ {#downloads-and-machine-readable-documents}

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

| 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 อีกด้วย

### การยืนยันตัวตน {#authentication}

ส่งคีย์ในเฮดเดอร์ `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](https://nexcmp.com/th/docs/developers/api-keys/).
- คุณสามารถตรวจสอบคีย์ได้ด้วย `GET /v1/apikeys/self` ซึ่งจะส่งคืนชื่อสิทธิ์ขอบเขต วันหมดอายุ และโควต้าอัตราการเรียกใช้งานที่เหลือของคีย์นั้น (ทุกคีย์สามารถเรียกใช้งานได้)

### ตัวอย่าง {#examples}

```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`.

### ข้อผิดพลาด {#errors}

ข้อผิดพลาดทุกรายการจะอยู่ในรูปแบบ 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](https://nexcmp.com/th/docs/billing/quotas/) แล้ว, หรือไม่อนุญาตให้ดำเนินการในเซสชันที่มีการสวมสิทธิ์ |
| 404 | `not_found` | ไม่พบข้อมูล — รวมถึงส่งคืนสำหรับทรัพยากรที่เป็นของผู้อื่นด้วย |
| 422 | `invalid_argument` | ข้อผิดพลาดในการตรวจสอบความถูกต้อง (ระบุชื่อฟิลด์ไว้ในผลลัพธ์) |
| 429 | `rate_limited` | มีการส่งคำขอมากเกินไป กรุณารอจนถึง `Retry-After`. |
| 503 | `maintenance` | โหมดบำรุงรักษาเปิดใช้งานอยู่: สามารถอ่านข้อมูลได้ แต่จะปฏิเสธการเขียนข้อมูล |

### อัตราการจำกัดคำขอ {#rate-limits}

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

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

### Idempotency {#idempotency}

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

## ตรวจสอบ {#verify}

1. สร้างคีย์ที่มีสิทธิ์ `vm:read` ในพอร์ทัล (**API keys › Create key**).
2. รันคำสั่ง:

   ```bash
   curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"
   ```

   คุณจะได้รับ HTTP 200 พร้อมกับส่วนหัวอัตราการจำกัดคำขอ
3. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` แสดงรายการ VM ของบัญชี ในพอร์ทัล คอลัมน์ **Last used** ของคีย์และ **Key usage log** จะแสดงการเรียกใช้งานทั้งหมด

## ขีดจำกัดและหมายเหตุ {#limits-notes}

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

## การแก้ Problme {#troubleshooting}

| อาการ | สาเหตุ | วิธีแก้ปัญหา |
|---|---|---|
| 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 |