API 與控制台共用同一套資源與庫存;透過 API 下單付款後,控制台「已購買 IP」可立即看到線路。
01請求頭與基地址
所有商家介面固定使用兩個請求頭:x-merchant-token(商戶訪問令牌)與 x-merchant-code(商戶編碼)。兩者皆為必填,缺少任一個都會被拒絕。
https://api.ipfast.net/api/ipft
下文所有路徑都接在此基地址之後,例如 GET /client/order/orderList 的完整位址為 https://api.ipfast.net/api/ipft/client/order/orderList。
02查詢可購地區與帶寬
下單前先查可購資源。bandwidth 為必填規格(單位 Mbps,常見 5、10),不傳時同一地區會按不同帶寬返回多筆記錄。
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。
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 購買月數。成功時返回訂單號:
{"msg":"操作成功","code":200,"data":"N2025032701271232584"}
04訂單支付
下單後須另行付款,訂單才會生效。目前僅支援餘額支付,路徑參數 orderId 即上一步返回的訂單號。
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 已支付。
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 再提交。