POST /apiv2/order1h

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

اینڈ پوائنٹ URL

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

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

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

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

json

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

درخواست کے پیرامیٹرز

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

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

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

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

مثالیں

cURL

bash

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

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)

json

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

رسپانس فیلڈز

Field	Type	تفصیل
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	پول ایڈریس جس نے توانائی تفویض کی
detail.data.energy	integer	Energy کی مقدار + بفر (عام طور پر +50)

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

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

json

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

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

json

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

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

json

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

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

json

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

json

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

json

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

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

json

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

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

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

شرح کی حدود

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

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

ریٹ لمٹ ہیڈرز

http

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

ریٹ لمٹ سے تجاوز (429)

json

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

Idempotency

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

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

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

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

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

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

اپنی کی (Key) فراہم کرنا

آپ X-Idempotency-Key ہیڈر بھیج کر idempotency کو اپنے کنٹرول میں لے سکتے ہیں۔ جب یہ موجود ہو، تو صرف وہی ویلیو فیصلہ کرتی ہے کہ آیا کوئی درخواست دہرائی گئی ہے یا نہیں، اور اوپر دیا گیا خودکار امتزاج استعمال نہیں ہوتا ہے۔ جب یہ غیر موجود ہو، تو کچھ بھی تبدیل نہیں ہوتا — سرور آپ کے لیے کی اخذ کرتا ہے۔


Header	`X-Idempotency-Key`
فارمیٹ	بالکل 64 چھوٹے حروف پر مشتمل ہیکساڈیسیمل کریکٹرز — ایک SHA-256 ڈائجسٹ
لائف ٹائم	اس کی کو لے جانے والی پہلی درخواست سے 24 گھنٹے
دائرہ کار	آپ کا اکاؤنٹ۔ کسی دوسرے اکاؤنٹ کی طرف سے بھیجی گئی وہی ویلیو کبھی بھی آپ کا نتیجہ واپس نہیں کرتی

کسی بھی دوسری ساخت کی کی — ڈیشز کے ساتھ UUID، base64، بڑے حروف کا ہیکس — آرڈر کے عمل میں آنے اور کسی بھی چارج سے پہلے 400 کے ساتھ مسترد کر دی جاتی ہے:

json

{
    "detail": "Invalid idempotency key format. Must be 64-character hexadecimal string."
}

فارمیٹ دیگر اینڈ پوائنٹس سے مختلف ہے۔ /apiv2/withdraw، /apiv2/bandwidth اور آرکیسٹریٹر 16–64 کریکٹر کی base64 کی قبول کرتے ہیں۔ یہ اینڈ پوائنٹ صرف 64 کریکٹر پر مشتمل ہیکس ڈائجسٹ قبول کرتا ہے، لہذا ان اینڈ پوائنٹس سے کاپی کیا گیا کی بنانے والا کوڈ یہاں 400 واپس کرے گا۔

کی کی تشکیل کیسے کریں

اسے اپنی API کی سے اخذ کریں۔ یہ ویلیو کو آپ کے اکاؤنٹ کے لیے منفرد بناتا ہے، دوبارہ کوشش کرنے پر دوبارہ تیار کیا جا سکتا ہے، اور کسی دوسرے کے لیے اس تک پہنچنا ناممکن ہوتا ہے:

python

import hashlib
import hmac

def make_idempotency_key(api_key: str, address: str, amount: int, nonce: str) -> str:
    message = f"{address}:{amount}:{nonce}"
    return hmac.new(api_key.encode(), message.encode(), hashlib.sha256).hexdigest()

nonce آرڈر سے تعلق رکھتا ہے، درخواست سے نہیں۔ اسے ایک بار منتخب کریں، جب آپ کی طرف آرڈر بنتا ہے، اور اس آرڈر کے ہر بار بھیجنے پر وہی ویلیو پاس کریں — پہلی کوشش اور ہر دوبارہ کوشش دونوں میں یکساں۔ بھیجنے والے فنکشن کے اندر ایک نئی ویلیو بنانا (ہر کال پر str(uuid.uuid4())) ہر کوشش کو ایک مختلف کی دیتا ہے، لہذا ٹائم آؤٹ کے بعد دوبارہ کوشش کو دوسرے آرڈر کے طور پر قبول کیا جاتا ہے اور دوبارہ چارج کیا جاتا ہے۔ سب سے آسان درست انتخاب وہ آرڈر آئی ڈی ہے جو آپ کے پاس پہلے سے موجود ہے: یہ پہلی کوشش سے پہلے موجود ہوتی ہے اور آپ کے پروسیس کے دوبارہ شروع ہونے کے بعد بھی باقی رہتی ہے۔

