Public API FoxPhone позволяет просматривать облачные телефоны и прокси текущего аккаунта, а также пакетно отправлять задачи сброса устройств и привязки прокси. В текущей версии доступны четыре endpoint.
1. Подготовка API Key
Нажмите на аватар в правом верхнем углу, выберите Settings, затем откройте страницу API Key в профиле аккаунта.
Создайте ключ на странице API Key. Для аккаунта разрешён только один действующий ключ:
- При создании нового ключа предыдущий сразу становится недействительным.
- После отключения ключа все запросы к Public API сразу отклоняются.
- Полный ключ показывается только один раз при создании. Сохраните его в контролируемом хранилище секретов.
Передавайте ключ в заголовке запроса:
X-API-Key: <your_api_key>Безопасность: Не помещайте API Key в URL, тело запроса, исходный код, журналы или обращения в поддержку. Идентификаторы ресурсов и ключи в руководстве являются примерами.
2. Общие правила
- Базовый URL production-среды:
https://api.foxphone.com/public_api/v1 - Для всех четырёх endpoint действует общий лимит: 60 запросов в минуту на один API Key.
- Для параметров списка:
page_numзначение по умолчанию —1;page_sizeзначение по умолчанию —20, максимальное значение —100;search— необязательный параметр. - Пакетный запрос может содержать от 1 до 100 значений
pod_ids; сервер автоматически удаляет дубликаты. - Доступны только ресурсы аккаунта, которому принадлежит API Key. Указать другой аккаунт параметром нельзя.
- Если предварительная проверка обнаружит недопустимый ресурс или конфликтующую операцию, пакет не будет отправлен.
- При частичных сбоях после начала отправки удалённых задач уже принятые операции не отменяются; в ответе отдельно перечисляются успешные и неуспешные элементы.
3. Список облачных телефонов
Используйте endpoint для постраничного получения списка облачных телефонов текущего аккаунта:
GET /public_api/v1/phones?page_num=1&page_size=20&search=pod-exampleИспользуйте search, чтобы найти облачный телефон по имени или pod_id.
Пример запроса:
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"Пример ответа:
{
"total": 1,
"phones": [
{
"pod_id": "pod-example-001",
"name": "automation-phone",
"online_status": 1,
"operating_status": 0,
"proxy_id": "42"
}
]
}proxy_id равно 0 означает, что прокси сейчас не привязан к телефону.
4. Список прокси
Используйте endpoint для постраничного получения прокси текущего аккаунта:
GET /public_api/v1/proxies?page_num=1&page_size=20&search=42Используйте search, чтобы найти прокси по имени или proxy_id. Endpoint не возвращает имя пользователя или пароль прокси.
Пример запроса:
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"Пример ответа:
{
"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. Пакетная отправка сброса устройств
Используйте endpoint для пакетной отправки задач сброса устройств:
POST /public_api/v1/phones/actions/reset
Content-Type: application/jsonТело запроса:
{
"pod_ids": ["pod-example-001", "pod-example-002"]
}Текущее ограничение: Endpoint сброса не поддерживает указание proxy_id или других параметров прокси в теле запроса. Чтобы сменить прокси, дождитесь завершения сброса и вызовите endpoint пакетной привязки существующего прокси.
Пример запроса:
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"Если для телефона уже выполняется сброс, новый запрос на этапе предварительной проверки вернёт RESET_IN_PROGRESS и не отправит повторную задачу.
6. Пакетная привязка существующего прокси
Сначала получите proxy_id через endpoint списка прокси, затем вызовите endpoint:
POST /public_api/v1/proxies/{proxy_id}/bind
Content-Type: application/jsonТело запроса:
{
"pod_ids": ["pod-example-001", "pod-example-002"]
}Пример запроса:
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"Прокси и все телефоны должны принадлежать текущему аккаунту. Прокси можно привязать и к выключенному телефону. Телефоны со сбросом, операцией питания, перезагрузкой или другой операцией с прокси будут отклонены при предварительной проверке.
7. Ответы пакетных запросов
Для сброса устройства и привязки прокси используется одинаковая структура ответа:
{
"successful_pod_ids": ["pod-example-001"],
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PROVIDER_REJECTED",
"message": "provider rejected the operation"
}
]
}При ошибке предварительной проверки возвращаются HTTP 409 и код ошибки BATCH_PRECHECK_FAILED. В метаданных ошибки failed_items перечислены соответствующие pod_id, code и message; в этом случае пакет не отправляется.
Сбои после начала приёма удалённой системой отражаются в ответе операции через successful_pod_ids и failed_items с фактическим результатом.
8. Частые ошибки
| Статус HTTP | Код ошибки | Описание |
|---|---|---|
| 400 | INVALID_ARGUMENT | Недопустимый формат параметра, количество элементов или значение пагинации |
| 401 | INVALID_API_KEY | API Key отсутствует, имеет неверный формат или недействителен |
| 403 | API_KEY_DISABLED | API Key отключён |
| 403 | USER_ACCOUNT_UNAVAILABLE | Аккаунт владельца API Key недоступен |
| 409 | BATCH_PRECHECK_FAILED | Пакетная проверка не пройдена; ничего не отправлено |
| 429 | RATE_LIMIT_EXCEEDED | Превышен лимит запросов в минуту |
При HTTP 429 повторите запрос позже с увеличивающейся задержкой. При HTTP 409 сначала используйте failed_items для исправления состояния ресурса; не отправляйте тот же запрос повторно сразу.
