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.