Orchestrator — ایک ہی کال میں بیچ آرڈرز

ایک ہی درخواست میں 100 تک پتے بھیجیں اور Netts کو ہر ایک کے لیے مکمل تسلسل خود انجام دینے دیں: ضرورت پڑنے پر ایڈریس کو فعال (activate) کرنا، بینڈوڈتھ کم ہونے پر اس میں اضافہ کرنا، اور پھر انرجی کرایہ پر دینا — بڑی مقداروں کو خودکار طور پر ٹکڑوں (chunks) میں تقسیم کرتے ہوئے۔

آپ کو ٹریکنگ کی کے ساتھ فوری طور پر 202 Accepted ملتا ہے اور کبھی بھی کنکشن پر انتظار نہیں کرنا پڑتا۔ اس کے بعد اسٹیٹس اینڈ پوائنٹ سے پیش رفت معلوم کی جا سکتی ہے۔

اسے کیوں استعمال کریں

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

probe → activation (if the address is not active) → bandwidth (if free < 400) → energy

ایکٹیویشن یا بینڈوڈتھ میں ناکامی اس ایڈریس کے لیے انرجی کے آرڈر کو نہیں روکتی، اور کسی ایک ایڈریس کی ناکامی دوسرے پتوں پر کبھی اثر انداز نہیں ہوتی۔

اینڈ پوائنٹ کا بنیادی یو آر ایل

https://netts.io/apiv2/orchestrator

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

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

* یا تو X-Idempotency-Key ہیڈر یا پھر باڈی میں clientRequestId فیلڈ کا ہونا لازمی ہے۔ اگر آپ دونوں میں سے کوئی بھی نہیں بھیجتے ہیں، تو درخواست 5010 کے ساتھ مسترد کر دی جاتی ہے۔

یہ کی پورے آرڈر کی شناخت کرتی ہے۔ اسی کی کے ساتھ درخواست دہرانے پر دوسرا آرڈر بنانے کے بجائے اصل نتیجہ واپس ملتا ہے — دیکھیے Idempotency۔

---

آرڈر بنائیں — POST /apiv2/orchestrator

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

{
    "clientRequestId": "my-batch-2026-01-01-001",
    "defaults": {
        "bandwidth": true,
        "bandwidthAmount": 400,
        "bandwidthPeriod": "1h",
        "check": true,
        "trx_send": false
    },
    "items": [
        { "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", "amount": 65000 },
        { "receiveAddress": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "amount": 131000 },
        { "receiveAddress": "TYYyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy", "amount": 61000, "bandwidth": false }
    ]
}

اولین سطح کی فیلڈز

فیلڈ	قسم	لازمی	تفصیل
items	array	ہاں	1 سے 100 پتے۔ ایک ہی آرڈر کے اندر ڈپلیکیٹس مسترد کر دیے جاتے ہیں۔
clientRequestId	string	نہیں	آپ کا آرڈر ریفرنس، 8–128 حروف پر مشتمل A-Z a-z 0-9 . _ : -۔ ہیڈر نہ ہونے کی صورت میں idempotency کی کے طور پر بھی کام کرتا ہے۔
defaults	object	نہیں	ایسی اقدار جو ہر اس آئٹم پر لاگو ہوتی ہیں جو انہیں اوور رائیڈ نہیں کرتا۔

آئٹم کی فیلڈز

receiveAddress اور amount کے علاوہ ہر فیلڈ کو defaults میں بھی سیٹ کیا جا سکتا ہے۔ آئٹم پر موجود قدر ڈیفالٹ پر فوقیت رکھتی ہے۔

فیلڈ	قسم	ڈیفالٹ	تفصیل
receiveAddress	string	—	انرجی وصول کرنے والا TRON ایڈریس
amount	int	—	اس ایڈریس کے لیے Energy، 61 000 … 50 000 000
bandwidth	bool	true	کم ہونے پر اس ایڈریس کے لیے بینڈوڈتھ کا آرڈر دیں
bandwidthAmount	int	400	400 یا 5000
bandwidthPeriod	string	1h	5m یا 1h
check	bool	نیچے دیکھیں	پہلے مفت بینڈوڈتھ چیک کریں اور اگر کافی ہو تو آرڈر چھوڑ دیں
trx_send	bool	false	بینڈوڈتھ سروس کو بغیر کسی تبدیلی کے منتقل کیا گیا
activation	bool	true	اگر ایڈریس فعال نہیں ہے تو اسے فعال کریں۔ اس ایڈریس کے لیے مرحلہ چھوڑنے کے لیے false سیٹ کریں جس کے بارے میں آپ جانتے ہیں کہ وہ پہلے سے فعال ہے۔

