Residential: sub-users и трафик

Управляйте residential sub-users своего аккаунта с помощью API-токена родителя. У каждого sub-user собственные proxy credentials и квота трафика. Все примеры используют API v2.

Подготовьте API-запросы

Передавайте API-токен своего аккаунта в заголовке Authorization: Bearer каждого запроса управления. Задайте LTESOCKS_API_TOKEN в окружении. Аккаунт определяется автоматически; передавать parent_id не нужно.

API_URL='https://api.ltesocks.io/v2'

curl "$API_URL/user" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}"

curl "$API_URL/proxies/residential?page=1&page_size=20" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}"

Поле residentialProxy.availableData в GET /user содержит остаток residential-трафика аккаунта в байтах. В предложениях traffic_limit измеряется в MB, а цены — в центах USD. Поля sub-user traffic_bytes, used_bytes и remaining_bytes — целые числа байтов: 1073741824 байта = 1 GiB.

Купите трафик для аккаунта

Выберите предложение из data: запишите его id в TARIFF_ID, id выбранной опции — в TARIFF_OPTION_ID, а актуальный price_hash опции — в PRICE_HASH. Перед покупкой проверьте final_price. Задайте новый UUID в PURCHASE_KEY и сохраните его вместе с телом запроса.

curl -X POST "$API_URL/proxies/residential" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${PURCHASE_KEY}" \
  --data "{\"tariff_id\":${TARIFF_ID},\"tariff_option_id\":${TARIFF_OPTION_ID},\"price_hash\":\"${PRICE_HASH}\"}"

При 409 с error_code=priceChanged заново получите предложения и подтвердите новую цену перед новой покупкой. После таймаута повторяйте исходный ключ и тело. Неопределённый ответ 500 может сохраняться 24 часа: выясните результат покупки перед новым платежом. Повторно прочитайте /user для проверки результата. См. пакеты residential и покупку трафика.

Создайте sub-user

Задайте новый UUID в CREATE_KEY для этого создания. Передавайте только суффикс логина: customer_01 станет {parent_login}_customer_01. Суффикс допускает ASCII-буквы, цифры, подчёркивания и дефисы, длина — 4–50 символов; полный логин должен укладываться в 64 символа. Email создаётся автоматически. Не передавайте email, first_name и last_name.

POST/proxies/residential/subusersСоздание sub-user

curl -X POST "$API_URL/proxies/residential/subusers" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${CREATE_KEY}" \
  --data '{"login":"customer_01","traffic_bytes":1073741824}'

Укажите положительное целое traffic_bytes, максимум 109951162777600 байтов (100 TiB). Создание и увеличение квоты ограничены доступным распределением трафика аккаунта и общей квотой sub-user. По умолчанию выбирается активный пакет; необязательный package_id должен соответствовать этому пакету. Сокращённый пример ответа:

{
  "success": true,
  "code": 201,
  "data": {
    "id": "e8b6be73-fc1e-4f06-8a3d-b16207b30ec5",
    "login": "parent_customer_01",
    "traffic_bytes": 1073741824,
    "used_bytes": 0,
    "remaining_bytes": 1073741824
  }
}

Сохраните полученный data.id в CHILD_ID; замените демонстрационный UUID ниже этим значением. Все последующие запросы выполняются в рамках авторизованного родителя.

Получите список и данные sub-user

GET/proxies/residential/subusersСписок sub-users

curl --get "$API_URL/proxies/residential/subusers" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=10'

Задавайте page начиная с 1. Страница содержит до 10 sub-users; page_size принимает только 10. Для перехода по страницам используйте page_info.page, page_info.page_size и page_info.total_count. Любой из двух параметров включает пагинацию; один page_size=10 выбирает первую страницу. Без обоих параметров возвращается полный список без page_info. Поисковый запрос этот endpoint не поддерживает.

GET/proxies/residential/subusers/{childId}Данные sub-user

CHILD_ID='e8b6be73-fc1e-4f06-8a3d-b16207b30ec5'

curl "$API_URL/proxies/residential/subusers/$CHILD_ID" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}"

curl "$API_URL/proxies/residential/subusers/$CHILD_ID/package" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}"

GET/proxies/residential/subusers/{childId}/packageСчётчики трафика

GET /proxies/residential/subusers/{childId}/package возвращает в data поля id, package_id, traffic_bytes (выделенная квота), used_bytes (израсходованный трафик) и remaining_bytes (остаток).

Получите данные для подключения

GET/proxies/residential/subusers/{childId}/credentialsProxy credentials

curl "$API_URL/proxies/residential/subusers/$CHILD_ID/credentials" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}"

Для авторизации proxy-подключений используйте data.username и data.password в точности из ответа. Username подключения зависит от пакета и может отличаться от логина sub-user. Bearer-токен авторизует запросы управления. Пример ответа:

{
  "success": true,
  "code": 200,
  "data": {
    "username": "product_residential",
    "password": "<sub-user-package-password>"
  }
}

Не записывайте полученный пароль в логи приложения. Выбор страны, региона, города и ASN описан на странице Residential-таргетинг.

Измените квоту трафика

Создайте отдельный UUID для каждой запланированной операции (ADD_KEY, SUBTRACT_KEY, RESET_KEY). Для повторов одной операции сохраняйте ключ и тело запроса. Добавление 512 MiB:

POST/proxies/residential/subusers/{childId}/traffic/{action}Управление трафиком

curl -X POST "$API_URL/proxies/residential/subusers/$CHILD_ID/traffic/add" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${ADD_KEY}" \
  --data '{"traffic_bytes":536870912}'

Вычитание 256 MiB. Количество должно быть положительным и не превышать remaining_bytes:

curl -X POST "$API_URL/proxies/residential/subusers/$CHILD_ID/traffic/subtract" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${SUBTRACT_KEY}" \
  --data '{"traffic_bytes":268435456}'

Сброс оставшегося трафика sub-user без передачи traffic_bytes:

curl -X POST "$API_URL/proxies/residential/subusers/$CHILD_ID/traffic/reset" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H "Idempotency-Key: ${RESET_KEY}"

Проверьте счётчики в ответе и повторно прочитайте /package. Операция add ограничена доступным распределением трафика аккаунта и общей квотой 109951162777600 байтов. Нарушение квоты возвращает 422, неподдерживаемое действие — 404.

Удалите sub-user

Остановите трафик с credentials дочернего пользователя, проверьте CHILD_ID и задайте новый DELETE_KEY. Операция удаляет sub-user; при неопределённом результате повторяйте запрос с тем же ключом.

DELETE/proxies/residential/subusers/{childId}Удаление sub-user

curl -X DELETE "$API_URL/proxies/residential/subusers/$CHILD_ID" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H "Idempotency-Key: ${DELETE_KEY}"

Успешное удаление возвращает HTTP 200 с пустым массивом data:

{ "success": true, "code": 200, "data": [] }

Обрабатывайте ошибки и повторы

При 401 проверьте API-токен. При 403 убедитесь, что используете аккаунт, которому принадлежит sub-user; если доступ всё ещё запрещён, обратитесь в поддержку. При 404 проверьте CHILD_ID и действие с трафиком в URL. При 409 прочитайте message перед повтором конфликтующей операции. При 422 проверьте message и ошибки полей errors, если они есть: ключ запроса, количество трафика, доступный остаток и допустимые поля. После 429 подождите перед повтором. При таймауте или ответе 500, 502, 503 сохраните исходный ключ, проверьте состояние и повторите ту же операцию с тем же телом. См. Идемпотентность и безопасные повторы.

API Reference генерируется из опубликованного контракта v2.