開發者 API

用 API 批量開通與管理代理線路

透過 REST API 查詢可購資源、批量下單、支付與查詢訂單,接入你自己的業務系統。

本文目錄
  1. 01請求頭與基地址
  2. 02查詢可購地區與帶寬
  3. 03批量下單
  4. 04訂單支付
  5. 05查詢訂單與已購 IP

API 與控制台共用同一套資源與庫存;透過 API 下單付款後,控制台「已購買 IP」可立即看到線路。

01請求頭與基地址

所有商家介面固定使用兩個請求頭:x-merchant-token(商戶訪問令牌)與 x-merchant-code(商戶編碼)。兩者皆為必填,缺少任一個都會被拒絕。

base-url
https://api.ipfast.net/api/ipft

下文所有路徑都接在此基地址之後,例如 GET /client/order/orderList 的完整位址為 https://api.ipfast.net/api/ipft/client/order/orderList。

02查詢可購地區與帶寬

下單前先查可購資源。bandwidth 為必填規格(單位 Mbps,常見 5、10),不傳時同一地區會按不同帶寬返回多筆記錄。

regional-available.sh
curl -X GET "https://api.ipfast.net/api/ipft/client/ip/pool/regionalAvailableIps?type=1&ipCategory=HOST" \
  -H "x-merchant-token: $TOKEN" \
  -H "x-merchant-code: $CODE"

回應中每筆記錄的 price 是該帶寬規格的月單價,ipTotals 是可購數量。下單時傳入的 bandwidth 要與這裡查到的規格一致,否則會因未設定售價或庫存不足而失敗。

03批量下單

countryNums 是一個陣列,每一項代表一個國家/地區的採購需求,因此一次請求就能批量開通多個地區。每一項都必須顯式傳入 bandwidth。

create-order.sh
curl -X POST "https://api.ipfast.net/api/ipft/client/order/addStatic" \
  -H "x-merchant-token: $TOKEN" \
  -H "x-merchant-code: $CODE" \
  -H "Content-Type: application/json" \
  -d '{
    "countryNums": [
      {"countryCode":"US","location":"New York","num":2,"ipType":1,"ipCategory":"HOST","bandwidth":10},
      {"countryCode":"HK","location":"hongkong","num":5,"ipType":1,"ipCategory":"HOST","bandwidth":5}
    ],
    "monthCount": 1
  }'

欄位含義:countryCode 國家代碼;location 省/州/區;num 該地區需要的 IP 數量;ipType 0 廣播、1 原生;ipCategory HOST 住宅、IDC 機房;monthCount 購買月數。成功時返回訂單號:

response
{"msg":"操作成功","code":200,"data":"N2025032701271232584"}

04訂單支付

下單後須另行付款,訂單才會生效。目前僅支援餘額支付,路徑參數 orderId 即上一步返回的訂單號。

pay-order.sh
curl -X POST "https://api.ipfast.net/api/ipft/client/payment/order/pay/N2025032701271232584" \
  -H "x-merchant-token: $TOKEN" \
  -H "x-merchant-code: $CODE" \
  -H "Content-Type: application/json" \
  -d '{"payment":"BALANCE"}'

回應的 data.status 為 1 表示支付成功、0 表示失敗。常見錯誤:500 訂單已失效、500 商戶錢包帳戶不存在、500 餘額不足。

05查詢訂單與已購 IP

訂單列表回傳訂單狀態與 orderItems 明細。status:0 未生效、10 已生效、20 已過期;paidStatus:0 已取消、10 未支付、20 已支付。

query.sh
curl -X GET "https://api.ipfast.net/api/ipft/client/order/orderList?productType=2" \
  -H "x-merchant-token: $TOKEN" \
  -H "x-merchant-code: $CODE"

# 已購 IP 列表,可按訂單號、狀態、IP 篩選
curl -X GET "https://api.ipfast.net/api/ipft/client/ip/pool/item/merchantIpList?orderNo=N2025032701271232584&status=1&pageNum=1&pageSize=50" \
  -H "x-merchant-token: $TOKEN" \
  -H "x-merchant-code: $CODE"

merchantIpList 的 status:1 已生效、2 已過期、3 已退訂;返回欄位包含 ip、account、password、port、countryCode、location、bandwidth、effectiveDatetime、expireDatetime,分頁用 pageNum 與 pageSize。

提示一次請求可批量開通多個地區,但庫存與帶寬是按地區分別校驗的:只要有一行規格不足,整張訂單就會被拒絕。建議先用 regionalAvailableIps 核對 ipTotals 再提交。

FAQ常見問題

購買後多久可以使用?

付款後約 1–3 分鐘生成線路,在控制台「已購買 IP」中查看。

支援哪些協議?推薦用哪個?

同時支援 HTTP 與 SOCKS5。指紋瀏覽器與客戶端場景推薦 SOCKS5,兼容性更好。

代理為什麼連接不上?

先確認本機已有境外網絡環境,再核對協議與端口是否對應,最後檢查賬號密碼是否多了空格。

支援退款和開發票嗎?

支援,條件與流程見「發票、退款與支付方式說明」。

可以一鍵續費所有線路嗎?

可以。在控制台勾選線路後批量續費,也支援開啟到期提醒。

這篇文章對你有幫助嗎?
I

IPFAST 技術團隊

專注住宅代理基礎設施與指紋瀏覽器整合,內容均經過實測,並隨產品更新維護。

更多教程

相關文章

幫助中心
Newsletter

訂閱 IPFAST 更新

新教程、產品更新與行業洞察,每月一封,隨時退訂。

提交即表示同意 隱私政策。
註冊領取試用 查看價格