FoxPhone Public API से आप मौजूदा खाते के क्लाउड फ़ोन और प्रॉक्सी की सूची देख सकते हैं तथा डिवाइस रीसेट और प्रॉक्सी बाइंड करने के कार्य बैच में भेज सकते हैं। मौजूदा संस्करण में ये चार endpoint उपलब्ध हैं।
1. API Key तैयार करें
ऊपर दाईं ओर प्रोफ़ाइल चित्र पर क्लिक करें, Settings चुनें और फिर खाते की प्रोफ़ाइल में API Key पेज खोलें।
API Key पेज पर Key बनाएँ। हर खाते के लिए केवल एक सक्रिय Key की अनुमति है:
- नई Key बनाने पर पुरानी Key तुरंत अमान्य हो जाती है।
- Key बंद करने के बाद सभी Public API अनुरोध तुरंत अस्वीकार हो जाते हैं।
- पूरी Key केवल बनाते समय एक बार दिखाई जाती है। इसे नियंत्रित सीक्रेट मैनेजर में सुरक्षित रखें।
अनुरोध header में Key भेजें:
X-API-Key: <your_api_key>सुरक्षा सूचना: API Key को URL, अनुरोध body, source code, logs या support ticket में न रखें। इस गाइड में दिए गए resource ID और Key केवल उदाहरण हैं।
2. सामान्य नियम
- Production base URL:
https://api.foxphone.com/public_api/v1 - चारों endpoint के लिए प्रति API Key प्रति मिनट 60 अनुरोधों की साझा सीमा है।
- सूची पैरामीटर में,
page_numका default मान1;page_sizeका default मान20, की अधिकतम सीमा100;searchवैकल्पिक है। - एक batch में 1 से 100
pod_idsस्वीकार किए जाते हैं; server duplicate मान अपने आप हटाता है। - आप केवल API Key के स्वामी खाते के संसाधनों तक पहुँच सकते हैं। पैरामीटर से कोई दूसरा खाता नहीं चुना जा सकता।
- यदि preflight में कोई resource अमान्य हो या उस पर विरोधी operation चल रहा हो, तो पूरा batch submit नहीं होगा।
- Remote submission शुरू होने के बाद कुछ कार्य विफल हों, तो स्वीकार किए गए कार्य वापस नहीं लिए जाते; response में सफल और विफल items अलग-अलग दिखते हैं।
3. क्लाउड फ़ोन सूची देखें
मौजूदा खाते के क्लाउड फ़ोन की paginated सूची के लिए इस endpoint का उपयोग करें:
GET /public_api/v1/phones?page_num=1&page_size=20&search=pod-exampleक्लाउड फ़ोन को नाम या pod_id से खोजने के लिए search का उपयोग करें।
अनुरोध का उदाहरण:
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"response का उदाहरण:
{
"total": 1,
"phones": [
{
"pod_id": "pod-example-001",
"name": "automation-phone",
"online_status": 1,
"operating_status": 0,
"proxy_id": "42"
}
]
}proxy_id का मान 0 होने पर क्लाउड फ़ोन से कोई proxy जुड़ा नहीं है।
4. प्रॉक्सी सूची देखें
मौजूदा खाते के प्रॉक्सी की paginated सूची के लिए इस endpoint का उपयोग करें:
GET /public_api/v1/proxies?page_num=1&page_size=20&search=42प्रॉक्सी को नाम या proxy_id से खोजने के लिए search का उपयोग करें। Endpoint प्रॉक्सी username या password नहीं लौटाता।
अनुरोध का उदाहरण:
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"response का उदाहरण:
{
"total": 1,
"proxies": [
{
"proxy_id": "42",
"name": "us-residential",
"proxy_type": "http",
"proxy_ip": "203.0.113.42",
"proxy_port": "10000",
"check_status": "available"
}
]
}5. डिवाइस रीसेट बैच में भेजें
कई डिवाइस के reset कार्य भेजने के लिए इस endpoint का उपयोग करें:
POST /public_api/v1/phones/actions/reset
Content-Type: application/jsonअनुरोध body:
{
"pod_ids": ["pod-example-001", "pod-example-002"]
}मौजूदा सीमा: Reset endpoint अनुरोध body में proxy_id या अन्य proxy पैरामीटर निर्दिष्ट करने का समर्थन नहीं करता। Proxy बदलने के लिए reset पूरा होने की प्रतीक्षा करें, फिर bulk bind-existing-proxy endpoint कॉल करें।
अनुरोध का उदाहरण:
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 पहले से चल रहा है, तो नया अनुरोध preflight में RESET_IN_PROGRESS लौटाता है और duplicate task submit नहीं करता।
6. मौजूदा प्रॉक्सी बैच में बाँधें
पहले proxy list endpoint से proxy_id प्राप्त करें, फिर यह endpoint कॉल करें:
POST /public_api/v1/proxies/{proxy_id}/bind
Content-Type: application/jsonअनुरोध body:
{
"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"Proxy और सभी क्लाउड फ़ोन मौजूदा खाते के होने चाहिए। बंद फ़ोन पर भी proxy बाँधा जा सकता है। Reset, power, reboot या दूसरी proxy operation में लगे फ़ोन preflight में अस्वीकार होंगे।
7. Batch response
डिवाइस reset और proxy binding का response structure समान है:
{
"successful_pod_ids": ["pod-example-001"],
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PROVIDER_REJECTED",
"message": "provider rejected the operation"
}
]
}Preflight विफल होने पर HTTP 409 और error code BATCH_PRECHECK_FAILED लौटता है। Error metadata में failed_items संबंधित pod_id, code तथा message सूचीबद्ध होते हैं; इस स्थिति में batch submit नहीं होगा।
Remote system द्वारा कार्य स्वीकार करना शुरू करने के बाद की विफलताएँ business response में successful_pod_ids तथा failed_items के माध्यम से दिखाई जाती हैं।
8. सामान्य त्रुटियाँ
| HTTP status | त्रुटि कोड | विवरण |
|---|---|---|
| 400 | INVALID_ARGUMENT | पैरामीटर फ़ॉर्मैट, item count या pagination मान अमान्य है |
| 401 | INVALID_API_KEY | API Key अनुपस्थित, गलत फ़ॉर्मैट में या अमान्य है |
| 403 | API_KEY_DISABLED | API Key बंद है |
| 403 | USER_ACCOUNT_UNAVAILABLE | API Key का स्वामी खाता उपलब्ध नहीं है |
| 409 | BATCH_PRECHECK_FAILED | Batch preflight विफल; कोई item submit नहीं हुआ |
| 429 | RATE_LIMIT_EXCEEDED | प्रति मिनट अनुरोध सीमा पार हो गई |
HTTP 429 मिलने पर backoff के साथ बाद में फिर प्रयास करें। HTTP 409 मिलने पर पहले failed_items के आधार पर resource स्थिति ठीक करें; वही अनुरोध तुरंत दोबारा submit न करें।
