Оркестратор — групові замовлення в один виклик

Надсилайте до 100 адрес в одному запиті, і Netts виконає повну послідовність дій для кожної з них: активує адресу за потреби, поповнить її bandwidth, якщо його недостатньо, а потім орендує energy, автоматично розбиваючи великі обсяги на частини.

Ви миттєво отримуєте 202 Accepted із ключем відстеження і не чекаєте на з'єднанні. Перебіг виконання потім зчитується з ендпоінта статусу.

Навіщо використовувати

Замовлення energy для нової адреси зазвичай вимагає трьох окремих викликів у правильному порядку з власною логікою повторних спроб між ними. Оркестратор об'єднує це в один запит і виконує послідовність для кожної адреси:

probe → activation (if the address is not active) → bandwidth (if free < 400) → energy

Помилка під час активації або виділення bandwidth не зупиняє замовлення energy для цієї адреси, а збій на одній адресі ніколи не впливає на інші.

Базова URL-адреса ендпоінта

https://netts.io/apiv2/orchestrator

Заголовки запиту

Заголовок	Обов'язковий	Опис
Content-Type	Так	application/json
X-API-KEY	Так	Ваш API-ключ із панелі керування Netts
X-Real-IP	Так	IP-адреса з вашого білого списку
X-Idempotency-Key	Так*	Ваш ключ для цього замовлення, 12–128 символів із `A-Z a-z 0-9 . _ : -`

* Потрібно вказати або заголовок X-Idempotency-Key, або поле clientRequestId у тілі запиту. Якщо ви не передасте жодного з них, запит буде відхилено з кодом 5010.

Ключ ідентифікує все замовлення. Повторний запит із тим самим ключем повертає початковий результат замість створення другого замовлення — див. Ідемпотентність.

Створення замовлення — `POST /apiv2/orchestrator`

Тіло запиту

json

{
    "clientRequestId": "my-batch-2026-01-01-001",
    "defaults": {
        "bandwidth": true,
        "bandwidthAmount": 400,
        "bandwidthPeriod": "1h",
        "check": true,
        "trx_send": false
    },
    "items": [
        { "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", "amount": 65000 },
        { "receiveAddress": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "amount": 131000 },
        { "receiveAddress": "TYYyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy", "amount": 61000, "bandwidth": false }
    ]
}

Поля верхнього рівня

Поле	Тип	Обов'язкове	Опис
`items`	array	Так	Від 1 до 100 адрес. Дублікати в межах одного замовлення відхиляються.
`clientRequestId`	string	Ні	Ваш ідентифікатор замовлення, 8–128 символів із `A-Z a-z 0-9 . _ : -`. Використовується як ключ ідемпотентності, якщо заголовок відсутній.
`defaults`	object	Ні	Значення, що застосовуються до кожного елемента, який їх не перевизначає.

Поля елемента

Кожне поле, крім receiveAddress та amount, також можна вказати в defaults. Значення в самому елементі має пріоритет над значенням за замовчуванням.

Поле	Тип	За замовчуванням	Опис
`receiveAddress`	string	—	Адреса TRON, що отримує energy
`amount`	int	—	Energy для цієї адреси, 61 000 … 50 000 000
`bandwidth`	bool	`true`	Замовити bandwidth для цієї адреси, коли його недостатньо
`bandwidthAmount`	int	`400`	`400` або `5000`
`bandwidthPeriod`	string	`1h`	`5m` або `1h`
`check`	bool	див. нижче	Спочатку перевірити вільний bandwidth і пропустити замовлення, якщо його достатньо
`trx_send`	bool	`false`	Передається до сервісу bandwidth без змін
`activation`	bool	`true`	Активувати адресу, якщо вона неактивна. Встановіть `false`, щоб пропустити цей крок для адреси, яка гарантовано вже активна.

check за замовчуванням дорівнює true, коли bandwidthAmount становить 400, і false в інших випадках — замовлення 5 000 одиниць зазвичай означає, що вони потрібні вам незалежно від наявного залишку.

Обсяги вказуються на кожну адресу. В одному запиті можна вільно комбінувати різні значення; єдиним обмеженням є загальна сума.

Ліміти

Ліміт	Значення
Адрес на замовлення	100
Energy на адресу	61 000 … 50 000 000
Загальна кількість energy на замовлення	50 000 000
Одночасних замовлень у процесі на акаунт	3
Одночасних адрес у процесі на акаунт	300
Мінімальний баланс для прийняття	4 TRX

Ліміт у 50 000 000 застосовується до суми за всіма адресами в запиті, а не до кожної окремо.

Відповідь — прийнято (202, код `10202`)

json

