FoxPhone Public API dapat menampilkan cloud phone dan proxy di akun saat ini, serta mengirim tugas reset perangkat dan pengikatan proxy secara massal. Versi saat ini menyediakan empat endpoint berikut.
1. Siapkan API Key
Klik avatar di pojok kanan atas, pilih Settings, lalu buka halaman API Key di profil akun Anda.
Buat Key di halaman API Key. Setiap akun hanya boleh memiliki satu Key aktif:
- Membuat ulang Key langsung membatalkan Key sebelumnya.
- Setelah Key dinonaktifkan, semua permintaan Public API langsung ditolak.
- Key lengkap hanya ditampilkan sekali saat dibuat. Simpan di sistem pengelolaan rahasia yang terkontrol.
Kirim Key melalui header permintaan:
X-API-Key: <your_api_key>Catatan keamanan: Jangan letakkan API Key di URL, body permintaan, kode sumber, log, atau tiket dukungan. ID sumber daya dan Key dalam panduan ini hanyalah contoh.
2. Aturan umum
- URL dasar production:
https://api.foxphone.com/public_api/v1 - Keempat endpoint berbagi batas 60 permintaan per menit untuk setiap API Key.
- Untuk parameter daftar,
page_nummemiliki nilai default1;page_sizememiliki nilai default20, memiliki nilai maksimum100;searchbersifat opsional. - Permintaan massal menerima 1 hingga 100
pod_ids; server akan menghapus duplikat secara otomatis. - Anda hanya dapat mengakses sumber daya milik akun pemegang API Key. Akun lain tidak dapat dipilih melalui parameter.
- Jika pemeriksaan awal menemukan sumber daya tidak valid atau operasi yang bertentangan, tidak ada permintaan dalam batch yang dikirim.
- Jika sebagian operasi gagal setelah pengiriman ke sistem jarak jauh dimulai, operasi yang sudah diterima tidak dibatalkan. Respons memisahkan item yang berhasil dan gagal.
3. Melihat daftar cloud phone
Gunakan endpoint ini untuk melihat daftar cloud phone pada akun saat ini dengan pagination:
GET /public_api/v1/phones?page_num=1&page_size=20&search=pod-exampleGunakan search untuk mencari cloud phone berdasarkan nama atau pod_id.
Contoh permintaan:
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"Contoh respons:
{
"total": 1,
"phones": [
{
"pod_id": "pod-example-001",
"name": "automation-phone",
"online_status": 1,
"operating_status": 0,
"proxy_id": "42"
}
]
}proxy_id adalah 0 jika phone tersebut belum terikat ke proxy.
4. Melihat daftar proxy
Gunakan endpoint ini untuk melihat proxy yang ada di akun saat ini dengan pagination:
GET /public_api/v1/proxies?page_num=1&page_size=20&search=42Gunakan search untuk mencari proxy berdasarkan nama atau proxy_id. Endpoint tidak mengembalikan nama pengguna atau kata sandi proxy.
Contoh permintaan:
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"Contoh respons:
{
"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. Mengirim reset perangkat massal
Gunakan endpoint berikut untuk mengirim tugas reset beberapa perangkat:
POST /public_api/v1/phones/actions/reset
Content-Type: application/jsonBody permintaan:
{
"pod_ids": ["pod-example-001", "pod-example-002"]
}Batasan saat ini: Endpoint reset tidak mendukung penentuan proxy_id atau parameter proxy lain di body permintaan. Untuk mengganti proxy, tunggu hingga reset selesai, lalu panggil endpoint pengikatan proxy yang sudah ada secara massal.
Contoh permintaan:
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"Jika cloud phone sudah memiliki tugas reset yang berjalan, permintaan baru mengembalikan RESET_IN_PROGRESS saat pemeriksaan awal dan tidak mengirim tugas duplikat.
6. Mengikat proxy yang sudah ada secara massal
Ambil proxy_id melalui endpoint daftar proxy, lalu panggil endpoint berikut:
POST /public_api/v1/proxies/{proxy_id}/bind
Content-Type: application/jsonBody permintaan:
{
"pod_ids": ["pod-example-001", "pod-example-002"]
}Contoh permintaan:
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 dan semua cloud phone harus dimiliki akun saat ini. Phone yang dimatikan tetap dapat diikat ke proxy. Phone yang sedang di-reset, dinyalakan/dimatikan, dimulai ulang, atau menjalankan operasi proxy lain akan ditolak saat pemeriksaan awal.
7. Respons massal
Reset perangkat dan pengikatan proxy menggunakan struktur respons yang sama:
{
"successful_pod_ids": ["pod-example-001"],
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PROVIDER_REJECTED",
"message": "provider rejected the operation"
}
]
}Pemeriksaan awal yang gagal mengembalikan HTTP 409 dan kode error BATCH_PRECHECK_FAILED. Dalam metadata error, failed_items mencantumkan pod_id, code dan message; tidak ada permintaan dalam batch yang dikirim.
Kegagalan setelah sistem jarak jauh mulai menerima tugas dilaporkan melalui successful_pod_ids dan failed_items dalam respons operasi.
8. Error umum
| Status HTTP | Kode error | Keterangan |
|---|---|---|
| 400 | INVALID_ARGUMENT | Format parameter, jumlah item, atau nilai pagination tidak valid |
| 401 | INVALID_API_KEY | API Key tidak ada, formatnya salah, atau sudah tidak valid |
| 403 | API_KEY_DISABLED | API Key dinonaktifkan |
| 403 | USER_ACCOUNT_UNAVAILABLE | Akun pemilik API Key tidak tersedia |
| 409 | BATCH_PRECHECK_FAILED | Pemeriksaan awal batch gagal; tidak ada item yang dikirim |
| 429 | RATE_LIMIT_EXCEEDED | Batas permintaan per menit terlampaui |
Untuk HTTP 429, coba lagi nanti dengan strategi backoff. Untuk HTTP 409, gunakan failed_items untuk memperbaiki status sumber daya; jangan langsung mengirim ulang permintaan yang sama.
