POST /apiv2/reports/statement

Yêu cầu một tệp sao kê — toàn bộ các hoạt động của một token trong một khoảng thời gian, dưới dạng CSV hoặc PDF. Tệp được tạo trong nền: yêu cầu sẽ trả về mã đơn hàng ngay lập tức và tệp sẽ được tải xuống sau khi sẵn sàng.

Để xem nhanh cùng dữ liệu đó mà không cần chờ đợi, hãy sử dụng xem trước bản sao kê thay thế — nó phản hồi ngay lập tức nhưng giới hạn số lượng hoạt động trả về.

URL cơ sở của Endpoint

https://netts.io/apiv2/reports

Headers của yêu cầu

Tiêu đề	Bắt buộc	Mô tả
X-API-KEY	có	Khóa API từ bảng điều khiển
X-Real-IP	có	Một địa chỉ từ danh sách trắng của khóa
X-Idempotency-Key	không	Khóa của riêng bạn, 12–128 ký tự thuộc A-Z a-z 0-9 . _ : -

Đặt yêu cầu tạo tệp

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
  }
}

Trường	Bắt buộc	Ghi chú
client_request_id	có	Định danh của bạn. Duy nhất cho mỗi tài khoản
address	có	TRON base58, 34 ký tự
token_id	không	Mặc định là TRX; hợp đồng TRC20 hoặc ID TRC10
date_from, date_to	có	UTC, bao gồm cả hai đầu. Tối đa 366 ngày
format	không	Mặc định là csv. PDF bị giới hạn ở 5000 hoạt động

Sau đó chờ xử lý

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

Trường status chuyển đổi tuần tự qua queued → running → waiting_cypherarc → done. Hai trạng thái kết thúc khác là: error, kèm theo lý do trong error_code và error_message, và expired khi tệp đã quá hạn. Một bản sao kê ngắn thường sẵn sàng trong chưa đầy một phút; hãy xem bất kỳ trạng thái nào ngoài done là "tiếp tục chờ".

Khi trạng thái là done, download_url sẽ được điền — dưới dạng một đường dẫn, không phải URL đầy đủ — và tệp có thể được tải xuống:

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'

Tệp được gửi về dưới dạng nén gzip. Yêu cầu tạo tệp CSV sẽ tải xuống dưới dạng application/gzip với tên tệp .csv.gz trong Content-Disposition; hãy giải nén tệp trước khi phân tích cú pháp. Phản hồi trạng thái chứa artifact_sha256 và artifact_size cho tệp nén chính xác như khi được gửi, nhờ đó bạn có thể xác thực bản tải xuống mà không cần thêm yêu cầu thứ hai.

Thay vì gửi yêu cầu thăm dò liên tục, hãy đăng ký một webhook để nhận thông báo khi tệp đã sẵn sàng.

Việc gửi lại yêu cầu là an toàn

Gửi cùng một client_request_id, hoặc cùng một X-Idempotency-Key, bạn sẽ nhận lại đơn hàng hiện có thay vì tạo thêm đơn hàng thứ hai. Phản hồi sẽ chứa "msg": "existing" để bạn có thể phân biệt giữa hai trường hợp.

Việc tái sử dụng một định danh với phần thân khác biệt là một lỗi, không phải đơn hàng mới: trường hợp đó trả về mã 409. Các định danh chỉ là duy nhất trong phạm vi tài khoản của bạn — định danh của tài khoản khác sẽ không bao giờ trùng lặp với định danh của bạn.

Thời hạn lưu trữ tệp là 30 ngày

Sau thời gian đó, đơn hàng sẽ chuyển sang trạng thái expired và việc tải xuống sẽ trả về 410. Hãy yêu cầu lại nếu bạn cần sử dụng sau này.

Giới hạn tần suất

10 yêu cầu mỗi giây cho mỗi endpoint, chia sẻ chung giữa tất cả các máy khách. Vượt quá giới hạn này sẽ trả về mã 429 kèm theo Retry-After: 1 và thông báo Endpoint rate limit exceeded (10 req/s shared).

Đó là giới hạn duy nhất. Không có hạn ngạch hàng tháng, không có mức trần về số lượng tệp bạn có thể yêu cầu và không có giới hạn về số lượng tệp được tạo cùng một lúc — một tài khoản có số dư dương có thể yêu cầu nhiều tùy ý trong phạm vi cho phép của giới hạn tốc độ. Các đơn hàng vượt quá khả năng tiếp nhận của hàng đợi xử lý sẽ được giữ lại và tự động thử lại thay vì bị từ chối, do đó lưu lượng truy cập tăng đột biến chỉ khiến bạn mất độ trễ chứ không gây ra lỗi.

Lỗi

HTTP	Ý nghĩa
400	địa chỉ có 34 ký tự nhưng không vượt qua kiểm tra tổng kiểm (checksum) base58
401	khóa bị thiếu hoặc không hợp lệ, hoặc IP nguồn không nằm trong danh sách trắng
402	số dư tài khoản dưới mức tối thiểu 4 TRX
403	khóa API bị chặn; liên hệ hỗ trợ
409	cùng một định danh đã được sử dụng với phần thân khác — nội dung phản hồi là IDEMPOTENCY_CONFLICT
410	tệp đã hết hạn
422	một trường bị thiếu hoặc định dạng sai, hoặc khoảng thời gian vượt quá 366 ngày
429	vượt quá giới hạn tốc độ — thử lại sau khoảng thời gian Retry-After

Liên quan

• Số dư — đọc số dư và xem trước bản sao kê tức thì
• Báo cáo webhook — thông báo khi tệp sẵn sàng