{
    "detail": {
        "code": 10202,
        "status": "accepted",
        "msg": "Order accepted for processing",
        "data": {
            "idempotencyKey": "my-batch-2026-01-01-001",
            "requestId": 1234,
            "itemsAccepted": 3,
            "statusUrl": "/apiv2/orchestrator/status/my-batch-2026-01-01-001",
            "items": [
                {
                    "deliveryKey": 5001,
                    "trackingId": "my-batch-2026-01-01-001:TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "amount": 65000,
                    "energyChunks": 1,
                    "activation": "planned",
                    "bandwidth": "planned",
                    "status": "queued"
                }
            ]
        }
    }
}

202 означає поставлено в чергу, але ще не виконано. Кошти ще не списувалися. Опитуйте statusUrl для отримання результату.

trackingId — це пара ключ ідемпотентності + адреса, тобто ідентифікатор однієї адреси всередині вашого замовлення. Використовуйте його у власних логах та для звірки.

Приклад

bash

curl -X POST https://netts.io/apiv2/orchestrator \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -H "X-Idempotency-Key: my-batch-2026-01-01-001" \
  -d '{
        "items": [
          {"receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", "amount": 65000}
        ]
      }'

Перевірка перебігу — `GET /apiv2/orchestrator/status/{idempotencyKey}`

Додайте ?address=T…, щоб отримати інформацію про одну адресу замість усього замовлення.

json

{
    "detail": {
        "code": 10000,
        "status": "processing",
        "data": {
            "idempotencyKey": "my-batch-2026-01-01-001",
            "requestId": 1234,
            "clientRequestId": "my-batch-2026-01-01-001",
            "summary": {
                "total": 3, "queued": 1, "processing": 1, "completed": 1,
                "partial": 0, "failed": 0, "insufficient_balance": 0,
                "credentials_revoked": 0, "cancelled": 0
            },
            "items": [
                {
                    "deliveryKey": 5001,
                    "trackingId": "my-batch-2026-01-01-001:TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "status": "completed",
                    "energy": {
                        "requested": 65000,
                        "delegated": 65000,
                        "status": "done",
                        "chunks": { "total": 1, "done": 1 },
                        "orderIds": ["1Hxxxxxxxxxx"],
                        "hashes": ["0000000000000000000000000000000000000000000000000000000000000000"]
                    },
                    "activation": { "status": "not_needed", "orderId": null, "hash": null },
                    "bandwidth": {
                        "status": "enough", "orderId": "B1Hxxxxxxxxxxxxxx",
                        "amount": 400, "period": "1h", "hashes": [], "skipReason": null
                    },
                    "attempts": 1,
                    "startedAt": "2026-01-01T00:00:00+00:00",
                    "finishedAt": "2026-01-01T00:00:03+00:00"
                }
            ]
        }
    }
}

Невідомий ключ або ключ, що належить іншому акаунту, повертає 404.

Значення статусу адреси

Статус	Значення
`queued`	Очікує на обробку
`processing`	У процесі виконання
`completed`	Уся замовлена energy делегована
`partial`	Частину делеговано успішно, частину — ні
`failed`	Нічого не делеговано
`insufficient_balance`	Зупинено — ваш баланс опустився нижче мінімального
`credentials_revoked`	Ваш API-ключ було видалено або деактивовано під час виконання замовлення
`cancelled`	Видалено з черги за вашим запитом на скасування

Значення статусу кроку

Крок	Значення
`activation`	`not_needed`, `done`, `failed`, `skipped`, `skipped_unavailable`
`bandwidth`	`enough`, `done`, `failed`, `skipped`
`energy`	`done`, `partial`, `failed`

bandwidth.skipReason пояснює причину skipped: option_off (ви вимкнули цю опцію), energy_gt_600000 (великі замовлення energy не потребують поповнення bandwidth).

Хеші делегування

energy.hashes — це ваше підтвердження доставки. Якщо energy надається зовнішнім постачальником, хеш невідомий на момент замовлення — він з'являється приблизно через хвилину, і адреса не вважається завершеною, доки хеші не будуть зібрані або не закінчиться вікно очікування. Адреса зі статусом completed і наявним хешем є повністю розрахованою.

Скасування — `POST /apiv2/orchestrator/cancel/{idempotencyKey}`

Видаляє з черги кожну адресу, яку ще не було взято в обробку.

json

{
    "detail": {
        "code": 10005,
        "status": "cancelled",
        "msg": "Order cancelled: 7 addresses removed from queue",
        "data": { "cancelled": 7 }
    }
}

Адреси, які вже перебувають у статусі processing, не перериваються: частина їхньої energy вже може бути оплачена. Скасування діє за принципом «якнайкраще» (best-effort) для залишку.

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

Замовлення ідентифікується вашим ключем — заголовком X-Idempotency-Key або clientRequestId, якщо заголовок відсутній.

Повторний запит	Результат
Той самий ключ, те саме тіло	208 із вихідним замовленням та `originalAcceptedAt` — без створення другого замовлення
Той самий ключ, інше тіло	409 `4090 IDEMPOTENCY_CONFLICT`

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

