---
title: REST API
description: 呼叫 NexCMP 安裝的客戶 API：驗證、互動式參考、OpenAPI 與 Postman 下載、錯誤、速率限制、等冪性及 curl 範例。
url: https://nexcmp.com/zh-tw/docs/developers/api/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# REST API

> **在哪裡找到：** 於 `https://<your-domain>/apidoc` (公開) 的 API 參考與 `/api-keys` 的 API 金鑰。**在管理後台哪裡：** Customers › API keys (`/customers/apikeys`) 列出客戶建立的金鑰。

## 功能 {#what-it-does}

客戶能在 portal 中執行的每一個動作——列出並控制虛擬機器、讀取發票、管理 SSH Keys、Kubernetes、儲存空間、支援工單——都能透過 `https://<your-domain>/v1/` 下方的版本化 REST API 來使用。客戶透過具備範圍限制的 **API key** 從腳本和 CI 進行呼叫。相同的 API 也為 [`cmp` command-line tool](https://nexcmp.com/zh-tw/docs/developers/cmp-cli/) 與 [MCP server](https://nexcmp.com/zh-tw/docs/developers/mcp/) 提供資料，且參考文件是從執行中的安裝產生，因此它總是精確列出你已開啟的功能。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 公開 HTTPS 地址 | API 提供於你的主要網域 (以及每個經銷商自己的網域)。 |
| API 金鑰 | 由客戶在 portal 中建立；請參閱 [API keys](https://nexcmp.com/zh-tw/docs/developers/api-keys/)。 |
| 相依項目 | 無。你未啟用的模組 (例如 Kubernetes 或 Object Storage) 之端點將會從參考文件中隱藏並遭到拒絕。 |

## 準備基礎設施 {#prepare-the-infrastructure}

無需安裝。若 NexCMP 前方有反向代理伺服器，請將 `/v1/`、`/mcp`、`/cli/` 與 `/apidoc` 轉發至面板 (安裝程式的 nginx 設定已完成此操作)。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

### 互動式參考 {#the-interactive-reference}

開啟 `https://cloud.example.com/apidoc` (將主機替換為你的網域；經銷商的客戶會在經銷商的網域上看到參考文件，並帶有經銷商的名稱)。它具備端點文件，包含 curl、`cmp` CLI、JavaScript、Python 與 Go 的要求和回應範例、搜尋框 (Ctrl 或 Cmd + K)，以及 **Try it** 面板。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 集合。 |
| `/v1/public/insomnia.json` | Insomnia 匯出。 |
| `/v1/public/api.md` | 單一 Markdown 檔案格式的參考文件。 |
| `/v1/public/api-catalog` | 輕量 JSON：品牌、基礎 URL、金鑰前綴、每個範圍與每個端點及其方法、路徑、範圍以及是否需要 `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`。參考頁面也提供適用於 JavaScript 與 Python 的單一檔案 API 用戶端。

### 驗證 {#authentication}

在 `Authorization` 標頭中傳送金鑰：

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

- 客戶金鑰開頭為 `vk_`。金鑰是**繫結至網站的**：在 `cloud.example.com` 建立的金鑰無法在經銷商網域上運作。
- 瀏覽器工作階段權杖（`pt_...`）僅適用於入口網站；自動化作業請使用金鑰。
- 金鑰的**範圍**決定了它能呼叫的內容；缺少範圍會回應 HTTP 403 `scope_required`。請參閱 [API keys](https://nexcmp.com/zh-tw/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}

每個錯誤都是帶有穩定 `code` 與人類可讀 `message` 的 JSON：

```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 金鑰已關閉。 |
| 403 | `scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden` | 金鑰缺少範圍；端點不對金鑰開放；帳戶遭到鎖定；已達到 [quota](https://nexcmp.com/zh-tw/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-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"` 會列出帳戶的虛擬機器。在入口網站中，金鑰的 **Last used** 欄位與 **Key usage log** 會顯示呼叫記錄。

## 限制與注意事項 {#limits-notes}

- **永不對金鑰開放：**加值、提領、變更卡片或自動加值、變更密碼、電子郵件或雙重認證（2FA）、刪除帳戶、建立、編輯或撤銷其他金鑰。這些操作需要已登入的瀏覽器工作階段。
- **隱藏模組：** 參考資料與 OpenAPI 文件僅列出該網站上啟用的功能。
- **回應大小與分頁：** 清單端點具備分頁功能（`page`、`per_page`）；請參閱各端點的 OpenAPI 文件。
- **時間與金額：** 金額以美金分（USD cents）計，除非欄位名稱另有說明。
- **管理員 API：** 管理主控台有自己的 **System › Admin › API** 頁面以及用於管理的管理者金鑰（`ofw_...`）；它們與此處描述的客戶端 API 是分開的。
- **版本控制：** 路徑前綴 `/v1` 是穩定的；回應中可能會新增欄位。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 新金鑰回傳 401 | 金鑰來自其他網域、已過期，或輸入時帶有空格 | 請在您呼叫的網域上建立金鑰；檢查 `Authorization: Bearer vk_...` 標頭。 |
| 403 `scope_required` | 缺少範圍 | 在portal中編輯金鑰並新增範圍。 |
| 401 `key_ip_denied` 或 `site_mismatch` | 金鑰受限於其他 IP（「允許的 IP」）或在其他網域上建立 | 將您伺服器的 IP 新增至金鑰的允許 IP，或呼叫建立該金鑰的網域。 |
| 現有虛擬機器回傳 404 | 該虛擬機器屬於其他帳戶 | 使用擁有者的金鑰。 |
| 400/422 要求 `Idempotency-Key` | 未帶標頭的付費操作 | 新增 `Idempotency-Key: <uuid>`。 |
| 429 | 超出限制 | 請稍候再試；使用 `Retry-After`。 |
| `/apidoc` 顯示的內容少於預期 | 模組已關閉 | 在 License & updates 中啟用此模組。 |