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

Связанные разделы

• Балансы — чтение балансов и мгновенный предпросмотр выписки
• Вебхуки отчетов — уведомление о готовности файла