Energy Reclaim — किराए पर ली गई energy को समय से पहले वापस करें

किराए की अवधि समाप्त होने से पहले डेलिगेट की गई energy को पूल में वापस करें। यह तब उपयोगी होता है जब वह ट्रांजेक्शन जिसके लिए आपने किराए पर लिया था, पहले ही भेजा जा चुका है: energy पते पर बेकार पड़ी नहीं रहती है, और पूल किसी अन्य की सेवा कर सकता है।

Reclaim स्वैच्छिक है। किराए अपने आप समाप्त हो जाते हैं — आपको इस एंडपॉइंट को कॉल करने की कभी आवश्यकता नहीं होती है।

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

https://netts.io/apiv2/energy/reclaim

Bandwidth का अपना एंडपॉइंट है, देखें Bandwidth।

अनुरोध हेडर (Request Headers)

Header	Required	Description
X-API-KEY	हाँ	API कुंजी जिसके साथ ऑर्डर दिया गया था
X-Real-IP	हाँ	आपकी श्वेतसूची (whitelist) से IP पता

आपकी user_id API कुंजी से प्राप्त होती है — आप इसे कभी पास नहीं करते हैं।

कुंजी वही होनी चाहिए जिसका उपयोग ऑर्डर के लिए किया गया था

ऑर्डर को केवल उसी कुंजी से reclaim किया जा सकता है जिसने इसे बनाया था। उसी खाते की कोई भिन्न कुंजी काम नहीं करेगी।

---

Reclaim — POST /apiv2/energy/reclaim/{orderId}

orderId वह ऑर्डर नंबर है जो energy ऑर्डर करते समय लौटाया गया था — उदाहरण के लिए 1-घंटे के किराए के लिए 1H… या 5-मिनट के किराए के लिए 5M…। कोई अनुरोध बॉडी (request body) नहीं।

curl -X POST "https://netts.io/apiv2/energy/reclaim/1Hb252feadcc" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip"

प्रतिक्रिया — reclaim किया गया (200, कोड 10004)

{
    "detail": {
        "code": 10004,
        "status": "reclaimed",
        "msg": "Energy reclaimed",
        "data": {
            "orderId": "1Hb252feadcc",
            "reclaimHash": "51fa77da06e8fbebf504fbf088d1d9611059398d…"
        }
    }
}

reclaimHash ऑन-चेन ट्रांजेक्शन है जिसने energy वापस की। अनुरोध से प्रतिक्रिया तक का सामान्य समय कुछ सेकंड का होता है।

प्रतिक्रिया — पहले से ही reclaim किया गया (200, कोड 10004)

{
    "detail": {
        "code": 10004,
        "status": "reclaimed",
        "msg": "Energy already reclaimed",
        "data": {
            "orderId": "1Hb252feadcc",
            "reclaimHash": "51fa77da06e8fbebf504fbf088d1d9611059398d…"
        }
    }
}

एंडपॉइंट को दो बार कॉल करना सुरक्षित है: दूसरा कॉल वही हैश लौटाता है और कुछ भी नहीं बदलता है। यह उन किरायों को भी कवर करता है जो अपने आप पहले ही समाप्त हो चुके हैं।

प्रतिक्रिया — बाहरी प्रदाता (400, कोड 5006)

{
    "detail": {
        "code": 5006,
        "status": "failed",
        "msg": "Reclaim is available only for internal pool orders",
        "data": { "orderId": "1H47eac983af", "provider": "…" }
    }
}

किसी बाहरी प्रदाता द्वारा पूरे किए गए ऑर्डरों को reclaim नहीं किया जा सकता: संसाधन वापस करने के लिए हमारे नहीं हैं। किस प्रदाता ने ऑर्डर पूरा किया है, यह ऑर्डर प्रतिक्रिया में दिखाई देता है।

प्रतिक्रिया — reclaim करने के लिए कुछ नहीं है (400, कोड 5005)

ऑर्डर के परिणामस्वरूप कभी कोई डेलिगेशन नहीं हुआ, या डेलिगेशन सक्रिय नहीं है। कुछ भी शुल्क नहीं लिया जाता है और कुछ भी नहीं बदलता है।

प्रतिक्रिया — अभी पूरा नहीं हुआ है (503, कोड 5003)

{
    "detail": {
        "code": 5003,
        "status": "failed",
        "msg": "Reclaim not completed yet — try again shortly",
        "data": { "orderId": "1Hb252feadcc" }
    }
}

Reclaim स्वीकार कर लिया गया था लेकिन प्रतीक्षा विंडो के भीतर ऑन-चेन ट्रांजेक्शन दिखाई नहीं दिया था। यह संभवतः अपने आप पूरा हो जाएगा — हैश प्राप्त करने के लिए कुछ सेकंड में कॉल दोहराएं।

प्रतिक्रिया — ऑर्डर नहीं मिला (404)

{ "detail": { "code": -1, "msg": "Order not found" } }

यह तब लौटाया जाता है जब ऑर्डर मौजूद नहीं होता है और जब यह किसी भिन्न खाते से संबंधित होता है।

---

एक ऑर्डर, एक पता नहीं

Reclaim प्रति ऑर्डर काम करता है, प्रति पता नहीं। यह जानबूझकर किया गया है: एक ऑर्डर ठीक से पहचानता है कि क्या वापस किया जा रहा है — एक ही पते पर कई ऑर्डरों से energy हो सकती है, जिसमें अन्य खातों के ऑर्डर भी शामिल हैं।

योजना बनाने योग्य दो परिणाम:

• कई पतों के लिए एक बैच ऑर्डर प्रति पता एक ऑर्डर नंबर उत्पन्न करता है। आप उनमें से किसी को भी व्यक्तिगत रूप से reclaim करते हैं; बाकी काम करते रहते हैं।
• एकल पते के लिए एक बड़ी राशि को कई ऑर्डरों में विभाजित किया जा सकता है। उस पते को पूरी तरह मुक्त करने के लिए, उनमें से प्रत्येक को reclaim करें।

Orchestrator के माध्यम से दिए गए ऑर्डरों को reclaim करना

उसी तरह काम करता है। अपने अनुरोध की स्थिति के लिए Orchestrator से पूछें, अपने इच्छित पते के energy.orderIds फ़ील्ड से ऑर्डर नंबर लें, और इसके साथ reclaim को कॉल करें:

"energy": {
    "requested": 65570,
    "delegated": 65570,
    "status": "done",
    "orderIds": ["1Hb252feadcc"]
}

राशि (Money)

Reclaim कुछ भी वापस (रिफंड) नहीं करता है। किराए पर लेना और वापस करना अलग-अलग ऑपरेशन हैं: आपने ऑर्डर देते समय किराए के लिए भुगतान किया था, और संसाधन को जल्दी वापस करने से वह भुगतान रद्द नहीं होता है।

दर सीमा (Rate limit)

प्रति IP प्रति सेकंड 10 अनुरोध।

त्रुटि कोड (Error codes)

Code	HTTP	Meaning
10004	200	Reclaim किया गया, या पहले से ही reclaim किया गया — हैश शामिल है
5003	503	स्वीकार किया गया, हैश की अभी पुष्टि नहीं हुई है — शीघ्र ही पुनः प्रयास करें
5005	400	इस ऑर्डर के लिए reclaim करने हेतु कुछ नहीं है
5006	400	बाहरी प्रदाता ऑर्डर — reclaim अनुपलब्ध है
−1	404	ऑर्डर नहीं मिला, या किसी अन्य खाते से संबंधित है
−1	401	गायब या अमान्य API कुंजी, या IP श्वेतसूची में नहीं है