Energy Reclaim — kiralanan Energy'yi erken iade etme

Kiralama süresi sona ermeden önce delege edilen Energy'yi havuza iade edin. Kiralama yaptığınız işlem zaten gönderildiğinde faydalıdır: Energy adreste boşta beklemez ve havuz başka birine hizmet verebilir.

Reclaim isteğe bağlıdır. Kiralamaların süresi kendiliğinden dolar — bu uç noktayı hiçbir zaman çağırmak zorunda değilsiniz.

Uç nokta temel URL'si

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

Bandwidth'in kendi uç noktası vardır, bkz. Bandwidth.

İstek Başlıkları

Başlık	Gerekli	Açıklama
X-API-KEY	Evet	Siparişin verildiği API anahtarı
X-Real-IP	Evet	Beyaz listenizdeki IP adresi

user_id bilginiz API anahtarından türetilir — bunu asla siz iletmezsiniz.

Anahtar, sipariş için kullanılan anahtar olmalıdır

Bir sipariş yalnızca onu oluşturan anahtarla geri çağrılabilir. Aynı hesaba ait farklı bir anahtar çalışmayacaktır.

---

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

orderId, Energy siparişi verildiğinde döndürülen sipariş numarasıdır — örneğin 1 saatlik kiralamalar için 1H… veya 5 dakikalık kiralamalar için 5M…. İstek gövdesi yoktur.

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

Yanıt — geri çağrıldı (200, kod 10004)

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

reclaimHash, Energy'yi iade eden zincir üstü (on-chain) işlemdir. İstekten yanıta kadar geçen tipik süre birkaç saniyedir.

Yanıt — zaten geri çağrılmış (200, kod 10004)

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

Uç noktayı iki kez çağırmak güvenlidir: ikinci çağrı aynı karmayı (hash) döndürür ve hiçbir şeyi değiştirmez. Bu durum, süresi kendiliğinden dolmuş kiralamaları da kapsar.

Yanıt — harici sağlayıcı (400, kod 5006)

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

Harici bir sağlayıcı tarafından karşılanan siparişler geri çağrılamaz: kaynaklar bize ait olmadığı için iade edilemez. Bir siparişi hangi sağlayıcının karşıladığı, sipariş yanıtında görülebilir.

Yanıt — geri çağrılacak bir şey yok (400, kod 5005)

Sipariş hiçbir zaman bir delegasyonla sonuçlanmadı veya delegasyon aktif değil. Hiçbir ücret alınmaz ve hiçbir şey değişmez.

Yanıt — henüz tamamlanmadı (503, kod 5003)

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

Geri çağırma kabul edildi ancak zincir üstü işlem bekleme penceresi içinde görünmedi. Büyük olasılıkla kendiliğinden tamamlanacaktır — karmayı (hash) almak için çağrıyı birkaç saniye içinde tekrarlayın.

Yanıt — sipariş bulunamadı (404)

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

Hem sipariş mevcut olmadığında hem de farklı bir hesaba ait olduğunda döndürülür.

---

Tek bir adres değil, tek bir sipariş

Reclaim adres başına değil, sipariş başına çalışır. Bu kasıtlıdır: bir sipariş neyin iade edildiğini tam olarak tanımlar — aynı adres, diğer hesapların siparişleri de dahil olmak üzere birden fazla siparişten Energy barındırıyor olabilir.

Planlamaya değer iki sonuç:

• Birçok adres için verilen bir toplu sipariş, adres başına bir sipariş numarası üretir. Bunlardan herhangi birini tek tek geri çağırabilirsiniz; geri kalanı çalışmaya devam eder.
• Tek bir adres için verilen büyük bir miktar birkaç siparişe bölünebilir. Bu adresi tamamen serbest bırakmak için her birini ayrı ayrı geri çağırın.

Orchestrator üzerinden verilen siparişleri geri çağırma

Aynı şekilde çalışır. Orchestrator uç noktasından isteğinizin durumunu sorgulayın, istediğiniz adresin energy.orderIds alanından sipariş numarasını alın ve bununla reclaim çağrısı yapın:

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

Ücretlendirme

Reclaim herhangi bir geri ödeme yapmaz. Kiralama ve iade etme ayrı işlemlerdir: siparişi verdiğinizde kiralama ücretini ödediniz ve kaynağı erken iade etmek bu ödemeyi geri almaz.

İstek limiti

IP başına saniyede 10 istek.

Hata kodları

Kod	HTTP	Anlamı
10004	200	Geri çağrıldı veya zaten geri çağrılmış — karma (hash) dahil
5003	503	Kabul edildi, karma henüz onaylanmadı — kısa süre içinde tekrar deneyin
5005	400	Bu sipariş için geri çağrılacak bir şey yok
5006	400	Harici sağlayıcı siparişi — reclaim kullanılamaz
−1	404	Sipariş bulunamadı veya başka bir hesaba ait
−1	401	Eksik veya geçersiz API anahtarı ya da IP beyaz listede değil