Подписки — Справочник API

Автопополнение ресурсов для адреса.

Метод	Путь	Описание
`GET`	`/v1/subscriptions/plans`	Тарифные планы резервирования энергии со средней ценой за использование
`GET`	`/v1/subscriptions`	Список подписок
`POST`	`/v1/subscriptions`	Настройка автопополнения адреса
`GET`	`/v1/subscriptions/{subscriptionId}`	Получение информации о подписке
`PATCH`	`/v1/subscriptions/{subscriptionId}`	Изменение или приостановка подписки
`DELETE`	`/v1/subscriptions/{subscriptionId}`	Отмена подписки

Сгенерировано из openapi.yaml во время сборки. Базовый URL https://api.tenergy.me/v1 или https://api-nile.tenergy.me/v1 в сети Nile (Окружения). Каждый запрос ниже подписывается в соответствии с разделом Аутентификация, если в строке Аутентификация не указано иное.

Тарифные планы резервирования энергии со средней ценой за использование

GET /v1/subscriptions/plans · listSubscriptionPlans

Аутентификация: Публичный — учетные данные не требуются.

Публичный вызов; переданный API-ключ валидируется при наличии. Значение per_use для тарифа типа grid рассчитывается по текущему окну времени суток. Значение average_price рассчитывается сервером для 10, 50, 200 и 1 000 использований в сутки.

Ответы

Статус	Значение
`200`	Список активных тарифных планов (от меньшего резерва к большему).

Поля ответа

Поле	Тип	Обязательное	Описание
`data`	array of object (SubscriptionPlan)	да
`data[].slug`	string	да
`data[].name`	string	да
`data[].reserve_energy`	integer	да	Объем энергии, постоянно поддерживаемый делегированным на адрес.
`data[].daily_fee_sun`	integer	да
`data[].daily_fee_trx`	number	да
`data[].per_use`	object	да
`data[].per_use.mode`	enum: `flat`, `grid`	да	`grid` = цена энергии за 1 ч в текущем временном окне × 65 000.
`data[].per_use.energy_per_use`	integer	да
`data[].per_use.price_sun`	integer \| null	да	`null`, если часовой тариф временно на паузе.
`data[].per_use.price_trx`	number \| null	да
`data[].per_use.day_part`	string \| null	да	ID временного окна для `grid`; `null` для `flat`.
`data[].throughput_rule`	string	да
`data[].refill`	object	да
`data[].refill.low`	integer	да	Пополнение при снижении доступной энергии ниже этой планки.
`data[].refill.high`	integer	да	Пополнение до этого уровня.
`data[].uses_within_reserve_per_day`	integer	да
`data[].average_price`	array of object	да	Средняя цена за транзакцию: суточная абонплата / N + цена за использование, для N = 10, 50, 200, 1000.
`data[].average_price[].uses_per_day`	integer	да
`data[].average_price[].average_sun`	integer \| null	да
`data[].average_price[].average_trx`	number \| null	да
`data[].average_price[].within_reserve`	boolean	да
`at`	string (date-time)	да

Список подписок

GET /v1/subscriptions · listSubscriptions

Аутентификация: API-ключ (HMAC).

Параметры

Параметр	Где	Тип	Описание
`status`	query	enum: `active`, `paused`, `suspended`, `cancelled`	Фильтр по статусу.
`receiver`	query	string	Фильтр по адресу получателя.
`limit`	query	integer
`cursor`	query	string	Непрозрачный курсор из `next_cursor` предыдущего ответа.

Ответы

Статус	Значение
`200`	OK
`401`	Отсутствуют, некорректны или отклонены учетные данные.
`429`	Слишком много запросов.
`500`	Ошибка на нашей стороне.

Поля ответа