check ڈیفالٹ طور پر true ہوتا ہے جب bandwidthAmount کی قدر 400 ہو، بصورت دیگر false ہوتا ہے — عام طور پر 5 000 یونٹس کا آرڈر دینے کا مطلب یہ ہوتا ہے کہ آپ انہیں ہر حال میں چاہتے ہیں قطع نظر اس کے کہ وہاں پہلے سے کیا موجود ہے۔

مقداریں فی ایڈریس ہیں۔ ایک ہی درخواست میں مختلف مقداروں کو آزادانہ طور پر ملایا جا سکتا ہے؛ واحد حد کل رقم کی ہے۔

حدود

حد	قدر
پتے فی آرڈر	100
انرجی فی ایڈریس	61 000 … 50 000 000
کل انرجی فی آرڈر	50 000 000
زیرِ عمل آرڈرز فی اکاؤنٹ	3
زیرِ عمل پتے فی اکاؤنٹ	300
قبولیت کے لیے کم از کم بیلنس	4 TRX

50 000 000 کی حد درخواست میں موجود تمام پتوں کے مجموعے پر لاگو ہوتی ہے، نہ کہ ہر ایک پر الگ الگ۔

رسپانس — قبول شدہ (202، کوڈ 10202)

{
    "detail": {
        "code": 10202,
        "status": "accepted",
        "msg": "Order accepted for processing",
        "data": {
            "idempotencyKey": "my-batch-2026-01-01-001",
            "requestId": 1234,
            "itemsAccepted": 3,
            "statusUrl": "/apiv2/orchestrator/status/my-batch-2026-01-01-001",
            "items": [
                {
                    "deliveryKey": 5001,
                    "trackingId": "my-batch-2026-01-01-001:TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "amount": 65000,
                    "energyChunks": 1,
                    "activation": "planned",
                    "bandwidth": "planned",
                    "status": "queued"
                }
            ]
        }
    }
}

202 کا مطلب ہے قطار میں شامل (queued)، مکمل نہیں ہوا۔ ابھی تک کوئی فیس نہیں کٹی ہے۔ نتیجے کے لیے statusUrl کو پول کریں۔

trackingId جوڑا ہے idempotency key + address کا — یعنی آپ کے آرڈر کے اندر ایک ایڈریس کی شناخت۔ اسے اپنے لاگز اور ریکونسیلیشن میں استعمال کریں۔

مثال

curl -X POST https://netts.io/apiv2/orchestrator \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -H "X-Idempotency-Key: my-batch-2026-01-01-001" \
  -d '{
        "items": [
          {"receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", "amount": 65000}
        ]
      }'

---

پیش رفت چیک کریں — GET /apiv2/orchestrator/status/{idempotencyKey}

پورے آرڈر کے بجائے ایک ایڈریس حاصل کرنے کے لیے ?address=T… شامل کریں۔

{
    "detail": {
        "code": 10000,
        "status": "processing",
        "data": {
            "idempotencyKey": "my-batch-2026-01-01-001",
            "requestId": 1234,
            "clientRequestId": "my-batch-2026-01-01-001",
            "summary": {
                "total": 3, "queued": 1, "processing": 1, "completed": 1,
                "partial": 0, "failed": 0, "insufficient_balance": 0,
                "credentials_revoked": 0, "cancelled": 0
            },
            "items": [
                {
                    "deliveryKey": 5001,
                    "trackingId": "my-batch-2026-01-01-001:TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "status": "completed",
                    "energy": {
                        "requested": 65000,
                        "delegated": 65000,
                        "status": "done",
                        "chunks": { "total": 1, "done": 1 },
                        "orderIds": ["1Hxxxxxxxxxx"],
                        "hashes": ["0000000000000000000000000000000000000000000000000000000000000000"]
                    },
                    "activation": { "status": "not_needed", "orderId": null, "hash": null },
                    "bandwidth": {
                        "status": "enough", "orderId": "B1Hxxxxxxxxxxxxxx",
                        "amount": 400, "period": "1h", "hashes": [], "skipReason": null
                    },
                    "attempts": 1,
                    "startedAt": "2026-01-01T00:00:00+00:00",
                    "finishedAt": "2026-01-01T00:00:03+00:00"
                }
            ]
        }
    }
}

