Пакеты — Справочник API

Один запрос — множество получателей.

Метод	Путь	Описание
`GET`	`/v1/batches`	Список пакетов
`POST`	`/v1/batches`	Заказ для нескольких получателей в одном запросе
`GET`	`/v1/batches/{batchId}`	Прогресс выполнения пакета
`POST`	`/v1/batches/{batchId}/cancel`	Отмена еще не начатых элементов пакета

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

Список пакетов

GET /v1/batches · listBatches

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

Параметры

Параметр	Где	Тип	Обязательный	Описание
`limit`	query	integer
`cursor`	query	string		Непрозрачный курсор из `next_cursor` предыдущего ответа.

Ответы

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

Поля ответа

Поле	Тип	Обязательное	Описание
`data`	array of object (Batch)	да
`data[].id`	string	да
`data[].client_batch_id`	string \| null
`data[].status`	enum: `queued`, `processing`, `completed`, `partial`, `failed`, `cancelled`	да	Статус пакета. `partial` означает, что часть получателей успешно обработана, а часть нет — проверяйте `items`.
`data[].items_accepted`	integer	да
`data[].summary`	object	да	Количество элементов по статусам.
`data[].summary.total`	integer
`data[].summary.queued`	integer
`data[].summary.processing`	integer
`data[].summary.completed`	integer
`data[].summary.partial`	integer
`data[].summary.failed`	integer
`data[].summary.insufficient_funds`	integer
`data[].summary.cancelled`	integer
`data[].items`	array of object (BatchItem)	да
`data[].items[].receiver`	string	да	TRON-адрес Base58Check (начинается с `T`, 34 символа).
`data[].items[].tracking_id`	string	да	`<client_batch_id>:<receiver>` — идентификатор элемента в пакете.
`data[].items[].status`	enum: `queued`, `processing`, `completed`, `partial`, `failed`, `insufficient_funds`, `cancelled`	да
`data[].items[].resource`	enum: `energy`, `bandwidth`, `activation`		`energy` — энергия TRON, ресурс для TRC-20 переводов. · `bandwidth` — пропускная способность TRON (net). · `activation` — разовая активация аккаунта.
`data[].items[].amount`	integer
`data[].items[].tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`		Срок аренды. `GET /v1/prices` возвращает актуальные тарифы.
`data[].items[].delivered_amount`	integer		Фактически доставленный объем ресурсов.
`data[].items[].order_ids`	array of string		Созданные заказы для получателя (несколько, если объем был разбит на части). Это стандартные заказы: их можно проверять и отзывать отдельно.
`data[].items[].delegate_hashes`	array of string
`data[].items[].charged_amount_sun`	integer (int64)		Сумма списания в SUN (1 TRX = 1 000 000 SUN). Всегда целое число.
`data[].items[].activation`	object
`data[].items[].bandwidth`	object
`data[].items[].attempts`	integer
`data[].items[].started_at`	string (date-time) \| null
`data[].items[].finished_at`	string (date-time) \| null
`data[].items[].failure`	null \| object
`data[].created_at`	string (date-time)	да
`data[].finished_at`	string (date-time) \| null
`next_cursor`	string \| null	да

Заказ для нескольких получателей в одном запросе

POST /v1/batches · createBatch

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

До 100 получателей в одном запросе. Для каждого получателя платформа выполняет полную последовательность: активация адреса при необходимости, пополнение пропускной способности при ее нехватке и доставка основного ресурса с автоматическим дроблением больших объемов.

Ответ 202 Accepted: пакет поставлен в очередь, средства еще не списаны, ресурсы не доставлены. Проверяйте статус через GET /v1/batches/{id} или вебхуки.

Ошибка одного получателя никогда не влияет на остальных, а сбой шага активации или пропускной способности не останавливает доставку энергии.

Оплата рассчитывается индивидуально для каждого получателя по цене на момент исполнения. Используйте параметр max_price_sun для каждого элемента, чтобы ограничить максимальную цену.

Каждый получатель создает отдельный заказ со своим ID. client_batch_id служит ключом идемпотентности всего пакета: повторный запрос с тем же ID и телом возвращает исходный пакет; с другим телом — отклоняется с 3010 idempotency_conflict.

Параметры

Параметр	Где	Тип	Обязательный	Описание
`Idempotency-Key`	header	string		Пользовательский ключ идемпотентности для безопасных повторов (8–128 символов `A-Z a-z 0-9 . _ : -`). Хранится 24 часа.

Тело запроса

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

