合作夥伴 API

面向合作夥伴的伺服器間 API：簽發金鑰，讀取店面設定與地點，建立客戶，發放方案，以及透過您自己的網站或 Telegram 機器人管理訂閱連結。

合作夥伴 API 讓您可以在 CreateYourVPN 上建立自己的網站、自己的控制台或 Telegram 機器人。

API 涵蓋客戶、訂閱、方案與店面設定。伺服器、節點、面板與 SSH 憑證等基礎設施不在公開契約的範圍內。

僅限伺服器之間呼叫。 請把 API 金鑰存放在您的伺服器上，不要放進前端程式碼。帶有瀏覽器標頭的請求會被拒絕，並回傳 403 browser_forbidden。

取得金鑰

在控制台中開啟帳號選單 → "API"，切換到"金鑰"分頁。

為金鑰命名（Telegram 機器人、著陸頁），並只選擇它需要的權限。

點擊"簽發金鑰"並複製完整的值。服務只儲存金鑰的雜湊值，因此 secret 只會顯示一次。

每個合作夥伴最多可以有 5 把有效金鑰。要輪替金鑰，請先簽發新金鑰、更新整合，再撤銷舊金鑰。

以 bearer 權杖的形式傳送金鑰：

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

如果用戶端的 Authorization 已被代理伺服器佔用，也可以使用 X-API-Key: cyv_live_…。

金鑰的格式為 cyv_live_<key_id>_<secret>。前半部（key_id）是公開的：它會顯示在控制台中，可以放心告訴客服。後半部是 secret。

只讀取店面資料的整合，有 config:read 就足夠了。只有在整合需要相應的客戶操作時，才加上 users:read 或 users:write。

完整、可直接執行的契約位於公開 Postman 集合中。其中包含所有端點、權限、參數、請求本文、回應範例與穩定的錯誤代碼。這個集合由後端契約產生，是請求與回應結構的最新依據。

瀏覽所有端點，並將集合複製到您的工作區。

限額按每把金鑰分別計算，與請求的 IP 位址無關。

GET /users 之所以有單獨的限額，是因為每次請求都會載入完整的客戶清單。日常查詢請使用 GET /users/{id} 或依 externalId 搜尋。

建議的存取方式。 保存建立客戶時回傳的 CreateYourVPN 客戶 ID，之後以 GET /users/{id} 查詢。您可以透過 externalId 把它與自己的識別碼關聯起來。

有三種操作需要 Idempotency-Key 標頭：發放方案、重設訂閱連結與刪除客戶。

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

在 24 小時內以同一個鍵重複請求，會回傳已儲存的回應，而不會再次執行操作。如此一來，整合在逾時後重試時就不會產生重複的變更。

為每個業務事件（例如一筆付款或一次操作）建立一個鍵，並在該事件的所有重試中重複使用它。

如果第一次嘗試仍在執行，或其結果暫時未知，API 會回傳 409 conflict，而不會再次執行操作。在決定是否重試之前，請先檢查客戶目前的狀態。

請求與回應的結構請以上方的公開 Postman 集合為準。