API для разработчиков

Покупать прокси и управлять ими можно из своего кода: оформлять заказы, читать пакеты, продлевать, следить за событиями. Всё, что вы покупаете, становится пакетом. Пакеты бывают двух видов, их различает поле family:

	Residential	IPv4
family	traffic_gateway	dedicated
Что покупаете	объём трафика в гигабайтах	N выделенных адресов на срок
Чем платите	за гигабайты, трафик не сгорает	за адрес за период: неделя, 2 недели, месяц, 2 или 3 месяца
Подключения	собираете сколько угодно строк с любым гео	фиксированный список адресов с одним логином и паролем
Смена IP	ротация или ссылка смены IP	замена всех адресов пакета раз в 30 дней
Продукт	Residential	IPv4

Покупка, список пакетов и карточка пакета - общие маршруты для обоих видов. Операции, которые есть только у одного вида, описаны отдельно: трафик и фиксированные адреса.

База и аутентификация

https://ipv.rent

curl https://ipv.rent/api/v1/balance \
  -H 'Authorization: Bearer YOUR_API_KEY'

Регистрация - на app.ipv.rent, после неё подтвердите почту: без подтверждения вход не откроется.

Ключ выпускается в кабинете: Профиль → API-ключи → Создать ключ. Секрет показывается один раз, активных ключей на аккаунт - до 20.

Отозванный ключ перестаёт приниматься сразу, и в журнал попадает событие api_key.revoked.

401 invalid_api_key - ключ не принят. 403 insufficient_scope - у ключа нет права, которого требует маршрут.

Схемы запросов и ответов со всеми полями и примерами - в справочнике OpenAPI.

Права ключа

Ключ, выпущенный без указания прав, получает все. Изменить набор у выпущенного ключа нельзя.

Право	Что открывает
catalog:read	продукты и их параметры, гео-каталог, расчёт цены
packages:read	список пакетов, карточка пакета, варианты продления
packages:write	покупка и все операции с пакетами: долив, подключения, пароль, продление, замена адресов, отпечаток, автопродление
orders:read	заказы
orders:write	зарезервировано - сегодня его не требует ни один маршрут
billing:read	баланс и транзакции
events:read	журнал событий

Маршруты

Каталог и покупка - для обоих видов:

Маршрут	Право	Idempotency-Key
GET /api/v1/products	catalog:read	-
GET /api/v1/products/{product}/options	catalog:read	-
POST /api/v1/quote	catalog:read	нет
POST /api/v1/packages	packages:write	обязателен
GET /api/v1/packages	packages:read	-
GET /api/v1/packages/{id}	packages:read	-
POST /api/v1/packages/{id}/password	packages:write	нет

Только Residential:

Маршрут	Право	Idempotency-Key
GET /api/v1/geo/countries, /states, /cities, /asns	catalog:read	-
POST /api/v1/packages/{id}/proxies	packages:write	нет
POST /api/v1/packages/{id}/topup	packages:write	обязателен
POST /api/v1/packages/{id}/rotation-secret	packages:write	нет

Только IPv4:

Маршрут	Право	Idempotency-Key
GET /api/v1/packages/{id}/prolong-options	packages:read	-
POST /api/v1/packages/{id}/prolong	packages:write	обязателен
POST /api/v1/packages/{id}/replace	packages:write	нет
POST /api/v1/packages/{id}/fingerprint	packages:write	нет
POST /api/v1/packages/{id}/renewal	packages:write	нет

Аккаунт:

Маршрут	Право	Idempotency-Key
GET /api/v1/orders, /orders/{id}	orders:read	-
GET /api/v1/balance, /transactions	billing:read	-
GET /api/v1/events	events:read	-

Операция другого вида на пакете отвечает 422 unsupported_capability.

Пополнение баланса и управление ключами - только в кабинете.

Лимиты

120 запросов в минуту на ключ плюс 30 в минуту на запросы, которые что-то меняют (POST). На каждом ответе RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset; превышение - 429 с retry_after и Retry-After: подождите указанное число секунд и повторите.

Поддержка

Telegram: @ipvrent_support, почта [email protected]. Приложите request_id из тела отказа.

Новости и статус сервиса - в канале t.me/ipvrent.