python

# once, when the order appears in your system
order = create_order(address="TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", amount=131000)

# on the first attempt and on every retry — the same three inputs, the same key
key = make_idempotency_key(API_KEY, order.address, order.amount, order.id)

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": API_KEY,
    "X-Idempotency-Key": key,
}

ایک کی 24 گھنٹے تک فعال رہتی ہے۔ اس کے بعد وہی nonce دوبارہ خالی ہو جاتا ہے اور ایک نیا آرڈر شروع کرتا ہے۔

ایسی ویلیو استعمال نہ کریں جس تک کوئی دوسرا پہنچ سکے — 64 صفر، کسی مقررہ لفظ کا ڈائجسٹ۔ کیز اکاؤنٹس کے درمیان ایک ہی اسپیس کا اشتراک کرتی ہیں۔ اس طرح کا تصادم کبھی بھی کسی دوسرے اکاؤنٹ کے آرڈر کو ظاہر نہیں کرتا، لیکن آپ کی درخواست اس وقت تک 409 کے ساتھ مسترد کی جاتی ہے جب تک کہ ان کی کی کی میعاد ختم نہ ہو جائے، جو وہ جواب نہیں ہے جو آپ دوبارہ کوشش کے دوران چاہتے ہیں۔

دو ایک جیسے آرڈرز دینا

کبھی کبھی آپ واقعی ایک ہی آرڈر دو بار چاہتے ہیں — ایک ہی ایڈریس پر اتنی ہی مقدار میں توانائی، ایک کے بعد دوسرا۔ خودکار کی اسے دوبارہ کوشش سے الگ نہیں کر سکتی: دونوں درخواستیں بائٹ بہ بائٹ ایک جیسی ہوتی ہیں، اور واحد چیز جو انہیں الگ کرتی ہے وہ ان کی آمد کا وقت ہے۔

اپنی کی کے بغیر، نتیجہ ان کے درمیان وقفے پر منحصر ہوتا ہے:

دونوں درخواستوں کے درمیان وقفہ	کیا ہوتا ہے
اسی 1 سیکنڈ کی ونڈو کے اندر	دوسری درخواست کو دہرائی گئی درخواست سمجھا جاتا ہے۔ اس پر عمل نہیں کیا جاتا: آپ کو `208` اور پہلے آرڈر کا رسپانس ملتا ہے، جس میں `orderId` بھی شامل ہے۔ اس کے لیے کچھ بھی چارج نہیں کیا جاتا
ایک سیکنڈ سے زیادہ کا فاصلہ	دو مختلف کیز — دونوں آرڈرز دیے جاتے ہیں اور دونوں پر چارج لیا جاتا ہے

لہذا اگر آپ خودکار کی پر انحصار کرتے ہیں، تو دو ایک جیسے آرڈرز کے درمیان ایک سیکنڈ سے زیادہ کا وقت چھوڑیں، اور اسٹیٹس کوڈ پڑھیں: 208 کا مطلب ہے کہ جو آرڈر آپ نے ابھی بھیجا تھا وہ نہیں دیا گیا۔

وقفہ ایک عارضی حل ہے، کوئی مستقل حل نہیں۔ یہ ہر درخواست کو الگ کرتا ہے، بشمول وہ درخواستیں جنہیں آپ کبھی دہرانا نہیں چاہتے تھے — ٹائم آؤٹ کے بعد دوبارہ کوشش، ڈبل کلک، آپ کی قطار کی طرف سے دوبارہ بھیجا گیا پیغام۔ وہ بھی ونڈو کے بعد آتے ہیں، اس لیے انہیں الگ الگ آرڈرز کے طور پر درج کیا جاتا ہے اور الگ الگ چارج کیا جاتا ہے۔ اس اینڈ پوائنٹ کا رسپانس ٹائم آؤٹ 10 سیکنڈ ہے، جو پہلے ہی ونڈو سے بہت باہر ہے: خودکار کی ٹائم آؤٹ کے بعد کی جانے والی دوبارہ کوشش کی حفاظت نہیں کرتی۔

آپ کی اپنی کی اندازوں کو ختم کر دیتی ہے، کیونکہ فیصلہ واحد فریق کے پاس منتقل ہو جاتا ہے جو جواب جانتا ہے:

