POST /apiv2/order1h

خودکار فیل اوور (failover) کے ساتھ متعدد energy فراہم کنندگان کے ذریعے 1 گھنٹے کا energy رینٹل آرڈر بنائیں۔

اینڈپوائنٹ URL

POST https://netts.io/apiv2/order1h

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

ہیڈر	لازمی	تفصیل
Content-Type	ہاں	application/json
X-API-KEY	ہاں	آپ کی API کلید Netts ڈیش بورڈ سے
X-Real-IP	ہاں	آپ کی وائٹ لسٹ سے IP پتہ

درخواست کا باڈی

{
    "amount": 131000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

پیرامیٹرز

پیرامیٹر	قسم	لازمی	تفصیل
amount	integer	ہاں	کرائے پر لینے کے لیے Energy کی مقدار (کم از کم: 61000، زیادہ سے زیادہ: 3000000)
receiveAddress	string	ہاں	TRON پتہ جو energy وصول کرے گا (TRC-20 فارمیٹ)

فراہم کنندہ کا انتخاب

API خودکار طور پر مندرجہ ذیل کی بنیاد پر بہترین energy فراہم کنندہ کا انتخاب کرتی ہے:

• قیمت کی بچت - ہمیشہ سب سے کم دستیاب قیمت تلاش کرتا ہے
• دستیابی - کافی energy کے ذخائر کو یقینی بناتا ہے
• قابل اعتمادی - اعلیٰ کامیابی کی شرح والے فراہم کنندگان کا استعمال کرتا ہے
• رفتار - تیز ترین ترسیل کے اوقات کو ترجیح دیتا ہے

نمونہ درخواستیں

cURL

curl -X POST https://netts.io/apiv2/order1h \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{
    "amount": 131000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

Python

import requests

url = "https://netts.io/apiv2/order1h"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key",
    "X-Real-IP": "your_whitelisted_ip"
}

payload = {
    "amount": 131000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if response.status_code == 200:
    detail = data.get('detail', {})
    order_data = detail.get('data', {})
    print(f"Order ID: {order_data.get('orderId')}")
    print(f"Transaction Hash: {order_data.get('hash')}")
    print(f"Energy Delivered: {order_data.get('energy')}")
    print(f"Cost: {order_data.get('paidTRX')} TRX")
    print(f"Delegate Address: {order_data.get('delegateAddress')}")
else:
    error_detail = data.get('detail', data)
    print(f"Error Code: {error_detail.get('code', 'N/A')}")
    print(f"Error Message: {error_detail.get('msg', error_detail)}")

جواب

کامیاب جواب (200 OK)

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 2.23 TRX deducted",
        "data": {
            "orderId": "1H123456",
            "paidTRX": 2.23,
            "hash": "a1b2c3d4e5f6789...",
            "delegateAddress": "TDelegatePoolAddress...",
            "energy": 131050
        }
    }
}

جواب کے فیلڈز

فیلڈ	قسم	تفصیل
detail.code	integer	کامیاب آرڈرز کے لیے ہمیشہ 10000
detail.msg	string	کٹوتی شدہ رقم کے ساتھ کامیابی کا پیغام
detail.data.orderId	string	یکساں آرڈر ID (فارمیٹ: 1H{request_id})
detail.data.paidTRX	number	TRX میں کل لاگت (اگر پتہ فعال نہیں تھا تو ایکٹیویشن فیس شامل ہے)
detail.data.hash	string | null	ٹرانزیکشن ہیش۔ فیلڈ ہمیشہ موجود ہوتی ہے لیکن خالی ہو سکتی ہے - کچھ فراہم کنندگان فوری طور پر ہیش واپس نہیں کرتے۔ ہیش حاصل کرنے کے لیے 1 منٹ کے بعد /apiv2/order_check کا استعمال کریں
detail.data.delegateAddress	string	پول کا پتہ جس نے energy ڈیلیگیٹ کی
detail.data.energy	integer	Energy کی مقدار + بفر (عام طور پر +50)

خرابی کے جوابات

تصدیقی خرابی (401)

{
    "detail": "Invalid API key or IP not in whitelist"
}

ناکافی بیلنس (403)

{
    "code": 1004,
    "msg": "Insufficient funds. Required: 2.23 TRX, Available: 1.50 TRX"
}

سروس دستیاب نہیں ہے (503)