Усередині замовлення кожна адреса має власний внутрішній ключ, тому повторний запит також ніколи не призведе до подвійного списання коштів за одну адресу.

Тарифікація

Сам оркестратор нічого не стягує. Кожен крок тарифікується тим сервісом, який його виконує, за його звичайною ціною:

Крок	Як списується
Activation	окреме списання, номер замовлення `A…`
Bandwidth	окреме списання, номер замовлення `B1H…` — лише у разі фактичного делегування
Energy	одне списання за кожну частину (chunk), номер замовлення `1H…`

Параметр check: true за наявності достатньої кількості вільного bandwidth нічого не коштує — статус встановлюється в enough, і замовлення не створюється. Великі обсяги energy взагалі пропускають крок bandwidth.

Якщо під час виконання пакета у вас закінчиться баланс, решта адрес отримає статус insufficient_balance без спроби виконання.

Довідник кодів помилок

Код	Опис	HTTP-статус
`10202`	Замовлення прийнято / вже було прийнято	202 / 208
`10000`	Статус повернуто	200
`10005`	Замовлення скасовано	200
`5004`	Некоректне поле: формат адреси, `amount` поза діапазоном, `bandwidthAmount` не 400/5000, `bandwidthPeriod` не 5m/1h, тіло не є JSON-об'єктом	400
`5005`	`items` відсутнє або порожнє	400
`5006`	Дублікат `receiveAddress` в одному замовленні	400
`5009`	Некоректний формат `X-Idempotency-Key` або `clientRequestId`	400
`5010`	Не надано ані `X-Idempotency-Key`, ані `clientRequestId`	400
`5012`	Загальна кількість energy в запиті перевищує 50 000 000	400
`-1`	Недійсний API-ключ / IP немає в білому списку	401
`1004`	Баланс нижче мінімуму в 4 TRX	402
`-1`	Замовлення не знайдено (або воно належить не вам)	404
`4090`	`IDEMPOTENCY_CONFLICT` — той самий ключ, інше тіло запиту	409
`4220`	Помилка валідації запиту (подробиці в `data.errors`)	422
`429` / `5011`	Забагато активних замовлень, адрес або частин (chunks) у процесі	429
`5003`	Замовлення не прийнято — сервіс тимчасово недоступний, можна повторити запит	503

Помилка 503 під час створення безпечна щодо збоїв: нічого не було збережено і кошти не списувалися.

Ліміти запитів (Rate Limits)

Обмежується для кожної вихідної IP-адреси:

Період	Ліміт
1 секунда	20 запитів

Перевищення ліміту запитів (429)

json

{ "message": "API rate limit exceeded" }

Примітки

202 не є підтвердженням доставки. Сприймайте це як «поставлено в чергу». Результат доступний через ендпоінт статусу.
Адреси обробляються паралельно, до 5 одночасно в межах одного замовлення, тому великий пакет не чекає на одну повільну адресу. Порядок завершення не гарантується.
Розбиття на частини (chunking) відбувається автоматично: суми понад 1 000 000 діляться на рівні частини, кожна з яких стає окремим замовленням energy. energy.orderIds та energy.hashes містять повний їхній перелік.
Окремого вебхука для замовлень оркестратора в цілому немає. Кожне делегування energy все одно генерує звичайний вебхук delegation.confirmed, див. Вебхуки.
Пов'язані ендпоінти: Активатор, Bandwidth, Замовлення 1H.

Оркестратор — групові замовлення в один виклик ​

Навіщо використовувати ​

Базова URL-адреса ендпоінта ​

Заголовки запиту ​

Створення замовлення — POST /apiv2/orchestrator ​

Тіло запиту ​

Поля верхнього рівня ​

Поля елемента ​

Ліміти ​

Відповідь — прийнято (202, код 10202) ​

Приклад ​

Перевірка перебігу — GET /apiv2/orchestrator/status/{idempotencyKey} ​

Значення статусу адреси ​

Значення статусу кроку ​

Хеші делегування ​

Скасування — POST /apiv2/orchestrator/cancel/{idempotencyKey} ​

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

Тарифікація ​

Довідник кодів помилок ​

Ліміти запитів (Rate Limits) ​

Перевищення ліміту запитів (429) ​

Примітки ​

Оркестратор — групові замовлення в один виклик

Навіщо використовувати

Базова URL-адреса ендпоінта

Заголовки запиту

Створення замовлення — `POST /apiv2/orchestrator`

Тіло запиту

Поля верхнього рівня

Поля елемента

Ліміти

Відповідь — прийнято (202, код `10202`)

Приклад

Перевірка перебігу — `GET /apiv2/orchestrator/status/{idempotencyKey}`

Значення статусу адреси

Значення статусу кроку

Хеші делегування

Скасування — `POST /apiv2/orchestrator/cancel/{idempotencyKey}`

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

Тарифікація

Довідник кодів помилок

Ліміти запитів (Rate Limits)

Перевищення ліміту запитів (429)

Примітки