آپ کیا کر رہے ہیں	آپ کیا بھیجتے ہیں	نتیجہ
دوسرا، واقعی نیا آرڈر	ایک نیا `nonce`	ایک نئی کی — آرڈر درج کر دیا جاتا ہے
کسی ایسے آرڈر کی دوبارہ کوشش جس کے نتیجے کا آپ کو علم نہیں ہے	پہلی کوشش کا `nonce`	وہی کی — `208`، اصل رسپانس، کوئی دوسرا چارج نہیں

دوسری قطار ہیڈر کے وجود کی اصل وجہ ہے، اور یہیں سے عام طور پر عمل درآمد میں غلطی ہوتی ہے: کی کی تشکیل کیسے کریں کے تحت دیا گیا نوٹ دیکھیں۔

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

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

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

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

json

{
    "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)

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

json

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

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

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

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

پوسٹ پیڈ اکاؤنٹس

پوسٹ پیڈ بلنگ پر موجود اکاؤنٹس باقی تمام افراد کی طرح ایک ہی اینڈ پوائنٹ، URL، ہیڈرز اور ریکوئسٹ باڈی کا استعمال کرتے ہیں۔ فرق صرف یہ ہے کہ آرڈر کی ادائیگی کیسے کی جاتی ہے:

آپ کے ڈپازٹ سے کچھ بھی منہا نہیں کیا جاتا ہے۔ ہر کامیاب آرڈر آپ کے اکاؤنٹ کے واجب الادا بیلنس میں آپ کے معاہدے میں طے شدہ تصفیہ کی کرنسی میں شامل کیا جاتا ہے۔ آپ اپنے معاہدے کے مطابق انوائس کے ذریعے اس کی ادائیگی کرتے ہیں۔
آپ کے اکاؤنٹ کی ایک کریڈٹ لمٹ ہوتی ہے۔ جب تک واجب الادا رقم حد کے اندر ہے، زیرو ڈپازٹ کے ساتھ بھی آرڈرز قبول کیے جاتے ہیں۔
صرف فراہم کردہ سروسز کا بل بھیجا جاتا ہے۔ مسترد یا غیر عمل شدہ آرڈر کی کوئی قیمت نہیں ہوتی۔
اگر وصول کنندہ کے ایڈریس کو فعال کرنا ضروری ہے، تو ایکٹیویشن اسی آرڈر کا حصہ ہے اور اس کا بل علیحدہ چارج کے طور پر لیا جاتا ہے۔

پوسٹ پیڈ بلنگ کی درخواست پر Netts کی طرف سے کسی اکاؤنٹ کے لیے فعال کی جاتی ہے۔ ہر رسپانس آپ کو بتاتا ہے کہ آرڈر کی ادائیگی کیسے کی گئی ہے: paymentMode یا تو postpaid ہوتا ہے یا prepaid۔

اضافی درخواست فیلڈز

Parameter	Type	مطلوب ہے	تفصیل
test	boolean	نہیں	`true` — صرف قیمت کا حساب لگائیں۔ کچھ بھی آرڈر، ڈیلیور یا بل نہیں کیا جاتا
freezePrice	boolean	نہیں	`true` — 60 سیکنڈ کے لیے اپنے معاہدے کے تحت قیمت فکس کریں۔ کچھ بھی آرڈر یا بل نہیں کیا جاتا
quoteId	string	نہیں	`freezePrice` کی طرف سے جاری کردہ کوٹیشن کی قیمت پر آرڈر دیں
priceCurrency	string	نہیں	`TRX` (ڈیفالٹ) یا آپ کے معاہدے کی کرنسی، جیسا کہ `settlement.asset` میں ہے۔ پوسٹ پیڈ اکاؤنٹس کے لیے آپ کے معاہدے کی کرنسی میں رقوم ہمیشہ شامل ہوتی ہیں

quoteId کو test یا freezePrice کے ساتھ نہیں ملایا جا سکتا۔ ریکوئسٹ باڈی میں کسی بھی دوسرے فیلڈ کو مسترد کر دیا جاتا ہے۔

قیمت کی جانچ (`test: true`)

json

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "test": true
}

json

{
    "detail": {
        "code": 10010,
        "msg": "Test calculation",
        "data": {
            "amount": 65000,
            "unitPriceSun": "20",
            "discount": null,
            "energyTRX": "1.300000",
            "activationTRX": "1.100000",
            "wouldCostTRX": "2.400000",
            "paidTRX": 0,
            "paymentMode": "postpaid",
            "activationCheck": "inactive",
            "alt": {"USDC": {"energy": "0.430541", "activation": "0.364304", "total": "0.794845"}},
            "fxAt": "2026-10-19T07:15:18.469870+00:00"
        }
    }
}

