help-icon
icon

Руководство по Public API

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

Личный API Key позволяет получать телефоны, прокси и приложения и запрашивать сброс, привязку и установку. Шесть клиентских интерфейсов работают на https://api.foxphone.com с базой /public_api/v1.

Интерфейсы

HTTP/public_api/v1Описание
GET/phonesСписок телефонов
GET/proxiesСписок прокси
POST/phones/actions/resetПакетный сброс
POST/proxies/{proxy_id}/bindПривязка прокси
GET/appsПриложения и версии
POST/phones/actions/install-appПакетная установка

Подготовка API Key

Откройте Settings через аватар, затем API Key в личном кабинете. У аккаунта один активный ключ; перевыпуск сразу отменяет старый, полное значение показывается один раз. Отправляйте X-API-Key, для POST также Content-Type: application/json. JWT сайта, Cookie, Device-ID, hash и platform не нужны. Bearer не заменяет этот заголовок.

X-API-Key: <your_api_key>

Храните ключ только на сервере в окружении или хранилище секретов, не во фронтенде, публичном репозитории или клиенте. Не помещайте в URL, тело, логи и обращения. Примеры используют API_KEY. При утечке немедленно замените/отключите и обновите вызывающие системы.

export API_KEY="<your_api_key>"

Правила и ответы

Используйте HTTPS. Успех: HTTP 200, данные внутри data. Ошибки: 4xx/5xx со строкой reason. Проверяйте статус, reason и результаты элементов, не только message. data ошибки может быть null; сохраняйте request_id. Партнерские /open_api/v1 используют другие учетные данные.

Один ключ делит 60 вызовов/мин. Отсутствующие или неположительные page_num/page_size становятся 1/20; page_size более 100 дает 400. Телефоны/прокси используют search, приложения app_name. pod_ids: 1–100 строк после очистки пробелов, пустых и повторов. Сопоставляйте по pod_id, не порядку.

pod_id всегда строка. proxy_id, total, id версии и version_code — числа JSON; большие целые читайте без потери точности, особенно в JavaScript. Нулевые и пустые значения сохраняются; пустой список может быть [] или null.

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

Список телефонов

Список устройств текущего аккаунта, search по имени или pod_id. data.phones содержит pod_id, name, online_status, operating_status, proxy_id; data.total — число. proxy_id=0 означает отсутствие связи. Локальная связь не подтверждает завершение в облаке.

online_status: 0 запускается, 1 работает, 2 остановлен, 3 останавливается, 4 перезапускается, 5 трансляция, 6 готова. operating_status: 0 запуск, 1 работает, 2 остановлен, 3 остановка, 4 перезапуск, 5 сброс; 6 не определено. Поля различаются.

ПолеТип
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"
}

Список прокси

Поиск прокси по имени/ID. data.proxies содержит proxy_id, name, proxy_type, proxy_ip, proxy_port, check_status. Порт — строка; учетные данные и URL обновления не выдаются. Статусы unchecked, success, failed; старые записи могут быть пустыми. Прошлый тест не гарантирует доступность сейчас.

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

Пакетный сброс

Сброс удаляет данные: сохраните копию и проверьте цели. Только pod_ids; устройства должны работать, быть доступны и принадлежать аккаунту. Остановленные, сбрасываемые и конфликтующие отклоняются. phone_template_mode, включая 0, и phone_template_id, включая пустой, дают 400 / PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED. Модель случайная; без альтернативы шаблон не задается. Симуляция сохраняется, прежний прокси по возможности восстанавливается после проверки; новые прокси не выбираются и не покупаются.

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 из списка в пути, только pod_ids в теле. Ресурсы принадлежат аккаунту, прокси действителен и проходит новую проверку. Остановленный телефон сохраняет настройки и остается остановленным до следующего запуска. Работающий применяет асинхронно и может перезапуститься. Конфликты отклоняются; неверный прокси: 409 / BATCH_PRECHECK_FAILED с 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"]}'

Результаты и ошибки

Только сброс/привязка используют successful_pod_ids/failed_items. Общая предварительная ошибка: 409 с data.failed_items, не верхним metadata. Возможен частичный прием без межсистемного отката. Успех означает прием/сохранение, не завершение, и может быть null. Не повторяйте весь пакет.

{
  "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"
}
ПолеОписание
RESOURCE_NOT_OWNEDРесурс не принадлежит текущей учётной записи
RESET_IN_PROGRESSИдёт сброс телефона
OPERATION_IN_PROGRESSВыполняется конфликтующая операция
PHONE_NOT_RUNNINGТелефон не запущен
RESOURCE_UNAVAILABLEРесурс отсутствует или недоступен
PRECHECK_FAILEDПроверка прокси или другая предварительная проверка не пройдена
PROVIDER_REJECTEDОблачный провайдер отклонил запрос или отправка не удалась

Приложения и версии

В запросе source обязателен: official или user. Фильтры app_name, необязательный целый app_type и общая пагинация. Группировка по package_name; total считает приложения. Пакеты по возрастанию, versions по убыванию version_code. Установка по package_name/version_code, не version_id/version_name. Это не установленные на телефоне приложения.

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

Пакетная установка

Нужны непустой package_name, положительный целый version_code и корректные pod_ids; выбирайте свои работающие телефоны. Указывайте source явно. Пустой ищет личные, затем официальные; явный источник без перехода. URL APK не поддерживается. data.items с pod_id/job_id означает отправку. Нет запроса результата установки и общего контракта проверки состояния как у сброса/привязки.

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 исправить параметры; 401/403 проверить ключ/аккаунт; 409 устранить конфликт; 429 отложить повтор. Чтение повторяется в квоте. Нет публичного ключа идемпотентности записи: после timeout/500 сначала проверьте прием. Отсутствующее приложение, версия или сбой отправки также дают 500 / PUBLIC_API_INTERNAL_ERROR; это не доказательство невыполнения.

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

Безопасность ключа

Храните ключ только на сервере в окружении или хранилище секретов, не во фронтенде, публичном репозитории или клиенте. Не помещайте в URL, тело, логи и обращения. Примеры используют API_KEY. При утечке немедленно замените/отключите и обновите вызывающие системы.

Проверка и поддержка

Передайте request_id, путь, HTTP, reason, время и очищенные параметры, но не ключ. Сначала проверьте чтение, затем запись на разрешенных тестовых устройствах и результат перед увеличением пакета.

Похожие статьи

Email contact
Cookie notification iconУведомление о файлах cookie
Этот веб-сайт использует файлы cookie для улучшения пользовательского опыта. Чтобы узнать больше о нашей политике использования файлов cookie или отозвать свое согласие, ознакомьтесь с нашей Политика конфиденциальности и Политика использования файлов cookie.