POST /apiv2/reports/statement

ایک اسٹیٹمنٹ فائل کا آرڈر دیں — کسی مخصوص مدت کے دوران ایک ٹوکن کا ہر آپریشن، بطور CSV یا PDF۔ فائل پس منظر میں تیار کی جاتی ہے: درخواست فوری طور پر ایک آرڈر نمبر واپس کرتی ہے، اور فائل تیار ہو جانے پر اسے حاصل کیا جاتا ہے۔

انتظار کیے بغیر اسی ڈیٹا کے فوری جائزے کے لیے، اس کے بجائے اسٹیٹمنٹ پیش نظارہ استعمال کریں — یہ فوری جواب دیتا ہے لیکن واپس کیے جانے والے آپریشنز کی تعداد کو محدود کرتا ہے۔

اینڈپوائنٹ بنیادی URL

https://netts.io/apiv2/reports

درخواست کے ہیڈرز

ہیڈر	لازمی	تفصیل
X-API-KEY	ہاں	ڈیش بورڈ سے حاصل کردہ API کی
X-Real-IP	ہاں	کی وائٹ لسٹ سے ایک پتہ
X-Idempotency-Key	نہیں	آپ کی اپنی کی، A-Z a-z 0-9 . _ : - کے 12–128 حروف پر مشتمل

فائل کا آرڈر دیں

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'

فائل gzipped صورت میں آتی ہے۔ CSV آرڈر Content-Disposition میں .csv.gz فائل کے نام کے ساتھ بطور application/gzip ڈاؤن لوڈ ہوتا ہے؛ تجزیہ (parse) کرنے سے پہلے اسے decompress کریں۔ اسٹیٹس کا جواب کمپریس شدہ فائل کے لیے ٹھیک ویسے ہی artifact_sha256 اور artifact_size فراہم کرتا ہے جیسے وہ موصول ہوئی ہے، تاکہ آپ دوسری درخواست کیے بغیر ڈاؤن لوڈ کی تصدیق کر سکیں۔

بار بار پولنگ کرنے کے بجائے، ایک ویب ہک رجسٹر کریں اور فائل تیار ہونے پر اطلاع حاصل کریں۔

درخواست کو دہرانا محفوظ ہے

وہی client_request_id، یا وہی X-Idempotency-Key بھیجیں، اور آپ کو دوسرا آرڈر تیار ہونے کے بجائے موجودہ آرڈر واپس مل جائے گا۔ جواب میں "msg": "existing" شامل ہوتا ہے تاکہ آپ دونوں میں فرق کر سکیں۔

ایک شناختی نام کو مختلف باڈی کے ساتھ دوبارہ استعمال کرنا نقص کی علامت ہے، نیا آرڈر نہیں: یہ 409 فراہم کرتا ہے۔ شناخت کنندگان صرف آپ کے اکاؤنٹ کی حد تک منفرد ہیں — کسی دوسرے اکاؤنٹ کے شناخت کنندگان کبھی بھی آپ کے ساتھ متصادم نہیں ہوتے۔

فائلیں 30 دنوں تک فعال رہتی ہیں

اس مدت کے بعد آرڈر expired ہو جاتا ہے اور ڈاؤن لوڈ کرنے پر 410 ملتا ہے۔ اگر آپ کو بعد میں اس کی ضرورت ہو تو اسے دوبارہ آرڈر کریں۔

شرح کی حدیں

10 درخواستیں فی سیکنڈ فی اینڈپوائنٹ، تمام کلائنٹس میں مشترکہ۔ اس سے تجاوز کرنے پر Retry-After: 1 کے ساتھ 429 اور Endpoint rate limit exceeded (10 req/s shared) کا پیغام ملتا ہے۔

یہی واحد حد ہے۔ کوئی ماہانہ کوٹہ نہیں، اس بات کی کوئی حد نہیں کہ آپ کتنی فائلوں کا آرڈر دے سکتے ہیں، اور ایک وقت میں کتنی فائلیں بن سکتی ہیں اس پر کوئی پابندی نہیں — مثبت بیلنس والا اکاؤنٹ ریٹ لمٹ کی اجازت کے مطابق آرڈر دے سکتا ہے۔ تعمیری قطار (build queue) کی گنجائش سے زائد آرڈرز مسترد ہونے کے بجائے روک لیے جاتے ہیں اور خودکار طور پر دوبارہ کوشش کی جاتی ہے، لہٰذا زیادہ دباؤ کی صورت میں ناکامی کے بجائے صرف تاخیر ہو سکتی ہے۔

نقائص

HTTP	مفہوم
400	پتہ 34 حروف کا ہے لیکن اس کی base58 تصدیق ناکام ہو جاتی ہے
401	کی غائب یا غلط ہے، یا سورس IP وائٹ لسٹ میں شامل نہیں ہے
402	اکاؤنٹ کا بیلنس کم از کم 4 TRX کی حد سے کم ہے
403	API کی مسدود ہے؛ معاونت سے رابطہ کریں
409	وہی شناخت کنندہ ایک مختلف باڈی کے ساتھ استعمال ہوا — باڈی IDEMPOTENCY_CONFLICT ہے
410	فائل کی میعاد ختم ہو چکی ہے
422	کوئی فیلڈ غائب یا خراب ہے، یا مدت 366 دنوں سے زیادہ ہے
429	شرح کی حد سے تجاوز — Retry-After کے بعد دوبارہ کوشش کریں

متعلقہ

• بیلنسز — بیلنسز دیکھنا اور فوری اسٹیٹمنٹ کا پیش نظارہ
• رپورٹ ویب ہکس — فائل تیار ہونے پر اطلاع