Orchestrator — एक ही कॉल में बैच ऑर्डर

एक ही अनुरोध में अधिकतम 100 पते भेजें और Netts को प्रत्येक पते के लिए संपूर्ण अनुक्रम संभालने दें: यदि आवश्यक हो तो पते को सक्रिय करें, कमी होने पर इसके Bandwidth को टॉप अप करें, फिर Energy किराए पर लें — बड़ी मात्रा को स्वचालित रूप से टुकड़ों में विभाजित करते हुए।

आपको ट्रैकिंग कुंजी के साथ तुरंत 202 Accepted प्राप्त होता है और कनेक्शन पर कभी प्रतीक्षा नहीं करनी पड़ती। इसके बाद स्थिति एंडपॉइंट से प्रगति पढ़ी जाती है।

इसका उपयोग क्यों करें

एक नए पते के लिए Energy ऑर्डर करने में सामान्यतः उनके बीच आपके अपने पुनः प्रयास तर्क (retry logic) के साथ, सही क्रम में, तीन अलग-अलग कॉल की आवश्यकता होती है। Orchestrator इसे एक अनुरोध में समाहित करता है और प्रत्येक पते के लिए यह अनुक्रम चलाता है:

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

सक्रियण या Bandwidth में विफलता उस पते के लिए Energy ऑर्डर को नहीं रोकती है, और एक पते की विफलता अन्य पतों को कभी प्रभावित नहीं करती है।

एंडपॉइंट बेस URL

https://netts.io/apiv2/orchestrator

अनुरोध हेडर

हेडर	आवश्यक	विवरण
Content-Type	हाँ	application/json
X-API-KEY	हाँ	Netts डैशबोर्ड से आपकी API कुंजी
X-Real-IP	हाँ	आपकी श्वेतसूची (whitelist) से IP पता
X-Idempotency-Key	हाँ*	इस ऑर्डर के लिए आपकी कुंजी, `A-Z a-z 0-9 . _ : -` के 12–128 वर्ण

* या तो X-Idempotency-Key हेडर या बॉडी में clientRequestId फ़ील्ड आवश्यक है। यदि आप दोनों में से कोई भी नहीं भेजते हैं, तो अनुरोध को 5010 के साथ अस्वीकार कर दिया जाता है।

कुंजी पूरे ऑर्डर की पहचान करती है। उसी कुंजी के साथ अनुरोध दोहराने पर दूसरा ऑर्डर बनाने के बजाय मूल परिणाम वापस आता है — देखें Idempotency।

ऑर्डर बनाएं — `POST /apiv2/orchestrator`

अनुरोध बॉडी

json

