help-icon
icon

Hướng dẫn Public API

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

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.

Giao diện

HTTP/public_api/v1Mô tả
GET/phonesLiệt kê điện thoại
GET/proxiesLiệt kê proxy
POST/phones/actions/resetĐặt lại hàng loạt
POST/proxies/{proxy_id}/bindGắn proxy có sẵn
GET/appsỨng dụng và phiên bản
POST/phones/actions/install-appCài đặt hàng loạt

Chuẩn bị API Key

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>"

Quy ước và phản hồi

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

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ườngKiểu
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"
}

Liệt kê proxy

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 hàng loạt

Đặ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"]}'

Gắn proxy có sẵn

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"]}'

Kết quả lô và lỗi

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ườngMô tả
RESOURCE_NOT_OWNEDTà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_PROGRESSCó thao tác đang xung đột
PHONE_NOT_RUNNINGĐiện thoại không chạy
RESOURCE_UNAVAILABLETài nguyên không tồn tại hoặc không khả dụng
PRECHECK_FAILEDKiểm tra proxy hoặc kiểm tra trước khác thất bại
PROVIDER_REJECTEDNhà cung cấp đám mây từ chối hoặc gửi yêu cầu thất bại

Ứng dụng và phiên bản

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ài đặt hàng loạt

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"
}

Lỗi và thử lại

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.

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

Bảo mật 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.

Xác minh và hỗ trợ

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ô.

Bài liên quan

Email contact
Cookie notification iconThông báo Cookie
Trang web này sử dụng cookie để cải thiện trải nghiệm người dùng. Để tìm hiểu thêm về chính sách cookie của chúng tôi hoặc rút lại sự đồng ý, vui lòng kiểm tra Chính sách bảo mật và Chính sách Cookie của chúng tôi.