{
    "code": 5003,
    "msg": "Service temporarily unavailable. All energy providers are currently unavailable."
}

فراہم کنندہ کی خرابیاں (503)

{
    "code": 5001,
    "msg": "Energy provider temporarily unavailable"
}

{
    "code": 5002,
    "msg": "Energy provider temporarily unavailable"
}

{
    "code": 5004,
    "msg": "Energy provider requires higher minimum amount"
}

انٹرنل سرور کی خرابی (500)

{
    "code": 5000,
    "msg": "Internal server error occurred"
}

خرابی کے کوڈز کا حوالہ

کوڈ	تفصیل	HTTP اسٹیٹس
10000	کامیابی	200
10000	کامیابی (کیش شدہ جواب)	208
-	ڈپلیکیٹ درخواست پر اب بھی عمل ہو رہا ہے	409
1004	ناکافی بیلنس	403
5000	انٹرنل سرور کی خرابی	500
5001	Energy فراہم کنندہ دستیاب نہیں ہے	503
5002	Energy فراہم کنندہ دستیاب نہیں ہے	503
5003	Energy سروس دستیاب نہیں ہے	503
5004	Energy فراہم کنندہ کی کم از کم حد پوری نہیں ہوئی	503

شرح کی حدیں (Rate Limits)

مندرجہ ذیل شرح کی حدیں اس اینڈپوائنٹ پر لاگو ہوتی ہیں (فی IP پتہ):

مدت	حد	تفصیل
1 سیکنڈ	50 درخواستیں	زیادہ سے زیادہ 50 درخواستیں فی سیکنڈ

شرح کی حد کے ہیڈرز

RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 49

شرح کی حد سے تجاوز (429)

{
    "message": "API rate limit exceeded"
}

خود مطابقت (Idempotency)

API ڈپلیکیٹ آرڈر پروسیسنگ کو روکنے کے لیے idempotency کی حمایت کرتی ہے۔ جب آپ متعدد ایک جیسی درخواستیں بھیجتے ہیں، تو سسٹم اس بات کو یقینی بناتا ہے کہ آرڈر پر صرف ایک بار عمل کیا جائے۔

Idempotency کیسے کام کرتی ہے

درخواست کی انفرادیت کا تعین مندرجہ ذیل کے مجموعے سے کیا جاتا ہے:

• درخواست کا ٹائم اسٹیمپ (1-سیکنڈ کی ونڈو)
• Energy کی مقدار
• وصول کنندہ کا پتہ
• API کلید

ہر درخواست کو 1-سیکنڈ کی انفرادیت کی ونڈو دی جاتی ہے۔ سسٹم کو غلط استعمال سے بچانے اور مناسب پروسیسنگ کو یقینی بنانے کے لیے، ایک جیسے پیرامیٹرز والی درخواستیں فی سیکنڈ ایک بار سے زیادہ کثرت سے نہیں بھیجی جا سکتیں۔

موجودہ رویہ: سسٹم خودکار طور پر کلائنٹس کو پہلے سے آرڈر شدہ energy پر غلط دوبارہ کوششوں سے بچاتا ہے۔ اگر آپ غلطی سے ایک ہی درخواست دو بار بھیج دیتے ہیں، تو آپ سے دو بار چارج نہیں لیا جائے گا۔

جلد آرہا ہے: درخواست میں ایک اختیاری idempotency_key پیرامیٹر شامل کیا جائے گا۔ فراہم کیے جانے پر، سسٹم خودکار طریقے سے تیار کردہ پیرامیٹرز کے بجائے درخواست کی انفرادیت کا تعین کرنے کے لیے اس کلید کا استعمال کرے گا۔ اس سے کلائنٹس کو idempotency پر مکمل کنٹرول ملتا ہے، کیونکہ صرف کلائنٹ ہی جانتا ہے کہ درخواست واقعی منفرد ہے یا دوبارہ کی گئی کوشش۔

ڈپلیکیٹ درخواستوں کے لیے HTTP اسٹیٹس کوڈز

اسٹیٹس کوڈ	نام	تفصیل
200	ٹھیک ہے (OK)	آرڈر کامیابی کے ساتھ پروسیس ہو گیا (پہلی درخواست)
208	پہلے ہی رپورٹ شدہ (Already Reported)	آرڈر پہلے ہی پروسیس ہو چکا تھا، کیش شدہ جواب واپس کیا جا رہا ہے
409	تنازع (Conflict)	درخواست پر فی الحال عمل ہو رہا ہے، دوبارہ کوشش نہ کریں