{
    "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	नहीं	आपका ऑर्डर संदर्भ, `A-Z a-z 0-9 . _ : -` के 8–128 वर्ण। यदि हेडर अनुपस्थित है तो यह Idempotency कुंजी के रूप में भी कार्य करता है।
`defaults`	object	नहीं	उन सभी आइटम पर लागू मान जो उन्हें ओवरराइड नहीं करते हैं।

आइटम फ़ील्ड

receiveAddress और amount को छोड़कर प्रत्येक फ़ील्ड को defaults में भी सेट किया जा सकता है। आइटम पर मौजूद मान डिफ़ॉल्ट मान से अधिक प्राथमिकता रखता है।

फ़ील्ड	प्रकार	डिफ़ॉल्ट	विवरण
`receiveAddress`	string	—	Energy प्राप्त करने वाला TRON पता
`amount`	int	—	इस पते के लिए Energy, 61 000 … 50 000 000
`bandwidth`	bool	`true`	कमी होने पर इस पते के लिए Bandwidth ऑर्डर करें
`bandwidthAmount`	int	`400`	`400` या `5000`
`bandwidthPeriod`	string	`1h`	`5m` या `1h`
`check`	bool	नीचे देखें	पहले मुफ़्त Bandwidth की जाँच करें और यदि पर्याप्त हो तो ऑर्डर छोड़ दें
`trx_send`	bool	`false`	Bandwidth सेवा को अग्रेषित किया गया
`activation`	bool	`true`	यदि पता सक्रिय नहीं है तो उसे सक्रिय करें। किसी ऐसे पते के लिए इस चरण को छोड़ने के लिए `false` सेट करें जिसके बारे में आप जानते हैं कि वह पहले से सक्रिय है।

जब bandwidthAmount का मान 400 होता है, तो check डिफ़ॉल्ट रूप से true होता है, और अन्यथा false होता है — 5 000 यूनिट ऑर्डर करने का आमतौर पर मतलब है कि आप उन्हें चाहते हैं, भले ही वहां पहले से कुछ भी उपलब्ध हो।

मात्राएं प्रति पता हैं। एक अनुरोध स्वतंत्र रूप से विभिन्न मात्राओं को मिला सकता है; एकमात्र सीमा कुल योग है।

सीमाएं

सीमा	मान
प्रति ऑर्डर पते	100
प्रति पता Energy	61 000 … 50 000 000
प्रति ऑर्डर कुल Energy	50 000 000
प्रति खाता इन-फ़्लाइट ऑर्डर	3
प्रति खाता इन-फ़्लाइट पते	300
स्वीकार किए जाने के लिए न्यूनतम शेष राशि	4 TRX

50 000 000 की अधिकतम सीमा अनुरोध में सभी पतों के योग पर लागू होती है, न कि प्रत्येक पर।

प्रतिक्रिया — स्वीकृत (202, कोड `10202`)

json

{
    "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 कुंजी + पता — आपके ऑर्डर के अंदर एक पते की पहचान। अपने स्वयं के लॉग और समाधान (reconciliation) में इसका उपयोग करें।

उदाहरण

bash

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… जोड़ें।

json

{
    "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 प्रत्यायोजित (delegated) कर दी गई
`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 ऑर्डर को Bandwidth टॉप-अप की आवश्यकता नहीं होती है)।

डेलिगेशन हैश

energy.hashes आपका वितरण का प्रमाण है। जब Energy किसी बाहरी प्रदाता से आती है तो ऑर्डर के समय हैश ज्ञात नहीं होता है — इसे लगभग एक मिनट बाद भरा जाता है, और जब तक हैश एकत्र नहीं हो जाते या प्रतीक्षा विंडो समाप्त नहीं हो जाती, तब तक पते को पूर्ण के रूप में रिपोर्ट नहीं किया जाता है। हैश मौजूद होने के साथ completed में मौजूद पता पूरी तरह से तय (settled) होता है।

रद्द करें — `POST /apiv2/orchestrator/cancel/{idempotencyKey}`

कतार से प्रत्येक उस पते को हटाता है जिसे अभी तक उठाया नहीं गया है।

json

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

जो पते पहले से ही processing में हैं, वे बाधित नहीं होते हैं: उनकी Energy के हिस्से के लिए पहले ही भुगतान किया जा चुका हो सकता है। शेष पर रद्द करना सर्वोत्तम-प्रयास (best-effort) है।

Idempotency

ऑर्डर की पहचान आपकी कुंजी द्वारा की जाती है — X-Idempotency-Key हेडर, या हेडर अनुपस्थित होने पर clientRequestId।

दोहराया गया अनुरोध	परिणाम
समान कुंजी, समान बॉडी	मूल ऑर्डर और `originalAcceptedAt` के साथ 208 — कोई दूसरा ऑर्डर नहीं
समान कुंजी, भिन्न बॉडी	409 `4090 IDEMPOTENCY_CONFLICT`

इसलिए आपकी तरफ से नेटवर्क टाइमआउट होने पर शब्दशः पुनः प्रयास करना सुरक्षित है। पहले से उपयोग की गई कुंजी के तहत पेलोड को बदलना चुपचाप लागू होने के बजाय अस्वीकार कर दिया जाता है।

ऑर्डर के अंदर, प्रत्येक पता अपनी आंतरिक कुंजी रखता है, इसलिए दोहराने पर भी किसी एक पते पर कभी दोहरा शुल्क नहीं लगता है।

बिलिंग

Orchestrator स्वयं कुछ भी शुल्क नहीं लेता है। प्रत्येक चरण का बिल उस सेवा द्वारा लिया जाता है जो इसे निष्पादित करती है, इसकी सामान्य कीमत पर:

चरण	शुल्क के रूप में
Activation	अलग कटौती, ऑर्डर संख्या `A…`
Bandwidth	अलग कटौती, ऑर्डर संख्या `B1H…` — केवल तभी जब वास्तव में प्रत्यायोजित किया गया हो
Energy	प्रति टुकड़ा एक कटौती, ऑर्डर संख्या `1H…`

पर्याप्त मुफ़्त Bandwidth के साथ check: true में कुछ भी खर्च नहीं होता है — स्थिति enough होती है और कोई ऑर्डर नहीं दिया जाता है। बड़ी मात्रा में Energy, Bandwidth को पूरी तरह से छोड़ देती है।

यदि बैच के बीच में आपकी शेष राशि समाप्त हो जाती है, तो शेष पते बिना प्रयास किए 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`	अनुरोध में कुल Energy 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 फ़ेल-सिक्योर है: कुछ भी संग्रहीत नहीं किया गया था और कोई शुल्क नहीं लिया गया था।

दर सीमाएं (Rate Limits)

प्रति स्रोत IP सीमित:

अवधि	सीमा
1 सेकंड	20 अनुरोध

दर सीमा पार हो गई (429)

json

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

202 वितरण रसीद नहीं है। इसे "कतारबद्ध" मानें। परिणाम स्थिति एंडपॉइंट में रहता है।
पते समानांतर में चलते हैं, एक ऑर्डर के भीतर एक समय में 5 तक, इसलिए एक बड़ा बैच किसी एक धीमे पते पर प्रतीक्षा नहीं करता है। पूर्ण होने के क्रम की गारंटी नहीं है।
चंकिंग स्वचालित है: 1 000 000 से ऊपर की राशि को बराबर टुकड़ों में विभाजित किया जाता है, प्रत्येक अपना Energy ऑर्डर बन जाता है। energy.orderIds और energy.hashes उन सभी को सूचीबद्ध करते हैं।
समग्र रूप से orchestrator ऑर्डर के लिए कोई वेबहुक नहीं है। प्रत्येक Energy डेलिगेशन अभी भी सामान्य delegation.confirmed वेबहुक उत्पन्न करता है, देखें Webhooks।
संबंधित एंडपॉइंट: Activator, Bandwidth, Order 1H।

Orchestrator — एक ही कॉल में बैच ऑर्डर ​

इसका उपयोग क्यों करें ​

एंडपॉइंट बेस URL ​

अनुरोध हेडर ​

ऑर्डर बनाएं — POST /apiv2/orchestrator ​

अनुरोध बॉडी ​

शीर्ष-स्तरीय फ़ील्ड ​

आइटम फ़ील्ड ​

सीमाएं ​

प्रतिक्रिया — स्वीकृत (202, कोड 10202) ​

उदाहरण ​

प्रगति जांचें — GET /apiv2/orchestrator/status/{idempotencyKey} ​

पता स्थिति मान ​

चरण स्थिति मान ​

डेलिगेशन हैश ​

रद्द करें — POST /apiv2/orchestrator/cancel/{idempotencyKey} ​

Idempotency ​

बिलिंग ​

त्रुटि कोड संदर्भ ​

दर सीमाएं (Rate Limits) ​

दर सीमा पार हो गई (429) ​

टिप्पणियाँ ​

Orchestrator — एक ही कॉल में बैच ऑर्डर

इसका उपयोग क्यों करें

एंडपॉइंट बेस URL

अनुरोध हेडर

ऑर्डर बनाएं — `POST /apiv2/orchestrator`

अनुरोध बॉडी

शीर्ष-स्तरीय फ़ील्ड

आइटम फ़ील्ड

सीमाएं

प्रतिक्रिया — स्वीकृत (202, कोड `10202`)

उदाहरण

प्रगति जांचें — `GET /apiv2/orchestrator/status/{idempotencyKey}`

पता स्थिति मान

चरण स्थिति मान

डेलिगेशन हैश

रद्द करें — `POST /apiv2/orchestrator/cancel/{idempotencyKey}`

Idempotency

बिलिंग

त्रुटि कोड संदर्भ

दर सीमाएं (Rate Limits)

दर सीमा पार हो गई (429)

टिप्पणियाँ