POST /apiv2/reports/statement

Замовити файл виписки — кожна операція одного токена за певний період у форматі CSV або PDF. Файл створюється у фоновому режимі: запит одразу повертає номер замовлення, а готовий файл можна отримати після завершення формування.

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

Базовий URL ендпоінта

https://netts.io/apiv2/reports

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

Заголовок	Обов'язковий	Опис
X-API-KEY	так	API-ключ з панелі керування
X-Real-IP	так	Адреса з білого списку ключа
X-Idempotency-Key	ні	Ваш власний ключ, 12–128 символів із A-Z a-z 0-9 . _ : -

Замовити файл

curl -s -X POST 'https://netts.io/apiv2/reports/statement' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Content-Type: application/json' \
  -d '{
        "client_request_id": "stmt-2026-09-usdt",
        "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "token_id": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "date_from": "2026-09-01",
        "date_to": "2026-09-30",
        "format": "csv"
      }'

{
  "status": "success",
  "code": 0,
  "msg": "created",
  "data": {
    "order_no": "REPxxxxxxxxxxxx",
    "client_request_id": "stmt-2026-09-usdt",
    "type": "statement",
    "status": "queued",
    "quota_bucket": "free",
    "progress_pct": 0,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "token_id": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "date_from": "2026-09-01",
    "date_to": "2026-09-30",
    "format": "csv",
    "created_at": "2026-09-06 17:01:51.868542+00:00",
    "finished_at": null,
    "expires_at": null,
    "artifact_sha256": null,
    "artifact_size": null,
    "download_url": null
  }
}

Поле	Обов'язкове	Примітки
client_request_id	так	Ваш ідентифікатор. Унікальний для кожного акаунта
address	так	TRON base58, 34 символи
token_id	ні	TRX за замовчуванням; контракт TRC20 або ідентифікатор TRC10
date_from, date_to	так	UTC, включно. Не більше ніж 366 днів
format	ні	csv за замовчуванням. PDF обмежено 5000 операціями

Потім очікуйте на нього

curl -s 'https://netts.io/apiv2/reports/REPxxxxxxxxxxxx' \
  -H 'X-API-KEY: your-api-key' -H 'X-Real-IP: 203.0.113.10'

Поле status проходить етапи queued → running → waiting_cypherarc → done. Ще два є кінцевими: error із причиною в error_code та error_message, а також expired, коли термін дії файлу сплив. Коротка виписка зазвичай готова значно менше ніж за хвилину; сприймайте будь-який статус, крім done, як сигнал «продовжуйте очікувати».

Щойно з'явиться статус done, заповниться поле download_url — як шлях, а не повний URL — і файл можна буде завантажити:

curl -s -OJ 'https://netts.io/apiv2/reports/REPxxxxxxxxxxxx/download' \
  -H 'X-API-KEY: your-api-key' -H 'X-Real-IP: 203.0.113.10'

Файл надходить стисненим у форматі gzip. Замовлення CSV завантажується як application/gzip з ім'ям файлу .csv.gz у Content-Disposition; розархівуйте його перед обробкою. Відповідь зі статусом містить artifact_sha256 і artifact_size саме для стисненого файлу в доставленому вигляді, тож ви можете перевірити завантаження без другого запиту.

Замість опитування зареєструйте вебхук, щоб отримати сповіщення, коли файл буде готовий.

Повторення запиту безпечне

Надішліть той самий client_request_id або той самий X-Idempotency-Key, і ви отримаєте наявне замовлення замість створення другого. Відповідь міститиме "msg": "existing", щоб ви могли їх розрізнити.

Повторне використання ідентифікатора з іншим тілом запиту є помилкою, а не новим замовленням: це призводить до помилки 409. Ідентифікатори є унікальними лише в межах вашого акаунта — ідентифікатори іншого акаунта ніколи не збігатимуться з вашими.

Файли зберігаються протягом 30 днів

Після цього замовлення набуває статусу expired, а спроба завантаження повертає 410. Замовте його повторно, якщо він знадобиться вам пізніше.

Ліміти запитів

10 запитів на секунду на ендпоінта, спільні для всіх клієнтів. Перевищення ліміту повертає 429 із заголовком Retry-After: 1 і повідомленням Endpoint rate limit exceeded (10 req/s shared).

Це єдине обмеження. Немає щомісячної квоти, немає обмежень на кількість файлів, які можна замовити, і немає обмежень на кількість файлів, що генеруються одночасно — акаунт із позитивним балансом може замовляти стільки, скільки дозволяє ліміт запитів. Замовлення, що перевищують місткість черги генерації, утримуються та повторюються автоматично, а не відхиляються, тому різкий сплеск навантаження впливає на затримку, а не призводить до збоїв.

Помилки

HTTP	Значення
400	адреса містить 34 символи, але не проходить перевірку контрольної суми base58
401	ключ відсутній або недійсний, або IP-адреси джерела немає в білому списку
402	баланс акаунта нижчий за мінімум у 4 TRX
403	API-ключ заблоковано; зверніться до служби підтримки
409	той самий ідентифікатор було використано з іншим тілом — тіло відповіді IDEMPOTENCY_CONFLICT
410	термін дії файлу сплив
422	поле відсутнє або некоректне, або період перевищує 366 днів
429	перевищено ліміт запитів — повторіть спробу після часу, вказаного в Retry-After

Пов'язані розділи

• Баланси — зчитування балансів і швидкий попередній перегляд виписки
• Вебхуки звітів — сповіщення про готовність файлу