Поле	Тип	Обязательное	Описание
`data`	array of object (Subscription)	да
`data[].id`	string	да
`data[].receiver`	string	да	TRON-адрес Base58Check (начинается с `T`, 34 символа).
`data[].resource`	enum: `energy`, `bandwidth`	да
`data[].mode`	enum: `refill`, `renewal`	да
`data[].tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`	да	Срок аренды.
`data[].threshold_amount`	integer
`data[].refill_amount`	integer
`data[].max_price_sun`	integer (int64) \| null
`data[].max_refills_per_day`	integer \| null
`data[].daily_fee_sun`	integer (int64)		Плата за мониторинг за календарный день активности подписки.
`data[].status`	enum: `active`, `paused`, `suspended`, `cancelled`	да	`paused` устанавливается пользователем; `suspended` выставляется платформой при нехватке баланса (автоматически снимается после пополнения); `cancelled` — терминальный статус.
`data[].label`	string \| null
`data[].last_refill_at`	string (date-time) \| null
`data[].last_order_id`	string \| null
`data[].refills_today`	integer
`data[].created_at`	string (date-time)	да
`data[].updated_at`	string (date-time)
`data[].plan`	string		Код тарифного плана (присутствует только для тарифных подписок).
`data[].reserve_energy`	integer \| null
`data[].delegated_energy`	integer		Энергия, делегированная на адрес прямо сейчас.
`data[].next_billing_at`	string (date-time) \| null
`data[].grace_until`	string (date-time) \| null		Льготный период сохранения делегирования при ошибке списания.
`data[].events`	array of object (SubscriptionEvent)		Только в `GET /v1/subscriptions/{id}` для тарифных подписок: последние 20 событий.
`data[].events[].id`	string	yes
`data[].events[].kind`	enum: `refill`, `charge`, `pause`, `resume`, `cancel`, `top_up_failed`	yes
`data[].events[].energy_delta`	integer \| null
`data[].events[].amount_sun`	integer \| null
`data[].events[].txid`	string \| null
`data[].events[].ts`	string (date-time)	yes
`next_cursor`	string \| null	yes

Настройка автопополнения адреса

POST /v1/subscriptions · createSubscription

Аутентификация: API-ключ (HMAC).

Отслеживает адрес и автоматически покупает ресурсы, когда их свободный объем опускается ниже threshold_amount. Два режима работы:

mode: "refill" — пополнение по требованию. Адрес опрашивается и пополняется при падении ниже порогового значения. Оплачивается каждый заказ пополнения плюс посуточная абонентская плата за мониторинг.
mode: "renewal" — продление постоянной аренды. Аренда срока tier продлевается по мере истечения, чтобы доступность ресурсов на адресе не прерывалась.

Биллинг: каждое пополнение или продление — это обычный заказ, списываемый по действующей цене, плюс daily_fee_sun за каждый календарный день активности подписки. Если баланса не хватает на очередное пополнение, подписка переходит в статус suspended (она не удаляется), и отправляется вебхук subscription.suspended; она возобновляется автоматически после пополнения баланса.

Один адрес может иметь максимум одну подписку на каждый тип ресурса. Повторная подписка отклоняется с кодом 3011 subscription_exists.

Параметры

Параметр	Где	Тип	Обязательный	Описание
`Idempotency-Key`	header	string		Клиентский ключ идемпотентности (8–128 символов).

Тело запроса

JSON (SubscriptionRequest), обязательно.

Поле	Тип	Обязательное	Описание
`receiver`	string	да	TRON-адрес Base58Check (начинается с `T`, 34 символа).
`resource`	enum: `energy`, `bandwidth`	да
`mode`	enum: `refill`, `renewal`	да	`refill` пополняет при падении баланса; `renewal` непрерывно продлевает аренду.
`tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`	да	Срок аренды.
`threshold_amount`	integer	да	Порог срабатывания пополнения.
`refill_amount`	integer	да	Объем ресурсов для покупки при пополнении.
`max_price_sun`	integer (int64)		Пропускать пополнение, если цена превышает этот лимит, чтобы избежать скачков цен.
`max_refills_per_day`	integer		Защитный лимит количества пополнений в сутки, предотвращающий утечку баланса. Настоятельно рекомендуется.
`label`	string \| null

Пример тела запроса из контракта (значения для иллюстрации):

json

