Конвенції

Гроші та обсяг - рядки

{
  "balance": "124.30",
  "currency": "USD"
}
{
  "purchased_gb": "25.000",
  "used_gb": "2.566",
  "left_gb": "22.434"
}

Розбирайте в decimal, не у float. Валюта - USD. Гігабайт = 10^9 байтів.

Час

ISO-8601 з явним зсувом, завжди UTC: 2026-08-28T14:03:11+00:00.

Розширювані переліки

Статус замовлення, тип транзакції, тип події, статус пакета, kind, family поповнюються всередині v1 без попередження - незнайоме значення потрібно пережити. У фільтрах незнайоме значення читається як «без фільтра».

Пагінація

Параметр	Значення
`offset`	скільки рядків пропустити; за замовчуванням 0
`limit`	1..200, за замовчуванням 50 (для `GET /api/v1/packages` - 200)

Обидва обрізаються, а не відхиляються, і повертаються в тілі вже обрізаними. Відповідь несе total.

GET /api/v1/orders?limit=100&offset=100
    -> { "orders": [...], "total": 317, "offset": 100, "limit": 100 }

У списках, до яких пишуть, offset адресує позицію: під час повного вивантаження дедуплікуйте за id. Порядок фіксований - нові зверху.

Журнал подій читається інакше: ?after=<id>, відповідь несе next_after.

Ідемпотентність

Операції, які списують гроші, вимагають заголовок: POST /api/v1/packages (купівля), POST /api/v1/packages/{id}/topup (доливання трафіку) і POST /api/v1/packages/{id}/prolong (продовження адрес).

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Рядок до 255 символів, пробіли по краях обрізаються.

Повтор із тим самим ключем і тим самим тілом повертає ту саму відповідь. Генеруйте ключ до запиту й використовуйте повторно під час повтору, включно з повтором після таймауту.

Ключ пам’ятається 24 години: той самий ключ через добу починає нову операцію.

Відмови:

422 - idempotency_key_required (заголовка немає), idempotency_key_invalid (порожній або довший за 255), idempotency_key_reused (той самий ключ з іншим тілом)
409 - idempotency_in_progress (попередній запит ще виконується - повторіть трохи пізніше з тим самим ключем)
500 - operation_indeterminate (повтор із ключем операції, результат якої не визначено - див. Відмови)

Кеш гео-каталогу

Рівні гео-каталогу віддають ETag - непрозорий хеш версії каталогу. Надсилайте його в If-None-Match - отримаєте 304 без тіла. Та сама версія в читабельному вигляді лежить у тілі полем version.

Версіонування

Випускається у v1 без попередження: нове поле у відповіді, новий необов’язковий параметр, нове значення розширюваного переліку, новий ендпоінт, новий код помилки на наявному статусі.

Тільки новою версією: видалення або перейменування поля, звуження типу, нове обов’язкове поле в запиті, зміна статусу чи коду для описаного випадку, зміна значення за замовчуванням.

Депрекація: заголовки Deprecation і Sunset, не менше ніж 6 місяців до вимкнення.