Thu hồi Energy — hoàn trả energy đã thuê sớm

Hoàn trả energy đã ủy quyền về pool trước khi thời hạn thuê kết thúc. Hữu ích khi giao dịch mà bạn thuê energy đã được gửi đi: energy sẽ không còn nhàn rỗi trên địa chỉ, và pool có thể phục vụ người khác.

Việc thu hồi là tự nguyện. Các gói thuê sẽ tự động hết hạn — bạn không bao giờ bắt buộc phải gọi endpoint này.

URL gốc của endpoint

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

Bandwidth có endpoint riêng, xem Bandwidth.

Tiêu đề Yêu cầu (Request Headers)

Tiêu đề	Bắt buộc	Mô tả
X-API-KEY	Có	Khóa API đã được dùng để tạo đơn hàng
X-Real-IP	Có	Địa chỉ IP từ danh sách trắng (whitelist) của bạn

user_id của bạn được lấy từ khóa API — bạn không bao giờ phải truyền nó.

Khóa API phải là khóa đã dùng cho đơn hàng

Một đơn hàng chỉ có thể được thu hồi bằng chính khóa đã tạo ra nó. Một khóa khác của cùng một tài khoản sẽ không hoạt động.

---

Thu hồi — POST /apiv2/energy/reclaim/{orderId}

orderId là mã đơn hàng được trả về khi energy được đặt thuê — ví dụ 1H… cho các gói thuê 1 giờ hoặc 5M… cho các gói thuê 5 phút. Không có thân yêu cầu (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"

Phản hồi — đã thu hồi (200, mã 10004)

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

reclaimHash là giao dịch on-chain đã hoàn trả energy. Thời gian thông thường từ khi yêu cầu đến khi nhận phản hồi là vài giây.

Phản hồi — đã được thu hồi trước đó (200, mã 10004)

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

Gọi endpoint này hai lần là an toàn: lệnh gọi thứ hai trả về cùng một mã băm (hash) và không làm thay đổi điều gì. Điều này cũng áp dụng cho các gói thuê đã tự hết hạn.

Phản hồi — nhà cung cấp bên ngoài (400, mã 5006)

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

Các đơn hàng do nhà cung cấp bên ngoài phục vụ không thể thu hồi: tài nguyên không thuộc về chúng tôi để hoàn trả. Nhà cung cấp nào đã phục vụ đơn hàng có thể được nhìn thấy trong phản hồi của đơn hàng.

Phản hồi — không có gì để thu hồi (400, mã 5005)

Đơn hàng chưa từng tạo ra ủy quyền, hoặc ủy quyền không còn hoạt động. Không có khoản phí nào bị tính và không có gì thay đổi.

Phản hồi — chưa hoàn tất (503, mã 5003)

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

Yêu cầu thu hồi đã được chấp nhận nhưng giao dịch on-chain chưa xuất hiện trong khoảng thời gian chờ. Nó rất có thể sẽ tự hoàn thành — hãy lặp lại lệnh gọi sau vài giây để nhận mã băm.

Phản hồi — không tìm thấy đơn hàng (404)

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

Được trả về trong cả hai trường hợp: đơn hàng không tồn tại hoặc thuộc về một tài khoản khác.

---

Một đơn hàng, không phải một địa chỉ

Việc thu hồi hoạt động theo từng đơn hàng, không phải theo địa chỉ. Điều này là có chủ đích: một đơn hàng xác định chính xác những gì đang được hoàn trả — cùng một địa chỉ có thể chứa energy từ nhiều đơn hàng, bao gồm cả đơn hàng của các tài khoản khác.

Hai hệ quả đáng lưu ý khi lập kế hoạch:

• Một đơn hàng hàng loạt (batch) cho nhiều địa chỉ sẽ tạo ra một mã đơn hàng cho mỗi địa chỉ. Bạn có thể thu hồi bất kỳ đơn nào trong số đó một cách riêng lẻ; các đơn còn lại vẫn tiếp tục hoạt động.
• Một lượng lớn cho một địa chỉ duy nhất có thể được chia thành nhiều đơn hàng. Để giải phóng địa chỉ đó hoàn toàn, hãy thu hồi từng đơn hàng một.

Thu hồi các đơn hàng được tạo thông qua Orchestrator

Hoạt động theo cách tương tự. Yêu cầu Orchestrator cung cấp trạng thái cho yêu cầu của bạn, lấy mã đơn hàng từ trường energy.orderIds của địa chỉ bạn muốn, và gọi lệnh thu hồi với mã đó:

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

Chi phí

Thu hồi không hoàn lại bất kỳ khoản tiền nào. Thuê và hoàn trả là hai thao tác riêng biệt: bạn đã thanh toán cho gói thuê khi đặt đơn hàng, và việc hoàn trả tài nguyên sớm không hoàn tác khoản thanh toán đó.

Giới hạn tốc độ (Rate limit)

10 yêu cầu mỗi giây cho mỗi IP.

Mã lỗi

Mã	HTTP	Ý nghĩa
10004	200	Đã thu hồi, hoặc đã được thu hồi trước đó — bao gồm mã băm
5003	503	Đã chấp nhận, mã băm chưa được xác nhận — thử lại sau giây lát
5005	400	Không có gì để thu hồi cho đơn hàng này
5006	400	Đơn hàng từ nhà cung cấp bên ngoài — tính năng thu hồi không khả dụng
−1	404	Không tìm thấy đơn hàng, hoặc thuộc về tài khoản khác
−1	401	Khóa API bị thiếu hoặc không hợp lệ, hoặc IP không nằm trong danh sách trắng