{
  "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "resource": "energy",
  "mode": "refill",
  "tier": "1h",
  "threshold_amount": 65000,
  "refill_amount": 131000,
  "max_price_sun": 3000000,
  "max_refills_per_day": 48
}

Ответы

Статус	Значение
`201`	Создана
`400`	Некорректный запрос — невалидный JSON, неизвестное поле или неверный тип.
`401`	Отсутствуют, некорректны или отклонены учетные данные.
`402`	Недостаточно средств для покрытия заказа.
`409`	Конфликт состояния объекта или дублирование подписки.
`422`	Синтаксически корректный запрос, но действие невозможно.
`429`	Слишком много запросов.
`500`	Ошибка на нашей стороне.

Поля ответа (`Subscription`)

Те же поля, что в ответе GET /v1/subscriptions.

Получение информации о подписке

GET /v1/subscriptions/{subscriptionId} · getSubscription

Аутентификация: API-ключ (HMAC).

Параметры

Параметр	Где	Тип	Обязательный	Описание
`subscriptionId`	path	string	да

Ответы

Статус	Значение
`200`	OK
`401`	Отсутствуют, некорректны или отклонены учетные данные.
`404`	Объект не найден или принадлежит другому аккаунту.
`500`	Ошибка на нашей стороне.

Поля ответа (`Subscription`)

Те же поля, что в списке подписок.

Изменение или приостановка подписки

PATCH /v1/subscriptions/{subscriptionId} · updateSubscription

Аутентификация: API-ключ (HMAC).

Передайте любое подмножество изменяемых полей. Поле status принимает только значения active и paused. Статус suspended устанавливается платформой при нехватке средств и сбрасывается автоматически после пополнения; статус cancelled достигается через DELETE. Пустое тело запроса отклоняется с 2002 empty_patch.

Параметры

Параметр	Где	Тип	Обязательный	Описание
`subscriptionId`	path	string	да

Тело запроса

JSON (SubscriptionPatch), обязательно.

Поле	Тип	Обязательное	Описание
`status`	enum: `active`, `paused`
`tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`
`threshold_amount`	integer
`refill_amount`	integer
`max_price_sun`	integer (int64)
`max_refills_per_day`	integer
`label`	string \| null

Ответы

Статус	Значение
`200`	Обновлена
`400`	Некорректный запрос — невалидный JSON, неизвестное поле или неверный тип.
`401`	Отсутствуют, некорректны или отклонены учетные данные.
`404`	Объект не найден или принадлежит другому аккаунту.
`422`	Синтаксически корректный запрос, но действие невозможно.
`500`	Ошибка на нашей стороне.

Поля ответа (`Subscription`)

Те же поля, что в объекте Subscription.

Отмена подписки

DELETE /v1/subscriptions/{subscriptionId} · cancelSubscription

Аутентификация: API-ключ (HMAC).

Останавливает будущие пополнения. Уже доставленные ресурсы продолжают действовать до истечения оплаченного срока; они не отзываются досрочно и не возмещаются. Подписка остается доступной для чтения со статусом status: "cancelled".

Параметры

Параметр	Где	Тип	Обязательный	Описание
`subscriptionId`	path	string	да

Ответы

Статус	Значение
`204`	Отменена. Тело ответа пустое.
`401`	Отсутствуют, некорректны или отклонены учетные данные.
`404`	Объект не найден или принадлежит другому аккаунту.
`500`	Ошибка на нашей стороне.

Подписки — Справочник API

Тарифные планы резервирования энергии со средней ценой за использование

Ответы

Поля ответа

Список подписок

Параметры

Ответы

Поля ответа

Настройка автопополнения адреса

Параметры

Тело запроса

Ответы

Поля ответа (Subscription)

Получение информации о подписке

Параметры

Ответы

Поля ответа (Subscription)

Изменение или приостановка подписки

Параметры

Тело запроса

Ответы

Поля ответа (Subscription)

Отмена подписки

Параметры

Ответы

Поля ответа (`Subscription`)

Поля ответа (`Subscription`)

Поля ответа (`Subscription`)