ایک نامعلوم کی، یا کسی دوسرے اکاؤنٹ کی کی، 404 لوٹاتی ہے۔

ایڈریس اسٹیٹس کی اقدار

اسٹیٹس	مفہوم
queued	اٹھائے جانے کا منتظر
processing	جاری ہے
completed	تمام مطلوبہ Energy ڈیلیگیٹ کر دی گئی
partial	کچھ حصے ڈیلیور ہو گئے، کچھ ناکام رہے
failed	کچھ بھی ڈیلیور نہیں ہوا
insufficient_balance	روک دیا گیا — آپ کا بیلنس کم از کم حد سے کم ہو گیا
credentials_revoked	آرڈر کے دوران آپ کی API کی ہٹا دی گئی یا غیر فعال کر دی گئی
cancelled	آپ کی منسوخی کی درخواست پر قطار سے ہٹا دیا گیا

مرحلے کی اسٹیٹس اقدار

مرحلہ	اقدار
activation	not_needed, done, failed, skipped, skipped_unavailable
bandwidth	enough, done, failed, skipped
energy	done, partial, failed

bandwidth.skipReason کے ذریعے skipped کی وضاحت ملتی ہے: option_off (آپ نے اسے غیر فعال کیا تھا)، energy_gt_600000 (بڑے انرجی آرڈرز کو بینڈوڈتھ میں اضافے کی ضرورت نہیں ہوتی)۔

ڈیلیگیشن ہیشز

energy.hashes آپ کی ترسیل کا ثبوت ہے۔ جب انرجی کسی بیرونی فراہم کنندہ سے آتی ہے تو آرڈر کے وقت ہیش معلوم نہیں ہوتا — یہ تقریباً ایک منٹ بعد درج کیا جاتا ہے، اور ایڈریس کو اس وقت تک مکمل نہیں دکھایا جاتا جب تک کہ ہیشز اکٹھے نہ ہو جائیں یا انتظار کا وقت ختم نہ ہو جائے۔ completed میں موجود ایڈریس جس کا ہیش موجود ہو، مکمل طور پر طے پا چکا ہے۔

---

منسوخ کریں — POST /apiv2/orchestrator/cancel/{idempotencyKey}

ہر اس ایڈریس کو قطار سے ہٹا دیتا ہے جسے ابھی تک اٹھایا نہیں گیا ہے۔

{
    "detail": {
        "code": 10005,
        "status": "cancelled",
        "msg": "Order cancelled: 7 addresses removed from queue",
        "data": { "cancelled": 7 }
    }
}

جو پتے پہلے ہی processing میں ہیں انہیں نہیں روکا جاتا: ممکن ہے ان کی کچھ انرجی کی ادائیگی پہلے ہی ہو چکی ہو۔ منسوخی بقیہ حصے کے لیے بہترین ممکنہ کوشش (best-effort) ہے۔

---

Idempotency

آرڈر کی شناخت آپ کی کی کے ذریعے کی جاتی ہے — X-Idempotency-Key ہیڈر، یا ہیڈر نہ ہونے کی صورت میں clientRequestId۔

درخواست دہرانا	نتیجہ
وہی کی، وہی باڈی	اصل آرڈر اور originalAcceptedAt کے ساتھ 208 — کوئی دوسرا آرڈر نہیں
وہی کی، مختلف باڈی	409 4090 IDEMPOTENCY_CONFLICT

لہذا آپ کی جانب سے نیٹ ورک ٹائم آؤٹ کی صورت میں من و عن دوبارہ کوشش کرنا محفوظ ہے۔ پہلے سے استعمال شدہ کی کے تحت پے لوڈ کو تبدیل کرنا خاموشی سے لاگو ہونے کے بجائے مسترد کر دیا جاتا ہے۔

آرڈر کے اندر، ہر ایڈریس کی اپنی اندرونی کی ہوتی ہے، اس لیے دہرائی جانے والی کال کبھی بھی کسی ایک ایڈریس سے دو بار کٹوتی نہیں کرتی۔

---

بلنگ

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