Field	تفصیل
unitPriceSun	SUN میں فی یونٹ توانائی کی قیمت، بشمول آپ کی ذاتی رعایت اگر آپ کے پاس ہے
discount	آپ کی ذاتی رعایت (`type`، `value`) یا `null`
energyTRX / activationTRX / wouldCostTRX	Energy، ایکٹیویشن (اگر ایڈریس کو اس کی ضرورت ہے) اور کل، TRX میں
activationCheck	`inactive` — ایڈریس فعال کیا جائے گا اور بل بھیجا جائے گا؛ `active` — کوئی ایکٹیویشن نہیں؛ `unknown` — اس وقت جانچ نہیں کی جا سکی
`alt.<currency>`	آپ کے معاہدے کی کرنسی میں وہی رقوم
fxAt	آپ کے معاہدے کی کرنسی میں رقوم کے لیے استعمال ہونے والی شرح تبادلہ کا وقت

فکسڈ پرائس کوٹیشن (`freezePrice: true`)

آرڈر کرنے سے پہلے اپنے معاہدے کے تحت قیمت فکس کرنے کے لیے کوٹیشن کا استعمال کریں۔

"freezePrice": true کے ساتھ آرڈر بھیجیں۔ رسپانس کا کوڈ 10011 (Quote issued) ہوتا ہے، جس میں قیمت کی جانچ جیسے ہی فیلڈز ہوتے ہیں، نیز quoteId اور expiresAt۔
60 سیکنڈ کے اندر "quoteId": "<quoteId>" اور اسی amount اور receiveAddress کے ساتھ آرڈر بھیجیں۔
آرڈر کا بل کوٹ کردہ قیمت پر وصول کیا جاتا ہے — کوٹیشن کے وقت آپ کے معاہدے کے تحت قیمت — چاہے اس دوران قیمت بدل بھی جائے۔

ایک کوٹیشن ایک بار اور صرف اسی پروڈکٹ کے لیے استعمال کی جا سکتی ہے: 1 گھنٹے کی کوٹیشن 5 منٹ کے آرڈر کی ادائیگی نہیں کر سکتی۔ ختم شدہ یا پہلے سے استعمال شدہ کوٹیشن مسترد کر دی جاتی ہے اور کچھ بھی آرڈر نہیں کیا جاتا ہے۔

json

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "quoteId": "q_4f540f16a2c94b7f8e3d1a6b5c0e9d72"
}

کامیاب آرڈر

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.30 TRX for energy + 1.10 TRX for address activation, postpaid",
        "data": {
            "orderId": "1Hf9544a1508",
            "paidTRX": 2.4,
            "hash": "032bda8fa6911b42c15a6d8d30520dc22bcc4077972a1503b6a3fae491967eb4",
            "delegateAddress": "TVnkj2jHKgmea8DVJFo2teD7rRSpH51bne",
            "energy": 65000,
            "activationHash": "259e1ab276114ae717a6f62d7d25eb1f89a2dccb637cbe41be626df3c2a78519",
            "paymentMode": "postpaid",
            "energyTRX": "1.300000",
            "activationTRX": "1.100000",
            "totalTRX": "2.400000"
        }
    }
}

Field	تفصیل
paidTRX	TRX میں سروس کی لاگت۔ پوسٹ پیڈ اکاؤنٹس کے لیے یہ ڈپازٹ سے منہا نہیں کی جاتی ہے
paymentMode	`postpaid`
energyTRX / activationTRX / totalTRX	درست رقوم، 6 اعشاریائی مقامات
quoteId, alt	موجود ہوتے ہیں جب آرڈر کوٹیشن کے ساتھ دیا گیا تھا: کوٹیشن ID اور کوٹ کردہ رقوم
activationFinal	موجود اور `false` صرف اس وقت ہوتا ہے جب ایکٹیویشن کی رقم ابتدائی ہو؛ حتمی رقم آپ کی انوائس پر ظاہر ہوتی ہے

دیگر تمام فیلڈز پری پیڈ آرڈرز جیسے ہی ہیں۔

کریڈٹ کی حد ختم ہو گئی (402)

json

{
    "detail": {
        "code": 1004,
        "msg": "Postpaid credit limit reached.",
        "paymentMode": "postpaid",
        "reason": "limit_reached"
    }
}

