Dùng API Key cá nhân để liệt kê điện thoại, proxy, ứng dụng và gửi tác vụ đặt lại, gắn proxy có sẵn, cài ứng dụng. Sáu giao diện khách hàng dùng https://api.foxphone.com và /public_api/v1.
| HTTP | /public_api/v1 | Mô tả |
|---|---|---|
| GET | /phones | Liệt kê điện thoại |
| GET | /proxies | Liệt kê proxy |
| POST | /phones/actions/reset | Đặt lại hàng loạt |
| POST | /proxies/{proxy_id}/bind | Gắn proxy có sẵn |
| GET | /apps | Ứng dụng và phiên bản |
| POST | /phones/actions/install-app | Cài đặt hàng loạt |
Mở Settings từ ảnh đại diện, rồi API Key trong trang cá nhân. Mỗi tài khoản có một Key hợp lệ; tạo lại làm Key cũ mất hiệu lực ngay, giá trị đầy đủ chỉ hiện một lần. Gửi X-API-Key, POST thêm Content-Type: application/json. Không cần JWT web, Cookie, Device-ID, hash hay platform. Bearer không thay thế được.
X-API-Key: <your_api_key>Chỉ giữ Key ở biến môi trường máy chủ hoặc kho bí mật, không nhúng frontend, kho công khai hay máy khách. Không đưa vào URL, body, log hoặc phiếu hỗ trợ. Mẫu dùng API_KEY. Khi lộ, tạo lại hoặc vô hiệu hóa ngay và cập nhật mọi nơi gọi.
export API_KEY="<your_api_key>"Dùng HTTPS. Thành công HTTP 200, dữ liệu trong data; lỗi 4xx/5xx có reason dạng chuỗi. Kiểm tra trạng thái, reason và từng mục, không chỉ message. data lỗi có thể null; giữ request_id. Thông tin đối tác /open_api/v1 là hệ riêng.
Cùng Key dùng chung 60 lần/phút. page_num/page_size thiếu hoặc không dương thành 1/20; page_size trên 100 trả 400. Điện thoại và proxy dùng search, ứng dụng dùng app_name. pod_ids là mảng chuỗi, sau bỏ khoảng trắng, mục rỗng và trùng phải có 1–100 mục. Ghép kết quả theo pod_id.
pod_id luôn là chuỗi. proxy_id, total, id phiên bản và version_code là số JSON; xử lý số nguyên lớn không mất độ chính xác, nhất là JavaScript. Trường 0 và chuỗi rỗng được giữ; danh sách rỗng có thể [] hoặc null.
{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 0,
"phones": []
},
"message": "success"
}Liệt kê điện thoại tài khoản, search theo tên hoặc pod_id. data.phones có pod_id, name, online_status, operating_status, proxy_id; data.total là tổng. proxy_id=0 là chưa liên kết. Liên kết cục bộ không chứng minh đã áp dụng trên đám mây.
online_status: 0 đang khởi động, 1 đang chạy, 2 đã tắt, 3 đang tắt, 4 khởi động lại, 5 đang truyền, 6 sẵn sàng truyền. operating_status: 0 khởi động, 1 chạy, 2 tắt, 3 đang tắt, 4 khởi động lại, 5 đặt lại; 6 chưa định nghĩa.
| Trường | Kiểu |
|---|---|
| pod_id | string |
| name | string |
| online_status | integer |
| operating_status | integer |
| proxy_id | number |
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"
}Tìm proxy theo tên hoặc ID. data.proxies có proxy_id, name, proxy_type, proxy_ip, proxy_port, check_status. Cổng là chuỗi; không trả tài khoản, mật khẩu hay URL làm mới. Trạng thái unchecked, success, failed; dữ liệu cũ có thể rỗng. Kiểm tra trước đây không đảm bảo hiện tại.
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"
}Đặt lại xóa dữ liệu: sao lưu và kiểm tra đích. Chỉ gửi pod_ids, điện thoại phải đang chạy, khả dụng và thuộc tài khoản. Đang tắt, đặt lại hoặc xung đột bị từ chối. phone_template_mode kể cả 0 và phone_template_id kể cả rỗng trả 400 / PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED. Chọn ngẫu nhiên kiểu máy; không có lựa chọn khác thì không chỉ định mẫu. Giữ mô phỏng và cố khôi phục proxy cũ sau kiểm tra; không chọn hay mua proxy mới.
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"]}'proxy_id dương lấy từ danh sách ở đường dẫn, body chỉ có pod_ids. Proxy và máy thuộc tài khoản, proxy còn hạn và qua kiểm tra mới. Máy tắt lưu cấu hình và giữ tắt, áp dụng khi mở sau; máy chạy áp dụng bất đồng bộ, có thể khởi động lại. Xung đột bị từ chối; proxy lỗi trả 409 / BATCH_PRECHECK_FAILED, mục PRECHECK_FAILED.
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"]}'Chỉ đặt lại và gắn dùng successful_pod_ids/failed_items. Lỗi kiểm tra cả lô trả 409 với data.failed_items, không ở metadata cấp ngoài. Có thể tiếp nhận một phần và không hoàn tác xuyên hệ thống. Thành công nghĩa là tiếp nhận/lưu, không phải hoàn tất; có thể null. Không gửi lại toàn lô.
{
"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"
}| Trường | Mô tả |
|---|---|
| RESOURCE_NOT_OWNED | Tài nguyên không thuộc tài khoản hiện tại |
| RESET_IN_PROGRESS | Điện thoại đang được đặt lại |
| OPERATION_IN_PROGRESS | Có thao tác đang xung đột |
| PHONE_NOT_RUNNING | Điện thoại không chạy |
| RESOURCE_UNAVAILABLE | Tài nguyên không tồn tại hoặc không khả dụng |
| PRECHECK_FAILED | Kiểm tra proxy hoặc kiểm tra trước khác thất bại |
| PROVIDER_REJECTED | Nhà cung cấp đám mây từ chối hoặc gửi yêu cầu thất bại |
source bắt buộc khi liệt kê: official hoặc user. Lọc app_name, app_type nguyên tùy chọn và phân trang chung. Gộp theo package_name; total đếm ứng dụng. Gói tăng dần, versions giảm theo version_code. Cài bằng package_name/version_code, không dùng version_id/version_name. Không phải danh sách đã cài trên máy.
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"
}Cần package_name không rỗng, version_code nguyên dương và pod_ids hợp lệ; chọn máy của bạn đang chạy. Nên ghi rõ source. Thiếu/rỗng tìm cá nhân rồi chính thức; chỉ định nguồn không tìm nguồn khác. Không nhận URL APK. data.items trả pod_id/job_id chỉ xác nhận gửi. Không có truy vấn kết quả cài và không dùng hợp đồng kiểm tra trạng thái cả lô của đặt lại/gắn.
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"
}400 sửa tham số; 401/403 kiểm tra Key/tài khoản; 409 xử lý xung đột; 429 chờ tăng dần. Truy vấn được thử lại trong hạn mức. Ghi không có khóa idempotency công bố; sau timeout/500 phải xác minh tiếp nhận trước. Ứng dụng thiếu, sai phiên bản hay lỗi gửi cũng có thể trả 500 / PUBLIC_API_INTERNAL_ERROR, không chứng minh chưa chạy.
| HTTP | reason |
|---|---|
| 400 | INVALID_ARGUMENT |
| 400 | PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED |
| 401 | INVALID_API_KEY |
| 403 | API_KEY_DISABLED |
| 403 | USER_ACCOUNT_UNAVAILABLE |
| 409 | BATCH_PRECHECK_FAILED |
| 429 | RATE_LIMIT_EXCEEDED |
| 500 | PUBLIC_API_INTERNAL_ERROR |
| 500 | PUBLIC_API_AUTH_ERROR |
Chỉ giữ Key ở biến môi trường máy chủ hoặc kho bí mật, không nhúng frontend, kho công khai hay máy khách. Không đưa vào URL, body, log hoặc phiếu hỗ trợ. Mẫu dùng API_KEY. Khi lộ, tạo lại hoặc vô hiệu hóa ngay và cập nhật mọi nơi gọi.
Gửi request_id, đường dẫn, HTTP, reason, thời gian và tham số đã che, không gửi Key. Thử truy vấn trước, rồi ghi trên thiết bị thử được cho phép và kiểm tra kết quả trước khi tăng lô.