help-icon
icon

Panduan Public API

helpDetails-time-icon2026-09-23T15:37:56+08:00

Gunakan API Key pribadi untuk daftar ponsel, proxy, aplikasi, serta reset, pengikatan proxy dan instalasi. Enam endpoint pelanggan memakai https://api.foxphone.com dan /public_api/v1.

Endpoint

HTTP/public_api/v1Keterangan
GET/phonesDaftar ponsel
GET/proxiesDaftar proxy
POST/phones/actions/resetReset massal
POST/proxies/{proxy_id}/bindIkat proxy tersedia
GET/appsAplikasi dan versi
POST/phones/actions/install-appInstalasi massal

Siapkan API Key

Buka Settings dari avatar lalu API Key di pusat pribadi. Satu akun memiliki satu Key aktif. Pembuatan ulang langsung membatalkan Key lama; nilai lengkap muncul sekali. Kirim X-API-Key dan Content-Type: application/json untuk POST. JWT web, Cookie, Device-ID, hash dan platform tidak diperlukan; Bearer tidak menggantikan header ini.

X-API-Key: <your_api_key>

Simpan Key hanya di variabel lingkungan server atau pengelola rahasia, bukan frontend, repositori publik atau klien. Jangan di URL, body, log atau tiket. Contoh memakai API_KEY. Jika bocor, rotasi/nonaktifkan segera dan perbarui semua pemanggil.

export API_KEY="<your_api_key>"

Konvensi dan respons

Gunakan HTTPS. Sukses HTTP 200 dengan payload di data; kesalahan 4xx/5xx memiliki reason string. Periksa status, reason dan hasil tiap item, bukan message saja. data kesalahan dapat null; simpan request_id. Kredensial mitra /open_api/v1 terpisah.

Satu Key berbagi 60 panggilan/menit. page_num/page_size kosong atau tidak positif menjadi 1/20; page_size di atas 100 menghasilkan 400. Ponsel/proxy memakai search, aplikasi app_name. pod_ids berupa array string 1–100 setelah trim, pembuangan kosong dan duplikat. Cocokkan hasil berdasarkan pod_id.

pod_id selalu string. proxy_id, total, id versi dan version_code adalah angka JSON; gunakan parser tanpa kehilangan presisi untuk bilangan besar, terutama JavaScript. Nilai 0 dan string kosong tetap ada; daftar kosong dapat [] atau null.

{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 0,
    "phones": []
  },
  "message": "success"
}

Daftar ponsel

Daftar ponsel akun saat ini, search menurut nama atau pod_id. data.phones berisi pod_id, name, online_status, operating_status, proxy_id; data.total jumlahnya. proxy_id=0 berarti tanpa asosiasi. Asosiasi lokal tidak memastikan pengikatan cloud selesai.

online_status: 0 mulai, 1 berjalan, 2 mati, 3 mematikan, 4 restart, 5 streaming, 6 siap streaming. operating_status: 0 mulai, 1 berjalan, 2 mati, 3 mematikan, 4 restart, 5 reset; 6 tidak ditentukan. Jangan samakan keduanya.

KolomTipe
pod_idstring
namestring
online_statusinteger
operating_statusinteger
proxy_idnumber
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones?page_num=1&page_size=20&search=example" \
  -H "X-API-Key: ${API_KEY}"
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 1,
    "phones": [
      {
        "pod_id": "pod-example-001",
        "name": "test-phone",
        "online_status": 1,
        "operating_status": 1,
        "proxy_id": 42
      }
    ]
  },
  "message": "success"
}

Daftar proxy

Cari proxy berdasarkan nama/ID. data.proxies berisi proxy_id, name, proxy_type, proxy_ip, proxy_port, check_status. Port adalah string; kredensial dan URL penyegaran tidak dikembalikan. Status unchecked, success, failed; data lama mungkin kosong. Pemeriksaan lama tidak menjamin ketersediaan kini.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/proxies?page_num=1&page_size=20&search=example" \
  -H "X-API-Key: ${API_KEY}"
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 1,
    "proxies": [
      {
        "proxy_id": 42,
        "name": "example-proxy",
        "proxy_type": "socks5",
        "proxy_ip": "203.0.113.42",
        "proxy_port": "1080",
        "check_status": "success"
      }
    ]
  },
  "message": "success"
}

Reset massal

Reset menghapus data: cadangkan dan periksa target. Hanya kirim pod_ids. Ponsel harus berjalan, tersedia dan milik akun; mati, reset atau konflik ditolak. phone_template_mode termasuk 0 dan phone_template_id termasuk kosong mengembalikan 400 / PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED. Model dipilih acak; jika tiada alternatif, tanpa template. Simulasi disimpan dan proxy lama dicoba dipulihkan setelah pemeriksaan; tidak memilih atau membeli proxy baru.

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

Ikat proxy tersedia

proxy_id positif dari daftar pada path, body hanya pod_ids. Proxy dan ponsel harus milik akun, proxy berlaku dan lolos pemeriksaan baru. Ponsel mati menyimpan konfigurasi dan tetap mati sampai startup berikutnya. Ponsel berjalan menerapkan asinkron dan dapat restart. Konflik ditolak; proxy tidak valid: 409 / BATCH_PRECHECK_FAILED dengan PRECHECK_FAILED per item.

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