آرڈر پر عمل نہیں کیا جاتا اور کچھ بھی بل نہیں کیا جاتا۔ آپ کی ادائیگی رجسٹر ہونے یا آپ کی حد میں اضافہ ہونے کے بعد نئے آرڈرز دوبارہ قبول کیے جاتے ہیں۔

پوسٹ پیڈ خرابی کے کوڈز

Code	HTTP	تفصیل
`10010`	200	قیمت کی جانچ کا نتیجہ (`test`)
`10011`	200	کوٹیشن جاری کر دی گئی (`freezePrice`)
`1004`	402	پوسٹ پیڈ کریڈٹ کی حد ختم ہو گئی
`4100`	400	باطل درخواست
`4101`	400	غیر تعاون یافتہ `priceCurrency`
`4102`	400	`quoteId` کو `test` یا `freezePrice` کے ساتھ ملایا گیا ہے
`4103`	409	کوٹیشن پہلے ہی استعمال ہو چکی ہے
`4104`	409	کوٹیشن کی میعاد ختم ہو گئی ہے
`4105`	409	مختلف درخواست کے لیے Idempotency کی پہلے ہی استعمال ہو چکی ہے
`4106`	404	کوٹیشن نہیں ملی
`4107`	409	آرڈر کے پیرامیٹرز کوٹیشن سے مختلف ہیں
`4108`	400	باطل `quoteId` فارمیٹ
`4109`	422	ذیلی اکاؤنٹس کے لیے دستیاب نہیں ہے
`5032`	503	قیمت عارضی طور پر دستیاب نہیں ہے
`5033`	503	شرح تبادلہ عارضی طور پر دستیاب نہیں ہے
`5034`	503	بلنگ عارضی طور پر دستیاب نہیں ہے — آرڈر قبول نہیں کیا گیا تھا
`5036`	503	کریڈٹ کی جانچ عارضی طور پر دستیاب نہیں ہے — بعد میں دوبارہ کوشش کریں

اوپر دیے گئے تمام 4xx اور 503 جوابات کے لیے کچھ بھی آرڈر نہیں کیا جاتا اور کچھ بھی بل نہیں کیا جاتا۔

نوٹس

کامیاب آرڈر پر 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}
قیمت کا تعین: دن کے وقت اور توانائی کی مقدار کی بنیاد پر متحرک
دورانیہ: مقررہ 1 گھنٹہ (3600 سیکنڈ)
ریٹ لمٹنگ: 50 درخواستیں فی سیکنڈ فی IP ایڈریس

POST /apiv2/order1h ​

اینڈ پوائنٹ URL ​

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

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

درخواست کے پیرامیٹرز ​

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

مثالیں ​

cURL ​

Python ​

جواب ​

کامیاب رسپانس (200 OK) ​

رسپانس فیلڈز ​

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

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

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

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

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

اندرونی سرور کی خرابی (500) ​

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

شرح کی حدود ​

ریٹ لمٹ ہیڈرز ​

ریٹ لمٹ سے تجاوز (429) ​

Idempotency ​

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

اپنی کی (Key) فراہم کرنا ​

کی کی تشکیل کیسے کریں ​

دو ایک جیسے آرڈرز دینا ​

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

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

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

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

پوسٹ پیڈ اکاؤنٹس ​

اضافی درخواست فیلڈز ​

قیمت کی جانچ (test: true) ​

فکسڈ پرائس کوٹیشن (freezePrice: true) ​

کامیاب آرڈر ​

کریڈٹ کی حد ختم ہو گئی (402) ​

پوسٹ پیڈ خرابی کے کوڈز ​

نوٹس ​

POST /apiv2/order1h

اینڈ پوائنٹ URL

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

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

درخواست کے پیرامیٹرز

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

مثالیں

cURL

Python

جواب

کامیاب رسپانس (200 OK)

رسپانس فیلڈز

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

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

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

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

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

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

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

شرح کی حدود

ریٹ لمٹ ہیڈرز

ریٹ لمٹ سے تجاوز (429)

Idempotency

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

اپنی کی (Key) فراہم کرنا

کی کی تشکیل کیسے کریں

دو ایک جیسے آرڈرز دینا

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

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

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

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

پوسٹ پیڈ اکاؤنٹس

اضافی درخواست فیلڈز

قیمت کی جانچ (`test: true`)

فکسڈ پرائس کوٹیشن (`freezePrice: true`)

کامیاب آرڈر

کریڈٹ کی حد ختم ہو گئی (402)

پوسٹ پیڈ خرابی کے کوڈز

نوٹس