Фиксированные адреса

Операции с пакетом фиксированных адресов (family: dedicated, продукт ipv4). Каждая действует на весь пакет: на все его адреса сразу. На пакете трафика эти маршруты отвечают 422 unsupported_capability.

Какие операции доступны пакету, перечислено в capabilities его карточки: prolong, credentials, replace, fingerprint, renewal.

Срок и статусы

Статус	Что происходит	Что можно сделать
`provisioning`	пакет выдаётся, до 2 минут	подождать
`active`	адреса работают до `expires_at`	всё
`expired`	срок вышел, адреса не отвечают	продлить до `extendable_until` - вернутся те же адреса
`closed`	прошёл `extendable_until`, адреса освобождены	только новая покупка
`suspended`	пакет отключён	написать в поддержку

Поля карточки, которые относятся к сроку:

Поле	Значение
`expires_at`	конец оплаченного срока
`extendable_until`	до какого момента продление возвращает те же адреса
`credentials_retired`	`true` - пароль отключён после окончания срока; продление выдаст новый

Когда срок заканчивается, в журнал событий приходит package.expired.

GET /api/v1/packages/{id}/prolong-options

На какие периоды можно продлить и сколько это стоит для вас. Право packages:read.

{
  "options": [
    {
      "period": "week",
      "price": "1.98"
    },
    {
      "period": "2_weeks",
      "price": "2.58"
    },
    {
      "period": "month",
      "price": "2.98"
    },
    {
      "period": "2_months",
      "price": "5.96"
    },
    {
      "period": "3_months",
      "price": "8.94"
    }
  ],
  "currency": "USD"
}

price - цена за весь пакет, за все его адреса.

POST /api/v1/packages/{id}/prolong

Продлить пакет. Право packages:write, Idempotency-Key обязателен: это списание. Тело: {"period": "month"}, период - из prolong-options.

curl -X POST https://ipv.rent/api/v1/packages/57/prolong \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"period":"month"}'

{
  "order_id": 140,
  "package_id": 57,
  "status": "completed",
  "price": "2.98",
  "expires_at": "2026-12-04T12:00:00+00:00",
  "credentials_reissued": false
}

Период прибавляется к текущему expires_at, а если срок уже вышел - к моменту продления.
Адреса и логин остаются прежними.
credentials_reissued: true - старый пароль был отключён и выдан новый; возьмите его из карточки пакета.
Продление создаёт отдельный заказ с applied_to_package_id.

Отказы:

400 - invalid_body (нет тела или не JSON), validation_failed
404 - not_found
409 - idempotency_in_progress
422 - unknown_period, insufficient_balance, prolong_window_closed (адреса уже не вернуть - пакет closed, нужна новая покупка), unsupported_capability, purchase_refunded, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - order_failed, order_needs_attention, operation_indeterminate - как у покупки

POST /api/v1/packages/{id}/renewal

Автопродление. Право packages:write. Ничего не списывает.

curl -X POST https://ipv.rent/api/v1/packages/57/renewal \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"enabled":true,"period":"month"}'

Поле	Значение
`enabled`	обязательно: `true` или `false`
`period`	на какой период продлевать каждый раз; без поля - остаётся прежний

Ответ - карточка пакета. Как работает автопродление:

оно включено по умолчанию, период - тот, что был куплен;
списание - за сутки до expires_at, по цене на этот момент; дата и сумма - в renewal.next_charge_at и renewal.next_charge_amount;
если денег не хватило, renewal.last_failure становится insufficient_balance, попытки повторяются каждые несколько часов ещё 3 дня после expires_at;
после этого автопродление выключается само, renewal.disabled_at заполнен.

Отказы: 400 invalid_body (нет enabled); 404 not_found; 422 unknown_period, unsupported_capability.

POST /api/v1/packages/{id}/replace

Заменить все адреса пакета новыми в той же локации. Право packages:write. Тело не нужно. Бесплатно.

Замена идёт в фоне. Ответ - 202 и карточка с replacement.state: pending. Читайте карточку, пока state не сменится, обычно это меньше минуты:

`replacement.state`	Значение
`pending`	замена идёт
`done`	в `addresses` новые адреса, старые не работают
`failed`	ничего не изменилось, можно запросить снова

Логин, пароль, срок и отпечаток не меняются. Повторная замена возможна через 30 дней: replace_available_at в карточке показывает, когда.

Отказы:

404 - not_found
409 - replace_in_progress (замена уже идёт)
422 - package_expired (срок вышел - сначала продлите), unsupported_capability
429 - replace_cooldown (адреса недавно заменялись; дата - в replace_available_at)

POST /api/v1/packages/{id}/fingerprint

Отпечаток p0f: адреса представляются выбранной ОС и браузером. Один профиль на весь пакет. Право packages:write. Бесплатно.

curl -X POST https://ipv.rent/api/v1/packages/57/fingerprint \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"profile":"windows_chrome"}'

profile - значение из fingerprint.profiles карточки: windows_chrome, windows_edge, windows_firefox, android_chrome, macos_chrome. null выключает подмену.

Новый отпечаток применяется через 2-3 минуты. Соединения, открытые до смены, сохраняют прежний - переподключитесь.

Отказы: 400 validation_failed (профиля нет в списке); 404 not_found; 422 package_expired, unsupported_capability.

Пароль

Перевыпуск пароля - общий маршрут POST /api/v1/packages/{id}/password. Логин не меняется, старый пароль перестаёт работать сразу на всех адресах пакета.