Hasil batch dan kesalahan

Hanya reset dan pengikatan memakai successful_pod_ids/failed_items. Kegagalan pemeriksaan seluruh batch: 409 dengan data.failed_items, bukan metadata terluar. Sebagian pengiriman bisa diterima dan tidak dapat di-rollback lintas sistem. Daftar sukses hanya diterima/disimpan, bukan selesai; dapat null. Jangan ulang seluruh batch.

{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "successful_pod_ids": [
      "pod-example-001"
    ],
    "failed_items": [
      {
        "pod_id": "pod-example-002",
        "code": "PROVIDER_REJECTED",
        "message": "provider rejected the operation"
      }
    ]
  },
  "message": "success"
}
{
  "request_id": "example-request-id",
  "code": 409,
  "data": {
    "failed_items": [
      {
        "pod_id": "pod-example-002",
        "code": "PHONE_NOT_RUNNING",
        "message": "phone is not running"
      }
    ]
  },
  "message": "batch precheck failed",
  "reason": "BATCH_PRECHECK_FAILED"
}
KolomKeterangan
RESOURCE_NOT_OWNEDSumber daya bukan milik akun saat ini
RESET_IN_PROGRESSReset ponsel sedang berlangsung
OPERATION_IN_PROGRESSAda operasi yang bertentangan
PHONE_NOT_RUNNINGPonsel tidak berjalan
RESOURCE_UNAVAILABLESumber daya tidak ada atau tidak tersedia
PRECHECK_FAILEDPemeriksaan proxy atau prapemeriksaan lain gagal
PROVIDER_REJECTEDPenyedia cloud menolak permintaan atau pengiriman gagal

Aplikasi dan versi

source wajib untuk daftar: official atau user. Filter app_name, app_type integer opsional, paginasi umum. Dikelompokkan package_name; total menghitung aplikasi. Paket urut naik, versions turun berdasarkan version_code. Instal memakai package_name/version_code, bukan version_id/version_name. Ini bukan daftar terinstal di ponsel.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/apps?source=official&page_num=1&page_size=20&app_name=example" \
  -H "X-API-Key: ${API_KEY}"
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 1,
    "apps": [
      {
        "app_id": "app-example",
        "app_name": "Example App",
        "package_name": "com.example.app",
        "app_type": 1,
        "icon_url": "",
        "source": "official",
        "versions": [
          {
            "id": 101,
            "version_id": "version-example",
            "version_name": "1.0.0",
            "version_code": 100
          }
        ]
      }
    ]
  },
  "message": "success"
}

Instalasi massal

Wajib package_name tidak kosong, version_code integer positif, pod_ids valid. Pilih ponsel sendiri yang berjalan. Sebaiknya source eksplisit. Kosong/tidak ada mencari pribadi lalu resmi; sumber eksplisit tanpa fallback. URL APK tidak didukung. data.items mengembalikan pod_id/job_id hanya untuk pengajuan. Tidak ada query hasil instalasi atau kontrak pemeriksaan status batch seperti reset/pengikatan.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones/actions/install-app" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"source":"official","package_name":"com.example.app","version_code":100,"pod_ids":["pod-example-001"]}'
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "items": [
      {
        "pod_id": "pod-example-001",
        "job_id": "job-example-001"
      }
    ]
  },
  "message": "success"
}

Kesalahan dan percobaan ulang

400 perbaiki parameter; 401/403 periksa Key/akun; 409 selesaikan konflik; 429 lakukan backoff. Query boleh diulang dalam kuota. Write tanpa kunci idempotensi publik: setelah timeout/500, periksa penerimaan dahulu. Aplikasi tidak ada, versi salah dan kegagalan pengiriman juga bisa 500 / PUBLIC_API_INTERNAL_ERROR; bukan bukti tidak dijalankan.

HTTPreason
400INVALID_ARGUMENT
400PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED
401INVALID_API_KEY
403API_KEY_DISABLED
403USER_ACCOUNT_UNAVAILABLE
409BATCH_PRECHECK_FAILED
429RATE_LIMIT_EXCEEDED
500PUBLIC_API_INTERNAL_ERROR
500PUBLIC_API_AUTH_ERROR

Keamanan API Key

Simpan Key hanya di variabel lingkungan server atau pengelola rahasia, bukan frontend, repositori publik atau klien. Jangan di URL, body, log atau tiket. Contoh memakai API_KEY. Jika bocor, rotasi/nonaktifkan segera dan perbarui semua pemanggil.

Verifikasi dan dukungan

Untuk dukungan, berikan request_id, path, HTTP, reason, waktu dan parameter tersamarkan, bukan Key. Uji query baca dahulu lalu write pada perangkat uji berizin, dan cek hasil sebelum memperbesar batch.

Artikel terkait

Email contact
Cookie notification iconPemberitahuan Cookie
Situs web ini menggunakan cookie untuk meningkatkan pengalaman pengguna. Untuk mempelajari lebih lanjut tentang kebijakan cookie kami atau menarik persetujuan Anda, silakan periksa Kebijakan Privasi dan Kebijakan Cookie kami.