Каталог і гео

Право: catalog:read.

GET /api/v1/products

Що продається, з ціною для власника ключа. У списку тільки те, що можна купити просто зараз; слаг поза списком відповідає 400 unknown_product.

Поле	Значення
slug	передається в product під час розрахунку та купівлі: residential, ipv4
family	вид продукту: traffic_gateway (трафік) або dedicated (фіксовані адреси)
unit	одиниця продажу: gb або ip
unit_price	ціна гігабайта для вас; у ipv4 - null, ціна залежить від країни та періоду
monthly_price_from	у ipv4: найнижча ціна однієї адреси за місяць для вас; у трафіку - null
min_volume, volume_presets, volume_discounts	обсяг купівлі трафіку: мінімум, підказки для інтерфейсу, об’ємна драбина у відсотках

Підсумкову суму рахує POST /api/v1/quote.

Параметри продукту

GET /api/v1/products/{product}/options - що можна обрати під час купівлі фіксованих адрес. У продукту трафіку countries порожній: він купується тільки обсягом.

curl "https://ipv.rent/api/v1/products/ipv4/options" \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "type": "ipv4",
  "countries": [
    {
      "code": "us",
      "name": "United States",
      "periods": ["week", "2_weeks", "month", "2_months", "3_months"],
      "quantity_max": null,
      "plans": [
        {
          "id": "dc",
          "traffic_gb": null,
          "periods": ["week", "2_weeks", "month", "2_months", "3_months"],
          "operators": [
            {
              "id": "united-states",
              "name": "United States",
              "available": 374
            }
          ]
        }
      ]
    }
  ]
}

Поле	Куди йде в купівлі	Значення
countries[].code	country	країна, ISO 3166-1 alpha-2
countries[].periods	period	терміни, на які продається країна
countries[].quantity_max	quantity	скільки адрес можна взяти за одну купівлю; null - окремого обмеження немає
plans[].id	plan	тариф; можна не передавати, якщо тариф у країні один
plans[].operators[].id	operator	локація: уся країна або місто; обов’язкова
plans[].operators[].available	-	скільки адрес у локації вільно зараз

Перечитуйте параметри перед купівлею, а не зберігайте в себе: набір країн і залишки змінюються.

Відмови: 400 unknown_product (слаг невідомий або продукт не продається).

Гео-каталог

Тільки для Residential: куди пакет трафіку може виходити. Чотири рівні, і кожен із них:

• приймає обов’язковий product - сьогодні residential;
• підтримує If-None-Match і відповідає 304 без тіла;
• повертає version і не розрізняє регістр кодів.

ETag - непрозорий хеш версії; та сама версія в читабельному вигляді - поле version.

Маршрут	Параметри	Відповідь
GET /api/v1/geo/countries	product	countries[] з code, name, pool (thin | normal | deep)
GET /api/v1/geo/states	product, country	states[] з code і name
GET /api/v1/geo/cities	product, country, state (необов’яз.)	cities[] з code і name
GET /api/v1/geo/asns	product, country	asns[] з code і name

curl "https://ipv.rent/api/v1/geo/countries?product=residential" \
  -H 'Authorization: Bearer YOUR_API_KEY'

Без state cities повертає всі міста країни. Країна, яка більше не обслуговується, - порожній список, а не відмова.

Відмови: 400 validation_failed (не передано product або country), unknown_product (слаг невідомий або продукт не продається); 503 catalog_unavailable.

Коди з цих відповідей - те, що приймає geo під час видачі підключень; значення поза каталогом отримує 422 invalid_targeting.