ڈپلیکیٹ درخواست - پہلے ہی عمل درآمد ہو چکا ہے (208)

جب پہلے سے مکمل شدہ آرڈر کے لیے ڈپلیکیٹ درخواست موصول ہوتی ہے:

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 2.54 TRX deducted",
        "data": {
            "hash": "9e4c20e21e01e4c39b21b670d1ea1fc1e4b0de94d8fbd4c190d5378ba911dfae",
            "energy": 65050,
            "orderId": "1H70bcc7962a",
            "paidTRX": 2.535,
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq"
        }
    },
    "idempotency": {
        "status": "completed",
        "cached": true,
        "original_created_at": "2025-12-03T10:34:49.104896"
    }
}

جواب کا باڈی اصل کامیاب جواب کے بالکل یکساں ہوتا ہے، جس میں ایک اضافی idempotency آبجیکٹ ہوتا ہے جو ظاہر کرتا ہے کہ یہ ایک کیش شدہ جواب ہے۔

ڈپلیکیٹ درخواست - ابھی تک پروسیسنگ جاری ہے (409)

جب اصل درخواست پر ابھی عمل جاری ہو اور اسی دوران ڈپلیکیٹ درخواست موصول ہو:

{
    "success": false,
    "error": "duplicate_request_processing",
    "message": "This request is currently being processed. Please wait and do not retry.",
    "idempotency_key": "b9e67b2412d33c92...",
    "retry_after_seconds": 3
}

سفارش: آرڈر کی حیثیت چیک کرنے سے پہلے مخصوص کردہ retry_after_seconds تک انتظار کریں۔

بہترین طریقہ کار

• ایک جیسے پیرامیٹرز کے ساتھ متوازی درخواستیں نہ بھیجیں - ہر جواب کا انتظار کریں
• مختلف آرڈرز کے لیے منفرد idempotency کلیدیں استعمال کریں
• فوری طور پر دوبارہ کوشش کرنے کے بجائے انتظار کر کے 409 جوابات کو ہینڈل کریں
• کیش شدہ جوابات کی شناخت کے لیے idempotency.cached فیلڈ کو چیک کریں

نوٹس

• کامیاب آرڈر پر Energy فوری طور پر فراہم کی جاتی ہے (عام طور پر 0.5-10 سیکنڈ کے اندر)
• API جواب کا ٹائم آؤٹ: زیادہ سے زیادہ 10 سیکنڈ، عام طور پر 2 سیکنڈ تک جواب دیتا ہے
• پتہ کی ایکٹیویشن: اگر وصول کنندہ کا پتہ فعال نہیں ہے، تو Netts اسے لاگت کی قیمت پر فعال کرتا ہے
• ایکٹیویشن میں تاخیر: غیر فعال پتوں کے لیے، ایکٹیویشن کے عمل کی وجہ سے API کے جواب میں 6 سیکنڈ تک کا وقت لگ سکتا ہے
• آرڈرز پر خودکار فراہم کنندہ کے فیل اوور کے ساتھ 24/7 عمل کیا جاتا ہے
• Energy کی کم از کم مقدار: 61,000 یونٹس
• Energy کی زیادہ سے زیادہ مقدار: 3,000,000 یونٹس فی آرڈر
• Energy بفر: فراہم کنندہ کے معاوضے کے لیے خودکار طور پر +50 یونٹس شامل کیے جاتے ہیں (مفت)
• ٹرانزیکشن ہیش: فیلڈ ہمیشہ موجود ہوتی ہے لیکن خالی ہو سکتی ہے اگر فراہم کنندہ اسے فوری طور پر واپس نہ کرے۔ ہیش حاصل کرنے کے لیے، آرڈر دینے کے بعد 1 منٹ سے پہلے /apiv2/order_check کو کال نہ کریں
• فراہم کنندہ کا انتخاب: لاگت اور دستیابی کی بنیاد پر خودکار
• آرڈر ID کا فارمیٹ: یکساں ٹریکنگ کے لیے 1H{request_id}
• قیمت کا تعین: دن کے وقت اور energy کی مقدار کی بنیاد پر متحرک (dynamic)
• مدت: مقررہ 1 گھنٹہ (3600 سیکنڈ)
• شرح کی حد بندی: 50 درخواستیں فی سیکنڈ فی IP پتہ