POST /apiv2/reports/statement

สั่งสร้างไฟล์รายการเดินบัญชี (statement) — ทุกธุรกรรมของหนึ่งโทเคนในช่วงเวลาที่กำหนด ในรูปแบบ CSV หรือ PDF ไฟล์จะถูกสร้างขึ้นในเบื้องหลัง: คำขอจะส่งคืนหมายเลขคำสั่งซื้อทันที และสามารถดาวน์โหลดไฟล์ได้เมื่อสร้างเสร็จสมบูรณ์

สำหรับการดูข้อมูลเดียวกันอย่างรวดเร็วโดยไม่ต้องรอ ให้ใช้ statement preview แทน — ซึ่งจะตอบกลับทันทีแต่จำกัดจำนวนธุรกรรมที่ส่งคืน

Base URL ของ Endpoint

https://netts.io/apiv2/reports

Headers ของคำขอ

Header	จำเป็น	คำอธิบาย
X-API-KEY	ใช่	API key จากแดชบอร์ด
X-Real-IP	ใช่	ที่อยู่อิสระจากรายการที่อนุญาต (whitelist) ของคีย์
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 id
date_from, date_to	ใช่	UTC, รวมวันดังกล่าวด้วย สูงสุดไม่เกิน 366 วัน
format	ไม่	ค่าเริ่มต้นคือ csv สำหรับ PDF จะจำกัดไว้ที่ 5,000 ธุรกรรม

จากนั้นรอไฟล์สร้างเสร็จ

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 จะแสดงข้อมูล — ในรูปแบบ path ไม่ใช่ 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 สำหรับไฟล์บีบอัดตรงตามที่ส่งมอบ เพื่อให้คุณสามารถตรวจสอบความถูกต้องของไฟล์ที่ดาวน์โหลดได้โดยไม่ต้องส่งคำขอซ้ำอีกครั้ง

แทนที่จะใช้วิธีส่งคำขอตรวจสอบเป็นระยะ (polling) คุณสามารถ ลงทะเบียน webhook เพื่อรับการแจ้งเตือนเมื่อไฟล์พร้อมใช้งาน

การส่งคำขอซ้ำมีความปลอดภัย

การส่ง client_request_id เดิม หรือ X-Idempotency-Key เดิม จะทำให้คุณได้รับคำสั่งซื้อเดิมกลับมาแทนที่จะสร้างคำสั่งซื้อใหม่อีกรายการ การตอบกลับจะระบุ "msg": "existing" เพื่อให้คุณแยกความแตกต่างได้

การนำตัวระบุเดิมกลับมาใช้ใหม่โดยมีเนื้อหาคำขอ (body) ที่แตกต่างกันจะถือเป็นข้อผิดพลาด ไม่ใช่การสร้างคำสั่งซื้อใหม่: ซึ่งจะได้รับสถานะ 409 ตัวระบุจะไม่ซ้ำกันเฉพาะภายในบัญชีของคุณเท่านั้น — ตัวระบุของบัญชีอื่นจะไม่มีวันชนกับของคุณ

ไฟล์มีอายุ 30 วัน

หลังจากพ้นระยะเวลาดังกล่าว คำสั่งซื้อจะเปลี่ยนสถานะเป็น expired และการดาวน์โหลดจะได้รับสถานะ 410 หากคุณต้องการใช้ในภายหลัง กรุณาสั่งสร้างไฟล์ใหม่อีกครั้ง

ขีดจำกัดอัตราการเรียกใช้

10 คำขอต่อวินาที ต่อ endpoint ซึ่งแชร์ร่วมกันในหมู่ผู้ใช้งานทั้งหมด หากเกินขีดจำกัดจะได้รับสถานะ 429 พร้อม Retry-After: 1 และข้อความ Endpoint rate limit exceeded (10 req/s shared)

นี่คือข้อจำกัดเพียงอย่างเดียว ไม่มีการจำกัดโควตารายเดือน ไม่จำกัดจำนวนไฟล์ที่คุณสามารถสั่งสร้างได้ และไม่จำกัดจำนวนไฟล์ที่สร้างพร้อมกันในคราวเดียว — บัญชีที่มียอดคงเหลือเป็นบวกสามารถสั่งสร้างได้มากเท่าที่ rate limit อนุญาต คำสั่งซื้อที่เกินกว่าความจุของคิวการสร้างจะถูกพักไว้และลองใหม่อัตโนมัติแทนที่จะถูกปฏิเสธ ดังนั้นคำขอที่เข้ามาจำนวนมากพร้อมกัน (burst) จะส่งผลต่อความล่าช้าเท่านั้น แต่จะไม่เกิดความล้มเหลว

ข้อผิดพลาด

HTTP	ความหมาย
400	ที่อยู่มีความยาว 34 ตัวอักษร แต่ checksum ของ base58 ไม่ถูกต้อง
401	คีย์ขาดหายหรือไม่ถูกต้อง หรือ IP ต้นทางไม่อยู่ใน whitelist
402	ยอดคงเหลือในบัญชีต่ำกว่าขั้นต่ำ 4 TRX
403	API key ถูกระงับการใช้งาน โปรดติดต่อฝ่ายสนับสนุน
409	มีการใช้ตัวระบุเดิมกับเนื้อหาคำขอที่แตกต่างกัน — เนื้อหาคำขอคือ IDEMPOTENCY_CONFLICT
410	ไฟล์หมดอายุแล้ว
422	ฟิลด์ขาดหายหรือรูปแบบไม่ถูกต้อง หรือช่วงเวลาเกินกว่า 366 วัน
429	เกินขีดจำกัด rate limit — ให้ลองใหม่อีกครั้งหลังจากระยะเวลาใน Retry-After

หน้าที่เกี่ยวข้อง

• Balances — การดูยอดคงเหลือและพรีวิวรายการเดินบัญชีทันที
• Report webhooks — การแจ้งเตือนเมื่อไฟล์พร้อมใช้งาน