Конвенции

Деньги и объём - строки

{
  "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 месяцев до выключения.