FoxPhone Public API cho phép liệt kê điện thoại đám mây và proxy trong tài khoản hiện tại, đồng thời gửi hàng loạt tác vụ đặt lại thiết bị và gán proxy. Phiên bản hiện tại cung cấp bốn endpoint sau.
1. Chuẩn bị API Key
Nhấp vào ảnh đại diện ở góc trên bên phải, chọn Settings, sau đó mở trang API Key trong hồ sơ tài khoản.
Tạo Key trên trang API Key. Mỗi tài khoản chỉ được có một Key đang hoạt động:
- Tạo lại Key sẽ vô hiệu hóa Key cũ ngay lập tức.
- Khi tắt Key, mọi yêu cầu Public API sẽ bị từ chối ngay.
- Key đầy đủ chỉ hiển thị một lần khi tạo. Hãy lưu Key trong hệ thống quản lý bí mật có kiểm soát.
Gửi Key trong header của yêu cầu:
X-API-Key: <your_api_key>Lưu ý bảo mật: Không đặt API Key trong URL, nội dung yêu cầu, mã nguồn, nhật ký hoặc phiếu hỗ trợ. ID tài nguyên và Key trong hướng dẫn này chỉ là giá trị minh họa.
2. Quy tắc chung
- URL cơ sở môi trường production:
https://api.foxphone.com/public_api/v1 - Cả bốn endpoint dùng chung giới hạn 60 yêu cầu mỗi phút cho mỗi API Key.
- Với tham số danh sách,
page_numcó giá trị mặc định là1;page_sizecó giá trị mặc định là20, có giá trị tối đa là100;searchlà tùy chọn. - Yêu cầu hàng loạt chấp nhận từ 1 đến 100
pod_ids; máy chủ tự động loại bỏ mục trùng lặp. - Bạn chỉ có thể truy cập tài nguyên thuộc tài khoản sở hữu API Key; API không cho phép chọn tài khoản khác bằng tham số.
- Nếu bước kiểm tra trước phát hiện tài nguyên không hợp lệ hoặc đang có thao tác xung đột, toàn bộ yêu cầu trong lô sẽ không được gửi.
- Nếu có lỗi sau khi bắt đầu gửi tác vụ đến hệ thống từ xa, các tác vụ đã được tiếp nhận sẽ không bị hoàn tác; phản hồi liệt kê riêng các mục thành công và thất bại.
3. Liệt kê điện thoại đám mây
Dùng endpoint sau để phân trang danh sách điện thoại đám mây của tài khoản hiện tại:
GET /public_api/v1/phones?page_num=1&page_size=20&search=pod-exampleDùng search để tìm điện thoại đám mây theo tên hoặc pod_id.
Ví dụ yêu cầu:
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"Ví dụ phản hồi:
{
"total": 1,
"phones": [
{
"pod_id": "pod-example-001",
"name": "automation-phone",
"online_status": 1,
"operating_status": 0,
"proxy_id": "42"
}
]
}proxy_id là 0 khi điện thoại chưa được gán proxy.
4. Liệt kê proxy
Dùng endpoint sau để phân trang danh sách proxy trong tài khoản hiện tại:
GET /public_api/v1/proxies?page_num=1&page_size=20&search=42Dùng search để tìm proxy theo tên hoặc proxy_id. Endpoint không trả về tên người dùng hoặc mật khẩu proxy.
Ví dụ yêu cầu:
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"Ví dụ phản hồi:
{
"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. Gửi yêu cầu đặt lại thiết bị hàng loạt
Dùng endpoint sau để gửi hàng loạt tác vụ đặt lại thiết bị:
POST /public_api/v1/phones/actions/reset
Content-Type: application/jsonNội dung yêu cầu:
{
"pod_ids": ["pod-example-001", "pod-example-002"]
}Giới hạn hiện tại: Endpoint đặt lại không hỗ trợ chỉ định proxy_id hoặc tham số proxy khác trong nội dung yêu cầu. Để đổi proxy, hãy đợi quá trình đặt lại hoàn tất rồi gọi endpoint gán proxy hiện có hàng loạt.
Ví dụ yêu cầu:
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"Nếu điện thoại đã có tác vụ đặt lại đang chạy, yêu cầu mới sẽ trả về RESET_IN_PROGRESS trong bước kiểm tra trước và không gửi tác vụ trùng lặp.
6. Gán proxy hiện có hàng loạt
Trước tiên lấy proxy_id từ endpoint danh sách proxy, sau đó gọi endpoint sau:
POST /public_api/v1/proxies/{proxy_id}/bind
Content-Type: application/jsonNội dung yêu cầu:
{
"pod_ids": ["pod-example-001", "pod-example-002"]
}Ví dụ yêu cầu:
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 và tất cả điện thoại phải thuộc tài khoản hiện tại. Điện thoại đã tắt vẫn có thể được gán proxy. Điện thoại đang đặt lại, bật/tắt nguồn, khởi động lại hoặc thực hiện thao tác proxy khác sẽ bị từ chối trong bước kiểm tra trước.
7. Phản hồi hàng loạt
Đặt lại thiết bị và gán proxy sử dụng cùng cấu trúc phản hồi:
{
"successful_pod_ids": ["pod-example-001"],
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PROVIDER_REJECTED",
"message": "provider rejected the operation"
}
]
}Kiểm tra trước thất bại sẽ trả về HTTP 409 và mã lỗi BATCH_PRECHECK_FAILED. Trong metadata lỗi, failed_items liệt kê pod_id, code và message; toàn bộ lô sẽ không được gửi.
Lỗi xảy ra sau khi hệ thống từ xa bắt đầu tiếp nhận được báo trong phản hồi nghiệp vụ qua successful_pod_ids và failed_items để thể hiện kết quả thực tế.
8. Lỗi thường gặp
| Trạng thái HTTP | Mã lỗi | Mô tả |
|---|---|---|
| 400 | INVALID_ARGUMENT | Định dạng tham số, số lượng mục hoặc giá trị phân trang không hợp lệ |
| 401 | INVALID_API_KEY | API Key bị thiếu, sai định dạng hoặc không còn hợp lệ |
| 403 | API_KEY_DISABLED | API Key đã bị tắt |
| 403 | USER_ACCOUNT_UNAVAILABLE | Tài khoản sở hữu API Key không khả dụng |
| 409 | BATCH_PRECHECK_FAILED | Kiểm tra trước thất bại; chưa gửi mục nào trong lô |
| 429 | RATE_LIMIT_EXCEEDED | Vượt quá giới hạn yêu cầu mỗi phút |
Khi nhận HTTP 429, hãy thử lại sau theo chiến lược backoff. Với HTTP 409, trước tiên dùng failed_items để khắc phục trạng thái tài nguyên; không gửi lại ngay yêu cầu giống hệt.