Поле	Тип	Обязательное	Описание
`client_batch_id`	string		Ваш идентификатор пакета и ключ идемпотентности. Обязателен, если не передан заголовок `Idempotency-Key`.
`defaults`	object (BatchItemOptions)		Параметры по умолчанию для всех элементов пакета.
`defaults.resource`	enum: `energy`, `bandwidth`, `activation`		`energy`, `bandwidth` или `activation`.
`defaults.amount`	integer
`defaults.tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`		Срок аренды.
`defaults.activate`	boolean
`defaults.bandwidth`	boolean		Пополнять пропускную способность получателя при нехватке перед передачей энергии.
`defaults.bandwidth_amount`	integer		Количество единиц bandwidth для пополнения.
`defaults.max_price_sun`	integer (int64)		Максимальная цена в SUN.
`defaults.client_order_id_prefix`	string		Префикс для генерации `client_order_id = "<prefix>-<receiver>"`.
`items`	array of object	да	Список получателей. Дублирующиеся адреса отклоняются с `2006 duplicate_receiver`.
`items[].receiver`	string	да	TRON-адрес Base58Check (начинается с `T`, 34 символа).
`items[].resource`	enum: `energy`, `bandwidth`, `activation`
`items[].amount`	integer
`items[].tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`
`items[].activate`	boolean
`items[].bandwidth`	boolean
`items[].bandwidth_amount`	integer
`items[].max_price_sun`	integer (int64)
`items[].client_order_id_prefix`	string

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

json

{
  "client_batch_id": "acme-payout-2026-09-11-01",
  "defaults": {
    "resource": "energy",
    "tier": "1h",
    "amount": 65000,
    "activate": true,
    "bandwidth": true,
    "bandwidth_amount": 400
  },
  "items": [
    {"receiver":"TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"},
    {"receiver":"TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","amount":131000},
    {"receiver":"TYYyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy","bandwidth":false}
  ]
}

Ответы

Статус	Значение
`200`	Повторный запрос с тем же `client_batch_id` и телом — возвращен исходный пакет.
`202`	Пакет принят и поставлен в очередь. Списаний пока не производилось.
`400`	Некорректный запрос — невалидный JSON, неизвестное поле или неверный тип.
`401`	Отсутствуют, некорректны или отклонены учетные данные.
`402`	Недостаточно средств для покрытия заказа.
`409`	Конфликт идемпотентности или состояния.
`422`	Синтаксически корректный запрос, но действие невозможно.
`429`	Слишком много запросов.
`500`	Ошибка на нашей стороне.
`503`	Временно недоступно.

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

Поле	Тип	Обязательное	Описание
`id`	string	да
`client_batch_id`	string \| null
`status`	enum: `queued`, `processing`, `completed`, `partial`, `failed`, `cancelled`	да	Статус выполнения пакета.
`items_accepted`	integer	да
`summary`	object	да	Сводка по элементам.
`summary.total`	integer
`summary.queued`	integer
`summary.processing`	integer
`summary.completed`	integer
`summary.partial`	integer
`summary.failed`	integer
`summary.insufficient_funds`	integer
`summary.cancelled`	integer
`items`	array of object (BatchItem)	да
`items[].receiver`	string	да	TRON-адрес Base58Check (начинается с `T`, 34 символа).
`items[].tracking_id`	string	да	`<client_batch_id>:<receiver>`.
`items[].status`	enum: `queued`, `processing`, `completed`, `partial`, `failed`, `insufficient_funds`, `cancelled`	да
`items[].resource`	enum: `energy`, `bandwidth`, `activation`
`items[].amount`	integer
`items[].tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`
`items[].delivered_amount`	integer
`items[].order_ids`	array of string		ID созданных заказов.
`items[].delegate_hashes`	array of string		Хеши транзакций делегирования.
`items[].charged_amount_sun`	integer (int64)		Списанная сумма в SUN.
`items[].activation`	object
`items[].activation.status`	enum: `planned`, `not_needed`, `done`, `failed`, `skipped`
`items[].activation.hash`	string \| null
`items[].bandwidth`	object
`items[].bandwidth.status`	enum: `planned`, `enough`, `done`, `failed`, `skipped`
`items[].bandwidth.order_id`	string \| null
`items[].bandwidth.skip_reason`	enum: `option_off`, `amount_large` \| null
`items[].attempts`	integer
`items[].started_at`	string (date-time) \| null
`items[].finished_at`	string (date-time) \| null
`items[].failure`	null \| object
`items[].failure.code`	integer
`items[].failure.slug`	string
`items[].failure.message`	string
`created_at`	string (date-time)	да
`finished_at`	string (date-time) \| null

Прогресс выполнения пакета

GET /v1/batches/{batchId} · getBatch

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

Параметры

Параметр	Где	Тип	Обязательный	Описание
`batchId`	path	string	да	ID пакета (`bat_…`) или `cid:<client_batch_id>`.
`receiver`	query	string		Фильтр для получения элемента только по данному адресу вместо всего пакета.

Ответы

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

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

Те же поля, что описаны выше в ответе POST /v1/batches.

Отмена еще не начатых элементов пакета

POST /v1/batches/{batchId}/cancel · cancelBatch

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

Удаляет из очереди всех получателей, обработка которых еще не началась. Получатели, уже находящиеся в процессе обработки, не прерываются.

Параметры

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

Ответы

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

Поля ответа

Поле	Тип	Обязательное	Описание
`id`	string	да
`cancelled`	integer	да	Количество получателей, снятых с очереди.

Пакеты — Справочник API

Список пакетов

Параметры

Ответы

Поля ответа

Заказ для нескольких получателей в одном запросе

Параметры

Тело запроса

Ответы

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

Прогресс выполнения пакета

Параметры

Ответы

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

Отмена еще не начатых элементов пакета

Параметры

Ответы

Поля ответа

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

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