公共 API 使用指南

FoxPhone 公共 API 可用於查詢目前帳號下的雲手機和代理，並批次執行一鍵新機、綁定現有代理。目前版本提供以下四個介面。

一、準備 API Key

點選頁面右上角的頭像，從選單選擇 Settings，接著在個人中心開啟 API Key 頁面。

在 API Key 頁面產生 Key。每個帳號只能有一個有效 Key：

• 重新產生 Key 後，舊 Key 會立即失效。
• 停用 Key 後，所有公共 API 請求都會立即遭到拒絕。
• 完整 Key 只會在產生時顯示一次，請將它儲存在受控的密鑰管理系統中。

呼叫公共 API 時，請透過請求標頭傳遞 Key：

X-API-Key: <your_api_key>

安全提示：請勿將 API Key 放入 URL、請求本文、原始碼、日誌或支援單。本指南中的資源 ID 和 Key 均為佔位符。

二、一般規則

• 正式環境基礎路徑：https://api.foxphone.com/public_api/v1
• 四個介面共用每個 API Key 每分鐘 60 次的呼叫限制。
• 列表參數 page_num 的預設值為 1；page_size 的預設值為 20， 的最大值為 100；search 為選用參數。
• 批次寫入支援 1 至 100 個 pod_ids，伺服器會自動去除重複值。
• 僅能存取 API Key 所屬帳號的資源，無法透過參數指定其他帳號。
• 批次預檢若發現任何資源無效或正在執行衝突操作，整批請求都不會提交。
• 遠端任務開始提交後若有部分失敗，已受理的任務不會回復；回應會分別列出成功和失敗項目。

三、查詢雲手機

使用以下介面分頁查詢目前帳號下的雲手機：

GET /public_api/v1/phones?page_num=1&page_size=20&search=pod-example

search 可依雲手機名稱或 pod_id 查詢。

請求範例：

curl --fail-with-body 
  -H "X-API-Key: $API_KEY" 
  "https://api.foxphone.com/public_api/v1/phones?page_num=1&page_size=20&search=pod-example"

回應範例：

{
  "total": 1,
  "phones": [
    {
      "pod_id": "pod-example-001",
      "name": "automation-phone",
      "online_status": 1,
      "operating_status": 0,
      "proxy_id": "42"
    }
  ]
}

proxy_id 為 0 時，表示該雲手機目前未綁定代理。

四、查詢代理

使用以下介面分頁查詢目前帳號下的代理：

GET /public_api/v1/proxies?page_num=1&page_size=20&search=42

search 可依代理名稱或 proxy_id 查詢。介面不會回傳代理使用者名稱或密碼。

請求範例：

curl --fail-with-body 
  -H "X-API-Key: $API_KEY" 
  "https://api.foxphone.com/public_api/v1/proxies?page_num=1&page_size=20&search=42"

回應範例：

{
  "total": 1,
  "proxies": [
    {
      "proxy_id": "42",
      "name": "us-residential",
      "proxy_type": "http",
      "proxy_ip": "203.0.113.42",
      "proxy_port": "10000",
      "check_status": "available"
    }
  ]
}

五、批次一鍵新機

呼叫以下介面批次提交一鍵新機任務：

POST /public_api/v1/phones/actions/reset
Content-Type: application/json

請求本文：

{
  "pod_ids": ["pod-example-001", "pod-example-002"]
}

目前限制：一鍵新機介面不支援在請求本文中指定 proxy_id 或其他代理參數。如需更換代理，請等待一鍵新機完成後，再呼叫「批次綁定現有代理」介面。

請求範例：

curl --fail-with-body 
  -X POST 
  -H "Content-Type: application/json" 
  -H "X-API-Key: $API_KEY" 
  --data '{"pod_ids":["pod-example-001","pod-example-002"]}' 
  "https://api.foxphone.com/public_api/v1/phones/actions/reset"

同一台雲手機已有一鍵新機任務時，新請求會在預檢階段回傳 RESET_IN_PROGRESS，不會重複提交任務。

六、批次綁定現有代理

先透過代理列表介面取得 proxy_id，再呼叫以下介面：

POST /public_api/v1/proxies/{proxy_id}/bind
Content-Type: application/json

請求本文：

{
  "pod_ids": ["pod-example-001", "pod-example-002"]
}

請求範例：

curl --fail-with-body 
  -X POST 
  -H "Content-Type: application/json" 
  -H "X-API-Key: $API_KEY" 
  --data '{"pod_ids":["pod-example-001","pod-example-002"]}' 
  "https://api.foxphone.com/public_api/v1/proxies/42/bind"

代理和所有雲手機都必須屬於目前帳號。關機中的雲手機也能綁定代理；正在一鍵新機、開關機、重新啟動或執行其他代理操作的雲手機會在預檢階段遭到拒絕。

七、批次回應

一鍵新機和代理綁定使用相同的回應結構：

{
  "successful_pod_ids": ["pod-example-001"],
  "failed_items": [
    {
      "pod_id": "pod-example-002",
      "code": "PROVIDER_REJECTED",
      "message": "provider rejected the operation"
    }
  ]
}

預檢失敗會回傳 HTTP 409 和錯誤碼 BATCH_PRECHECK_FAILED。錯誤中繼資料中的 failed_items 會列出具體的 pod_id、code 和 message，此時整批請求都不會提交。

遠端開始受理後發生的失敗，則會透過業務回應中的 successful_pod_ids 和 failed_items 表示實際結果。

八、常見錯誤

收到 HTTP 429 時，請使用退避策略稍後重試。收到 HTTP 409 時，請先根據 failed_items 修復資源狀態，請勿立即重複提交相同請求。