مرحلہ	کٹوتی کا طریقہ
Activation	الگ کٹوتی، آرڈر نمبر A…
Bandwidth	الگ کٹوتی، آرڈر نمبر B1H… — صرف اس صورت میں جب واقعی ڈیلیگیٹ کیا گیا ہو
Energy	فی ٹکڑا (chunk) ایک کٹوتی، آرڈر نمبر 1H…

کافی مفت بینڈوڈتھ کے ساتھ check: true کی کوئی لاگت نہیں ہوتی — اسٹیٹس enough ہوتا ہے اور کوئی آرڈر نہیں دیا جاتا۔ بڑی انرجی کی مقداریں بینڈوڈتھ کو مکمل طور پر چھوڑ دیتی ہیں۔

اگر بیچ کے درمیان میں آپ کا بیلنس ختم ہو جاتا ہے، تو بقیہ پتے بغیر کوشش کیے insufficient_balance پر ختم ہو جاتے ہیں۔

---

ایرر کوڈ ریفرنس

کوڈ	تفصیل	HTTP اسٹیٹس
10202	آرڈر قبول کر لیا گیا / پہلے ہی قبول شدہ	202 / 208
10000	اسٹیٹس واپس آ گیا	200
10005	آرڈر منسوخ کر دیا گیا	200
5004	غلط فیلڈ: ایڈریس فارمیٹ، amount حد سے باہر، bandwidthAmount 400/5000 نہیں ہے، bandwidthPeriod 5m/1h نہیں ہے، باڈی JSON آبجیکٹ نہیں ہے	400
5005	items غائب یا خالی ہے	400
5006	ایک آرڈر میں ڈپلیکیٹ receiveAddress	400
5009	خراب ساخت والا X-Idempotency-Key یا clientRequestId	400
5010	نہ تو X-Idempotency-Key اور نہ ہی clientRequestId فراہم کیا گیا	400
5012	درخواست میں کل انرجی 50 000 000 سے زیادہ ہے	400
-1	غلط API کی / IP وائٹ لسٹ میں نہیں ہے	401
1004	بیلنس 4 TRX کی کم از کم حد سے کم ہے	402
-1	آرڈر نہیں ملا (یا آپ کا نہیں ہے)	404
4090	IDEMPOTENCY_CONFLICT — وہی کی، مختلف باڈی	409
4220	درخواست کی تصدیق ناکام ہو گئی (تفصیلات data.errors میں)	422
429 / 5011	بہت زیادہ آرڈرز، پتے یا ٹکڑے زیرِ عمل ہیں	429
5003	آرڈر قبول نہیں کیا گیا تھا — سروس عارضی طور پر دستیاب نہیں ہے، دوبارہ کوشش کرنا محفوظ ہے	503

بنانے کے وقت 503 ایرر محفوظ ناکامی (fail-secure) ہے: کچھ بھی محفوظ نہیں کیا گیا اور کوئی کٹوتی نہیں ہوئی۔

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

فی سورس IP محدود:

مدت	حد
1 سیکنڈ	20 درخواستیں

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

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

نوٹس

• 202 ترسیل کی رسید نہیں ہے۔ اسے "queued" سمجھیں۔ نتیجہ اسٹیٹس اینڈ پوائنٹ میں ملتا ہے۔
• پتے متوازی طور پر چلتے ہیں، ایک آرڈر کے اندر ایک وقت میں 5 تک، تاکہ بڑا بیچ کسی ایک سست ایڈریس کی وجہ سے نہ رکے۔ تکمیل کی ترتیب کی ضمانت نہیں ہے۔
• ٹکڑوں میں تقسیم خودکار ہے: 1 000 000 سے زیادہ مقداروں کو برابر حصوں میں تقسیم کیا جاتا ہے، جن میں سے ہر ایک اپنا الگ انرجی آرڈر بن جاتا ہے۔ energy.orderIds اور energy.hashes ان تمام کو درج کرتے ہیں۔
• مجموعی طور پر آرکیسٹریٹر آرڈرز کے لیے کوئی ویب ہک نہیں ہے۔ ہر انرجی ڈیلیگیشن اب بھی معمول کا delegation.confirmed ویب ہک پیدا کرتی ہے، دیکھیے Webhooks۔
• متعلقہ اینڈ پوائنٹس: Activator، Bandwidth، Order 1H۔