การเรียกคืน Energy — คืน Energy ที่เช่าก่อนกำหนด

ส่งคืน Energy ที่ได้รับการมอบหมาย (delegate) กลับไปยังพูลก่อนที่ระยะเวลาการเช่าจะสิ้นสุดลง มีประโยชน์เมื่อธุรกรรม ที่คุณเช่ามาใช้งานนั้นถูกส่งไปแล้ว: Energy จะได้ไม่ค้างอยู่บนที่อยู่โดยเปล่าประโยชน์ และพูลสามารถ นำไปให้บริการแก่ผู้อื่นต่อได้

การเรียกคืนเป็นแบบตามความสมัครใจ การเช่าจะหมดอายุลงเองตามระยะเวลา — คุณไม่จำเป็นต้องเรียกใช้งานเอนด์พอยต์นี้เลยก็ได้

Base URL ของ Endpoint

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

Bandwidth มีเอนด์พอยต์แยกเป็นของตัวเอง โปรดดูที่ Bandwidth

Headers ของคำขอ

ส่วนหัว	จำเป็น	คำอธิบาย
X-API-KEY	ใช่	คีย์ API ที่ใช้ในการสร้างคำสั่งซื้อ
X-Real-IP	ใช่	ที่อยู่ IP ที่อยู่ในไวต์ลิสต์ของคุณ

user_id ของคุณจะได้มาจากคีย์ API โดยตรง — คุณไม่ต้องส่งค่านี้ไป

คีย์ที่ใช้ต้องเป็นคีย์เดียวกันกับที่ใช้สร้างคำสั่งซื้อ

คำสั่งซื้อสามารถเรียกคืนได้ด้วยคีย์ที่สร้างคำสั่งซื้อนั้นขึ้นมาเท่านั้น คีย์อื่นที่อยู่ในบัญชีเดียวกัน จะไม่สามารถใช้งานได้

---

เรียกคืน — POST /apiv2/energy/reclaim/{orderId}

orderId คือหมายเลขคำสั่งซื้อที่ได้รับกลับมาตอนสั่งซื้อ Energy — ตัวอย่างเช่น 1H… สำหรับ การเช่าแบบ 1 ชั่วโมง หรือ 5M… สำหรับการเช่าแบบ 5 นาที ไม่ต้องมีเนื้อหาคำขอ (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"

การตอบกลับ — เรียกคืนสำเร็จ (200, รหัส 10004)

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

reclaimHash คือธุรกรรมบนเชนที่ส่งคืน Energy เวลาโดยทั่วไปตั้งแต่ส่งคำขอจนถึง ได้รับการตอบกลับจะอยู่ที่สองสามวินาที

การตอบกลับ — มีการเรียกคืนไปแล้ว (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": "…" }
    }
}

คำสั่งซื้อที่ให้บริการโดยผู้ให้บริการภายนอกจะไม่สามารถเรียกคืนได้: เนื่องจากทรัพยากรไม่ได้เป็นของเราที่จะส่งคืนได้ คุณสามารถดูว่าผู้ให้บริการรายใดเป็นผู้ดำเนินการคำสั่งซื้อได้จากการตอบกลับของคำสั่งซื้อ

การตอบกลับ — ไม่มีรายการให้เรียกคืน (400, รหัส 5005)

คำสั่งซื้อไม่เคยส่งผลให้เกิดการมอบหมาย (delegation) หรือการมอบหมายนั้นไม่ได้ใช้งานอยู่ ไม่มีการคิดค่าบริการและ ไม่มีสิ่งใดเปลี่ยนแปลง

การตอบกลับ — ยังดำเนินการไม่เสร็จสิ้น (503, รหัส 5003)

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

ระบบรับคำขอการเรียกคืนแล้ว แต่ธุรกรรมบนเชนยังไม่ปรากฏขึ้นภายในระยะเวลาที่กำหนด โดยส่วนใหญ่ธุรกรรมจะดำเนินการเสร็จสิ้นได้เอง — ให้ลองเรียกใหม่อีกครั้งในอีกสองสามวินาทีเพื่อรับแฮช

การตอบกลับ — ไม่พบคำสั่งซื้อ (404)

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

จะส่งค่านี้กลับมาทั้งในกรณีที่ไม่พบคำสั่งซื้อและกรณีที่คำสั่งซื้อนั้นเป็นของบัญชีอื่น

---

ต่อหนึ่งคำสั่งซื้อ ไม่ใช่ต่อหนึ่งที่อยู่

การเรียกคืนจะทำงานแยกตามคำสั่งซื้อ ไม่ใช่แยกตามที่อยู่ ซึ่งได้รับการออกแบบมาโดยเฉพาะ: คำสั่งซื้อจะระบุอย่างชัดเจนว่า กำลังส่งคืนรายการใด — ที่อยู่เดียวกันอาจถือครอง Energy จากหลายคำสั่งซื้อได้ รวมถึงคำสั่งซื้อ จากบัญชีอื่นๆ ด้วย

ข้อควรคำนึงสองประการในการวางแผนระบบ:

• คำสั่งซื้อแบบกลุ่ม (batch order) สำหรับหลายที่อยู่จะสร้างหมายเลขคำสั่งซื้อแยกหนึ่งหมายเลขต่อหนึ่งที่อยู่ คุณสามารถเรียกคืนรายการใด รายการหนึ่งแยกกันได้ โดยรายการที่เหลือยังคงทำงานต่อไป
• จำนวนทรัพยากรจำนวนมากสำหรับที่อยู่เดียวอาจถูกแบ่งออกเป็นหลายคำสั่งซื้อ การจะปลดปล่อยที่อยู่นั้น อย่างสมบูรณ์ คุณจะต้องเรียกคืนแต่ละคำสั่งซื้อทีละรายการ

การเรียกคืนคำสั่งซื้อที่สร้างผ่าน Orchestrator

ทำงานในลักษณะเดียวกัน ให้สอบถามสถานะคำขอของคุณจาก Orchestrator จากนั้นนำหมายเลขคำสั่งซื้อจากฟิลด์ energy.orderIds ของที่อยู่ที่คุณต้องการ และส่งคำขอเรียกคืนด้วยหมายเลขดังกล่าว:

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

ค่าใช้จ่าย

การเรียกคืนจะไม่มีการคืนเงินใดๆ ทั้งสิ้น การเช่าและการส่งคืนเป็นการดำเนินการที่แยกจากกัน: คุณได้ชำระเงินสำหรับการเช่า ไปแล้วเมื่อสร้างคำสั่งซื้อ และการส่งคืนทรัพยากรก่อนกำหนดไม่ได้เป็นการยกเลิกการชำระเงินนั้น

อัตราจำกัดการเรียกใช้งาน

10 คำขอต่อวินาที ต่อ IP

รหัสข้อผิดพลาด

รหัส	HTTP	ความหมาย
10004	200	เรียกคืนสำเร็จ หรือได้รับการเรียกคืนไปแล้ว — มีแฮชแนบมาด้วย
5003	503	รับคำขอแล้ว แต่ยังไม่ได้รับการยืนยันแฮช — ให้ลองใหม่อีกครั้งในไม่ช้า
5005	400	ไม่มีรายการให้เรียกคืนสำหรับคำสั่งซื้อนี้
5006	400	คำสั่งซื้อจากผู้ให้บริการภายนอก — ไม่สามารถเรียกคืนได้
−1	404	ไม่พบคำสั่งซื้อ หรือคำสั่งซื้อเป็นของบัญชีอื่น
−1	401	คีย์ API ไม่ถูกต้องหรือไม่ได้ระบุ หรือ IP ไม่อยู่ในไวต์ลิสต์