Пакетные заказы
Эндпоинт POST /v1/batches позволяет заказать энергию сразу для группы до 100 адресов-получателей. Для каждого адреса платформа автоматически проверяет активацию, при необходимости пополняет пропускную способность, а затем частями делегирует заказанный объем.
Принципы работы пакетных заказов
| Характеристика | Поведение |
|---|---|
| Ответ API | 202 Accepted: пакет принят в очередь, списания и делегирования еще не начались |
| Получение результата | Запрос GET /v1/batches/{id} либо вебхуки (событие order.confirmed содержит batch_id) |
| Списание средств | По каждому адресу отдельно по тарифу на момент начала исполнения; ограничьте ставку через max_price_sun |
| Изоляция сбоев | Ошибка на одном адресе не влияет на остальные; сбой активации или带宽 не отменяет заказ энергии для этого адреса |
| Отдельные заказы | Каждый адрес получает собственный order_id для последующего контроля, отзыва и сверки |
| Идемпотентность | client_batch_id: тот же id + то же тело возвращает исходный пакет; тот же id + другое тело — ошибка 3010 idempotency_conflict |
| Отмена | POST /v1/batches/{id}/cancel останавливает не начатые строки; взятые в работу возвращают 3002 order_not_cancellable |
| Лимиты частоты | Создание заказов (POST /v1/orders и POST /v1/batches) делят общий лимит 30 rps |
Формат запроса
Поля из defaults применяются ко всем строкам пакета; любая строка может переопределить любое поле.
{
"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 }
]
}
Эндпоинты
| Метод | Путь | Назначение |
|---|---|---|
POST | /v1/batches | Создание пакета заказов |
GET | /v1/batches | Список пакетов |
GET | /v1/batches/{batchId} | Прогресс исполнения и список созданных заказов |
POST | /v1/batches/{batchId}/cancel | Отмена еще не начатых элементов |
Детальное описание схем полей: Справочник API — Пакетные заказы.