POST /apiv2/order1h

Otomatik yük devretme özellikli çoklu enerji sağlayıcıları aracılığıyla 1 saatlik enerji kiralama siparişi oluşturun.

Uç Nokta URL'si

POST https://netts.io/apiv2/order1h

İstek Başlıkları

Başlık	Gerekli	Açıklama
Content-Type	Evet	application/json
X-API-KEY	Evet	Netts kontrol panelinizden alınan API anahtarınız
X-Real-IP	Evet	Beyaz listenizdeki IP adresi

İstek Gövdesi

json

{
    "amount": 131000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

Parametreler

Parametre	Tür	Gerekli	Açıklama
amount	integer	Evet	Kiralanacak enerji miktarı (minimum: 61000, maksimum: 3000000)
receiveAddress	string	Evet	Enerjiyi alacak TRON adresi (TRC-20 formatında)

Sağlayıcı Seçimi

API, en uygun enerji sağlayıcısını şu kriterlere göre otomatik olarak seçer:

Maliyet verimliliği - Her zaman mevcut en düşük fiyatı bulur
Kullanılabilirlik - Yeterli enerji rezervinin bulunmasını sağlar
Güvenilirlik - Başarı oranı yüksek sağlayıcıları kullanır
Hız - En hızlı teslimat sürelerine öncelik verir

Örnek İstekler

cURL

bash

curl -X POST https://netts.io/apiv2/order1h \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{
    "amount": 131000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

Python

python

import requests

url = "https://netts.io/apiv2/order1h"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key",
    "X-Real-IP": "your_whitelisted_ip"
}

payload = {
    "amount": 131000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if response.status_code == 200:
    detail = data.get('detail', {})
    order_data = detail.get('data', {})
    print(f"Order ID: {order_data.get('orderId')}")
    print(f"Transaction Hash: {order_data.get('hash')}")
    print(f"Energy Delivered: {order_data.get('energy')}")
    print(f"Cost: {order_data.get('paidTRX')} TRX")
    print(f"Delegate Address: {order_data.get('delegateAddress')}")
else:
    error_detail = data.get('detail', data)
    print(f"Error Code: {error_detail.get('code', 'N/A')}")
    print(f"Error Message: {error_detail.get('msg', error_detail)}")

Yanıt

Başarılı Yanıt (200 OK)

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 2.23 TRX deducted",
        "data": {
            "orderId": "1H123456",
            "paidTRX": 2.23,
            "hash": "a1b2c3d4e5f6789...",
            "delegateAddress": "TDelegatePoolAddress...",
            "energy": 131050
        }
    }
}

Yanıt Alanları

Alan	Tür	Açıklama
detail.code	integer	Başarılı siparişler için her zaman `10000`
detail.msg	string	Kesilen tutarı içeren başarı mesajı
detail.data.orderId	string	Birleşik sipariş kimliği (format: `1H{request_id}`)
detail.data.paidTRX	number	TRX cinsinden toplam maliyet (adres etkinleştirilmemişse etkinleştirme ücretini içerir)
detail.data.hash	string \| null	İşlem karması (hash). Alan her zaman mevcuttur ancak boş olabilir - bazı sağlayıcılar karmayı hemen döndürmez. Karmayı almak için 1 dakika sonra /apiv2/order_check kullanın
detail.data.delegateAddress	string	Enerjiyi delege eden havuz adresi
detail.data.energy	integer	Enerji miktarı + tampon payı (genellikle +50)

Hata Yanıtları

Kimlik Doğrulama Hatası (401)

json

{
    "detail": "Invalid API key or IP not in whitelist"
}

Yetersiz Bakiye (403)

json

{
    "code": 1004,
    "msg": "Insufficient funds. Required: 2.23 TRX, Available: 1.50 TRX"
}

Hizmet Kullanılamıyor (503)

json

{
    "code": 5003,
    "msg": "Service temporarily unavailable. All energy providers are currently unavailable."
}

Sağlayıcı Hataları (503)

json

{
    "code": 5001,
    "msg": "Energy provider temporarily unavailable"
}

json

{
    "code": 5002,
    "msg": "Energy provider temporarily unavailable"
}

json

{
    "code": 5004,
    "msg": "Energy provider requires higher minimum amount"
}

Sunucu İçi Hata (500)

json

{
    "code": 5000,
    "msg": "Internal server error occurred"
}

Hata Kodu Referansı

Kod	Açıklama	HTTP Durumu
`10000`	Başarılı	200
`10000`	Başarılı (önbelleğe alınmış yanıt)	208
`-`	Mükerrer istek halen işleniyor	409
`1004`	Yetersiz bakiye	403
`5000`	Sunucu içi hata	500
`5001`	Enerji sağlayıcı kullanılamıyor	503
`5002`	Enerji sağlayıcı kullanılamıyor	503
`5003`	Enerji hizmeti kullanılamıyor	503
`5004`	Enerji sağlayıcı minimum tutarı karşılanmadı	503

Hız Limitleri

Bu uç nokta için aşağıdaki hız limitleri geçerlidir (IP adresi başına):

Dönem	Limit	Açıklama
1 saniye	50 istek	Saniyede en fazla 50 istek

Hız Limiti Başlıkları

http

RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 49

Hız Limiti Aşıldı (429)

json

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

Eşgüçlülük (Idempotency)

API, mükerrer sipariş işlemlerini önlemek için eşgüçlülüğü destekler. Birden fazla özdeş istek gönderdiğinizde sistem, siparişin yalnızca bir kez işlenmesini sağlar.

Eşgüçlülük Nasıl Çalışır?

İstek benzersizliği aşağıdakilerin birleşimiyle belirlenir:

İstek zaman damgası (1 saniyelik aralık)
Enerji miktarı
Alıcı adresi
API anahtarı

Her isteğe 1 saniyelik bir benzersizlik aralığı tanınır. Sistemi kötüye kullanımdan korumak ve düzgün işlem yapılmasını sağlamak için, aynı parametrelere sahip istekler saniyede birden daha sık gönderilemez.

Mevcut davranış: Sistem, istemcileri zaten sipariş edilmiş enerjiye yönelik hatalı yeniden denemelere karşı otomatik olarak korur. Yanlışlıkla aynı isteği iki kez gönderirseniz, iki kez ücretlendirilmezsiniz.

Kendi Anahtarınızı Belirtme

X-Idempotency-Key başlığını göndererek eşgüçlülük yönetimini kendi elinize alabilirsiniz. Bu başlık mevcut olduğunda, bir isteğin tekrar olup olmadığına yalnızca bu değer karar verir ve yukarıdaki otomatik kombinasyon kullanılmaz. Başlık bulunmadığında hiçbir şey değişmez; sunucu anahtarı sizin için türetir.


Başlık	`X-Idempotency-Key`
Biçim	Tam olarak 64 küçük harfli onaltılık karakter — bir SHA-256 özeti
Geçerlilik Süresi	Bu anahtarı taşıyan ilk istekten itibaren 24 saat
Kapsam	Hesabınız. Başka bir hesap tarafından gönderilen aynı değer asla sizin sonucunuzu döndürmez

Başka herhangi bir yapıdaki anahtar — tireli UUID, base64, büyük harfli onaltılık — sipariş verilmeden ve herhangi bir ücretlendirme yapılmadan önce 400 ile reddedilir:

json

{
    "detail": "Invalid idempotency key format. Must be 64-character hexadecimal string."
}

Biçim diğer uç noktalardan farklıdır. /apiv2/withdraw, /apiv2/bandwidth ve orchestrator 16–64 karakterlik bir base64 anahtarı kabul eder. Bu uç nokta yalnızca 64 karakterlik bir onaltılık özet kabul eder; bu nedenle o uç noktalardan kopyalanan anahtar oluşturma kodu burada 400 hatası döndürür.

Anahtar nasıl oluşturulur?

Anahtarı API anahtarınızdan türetin. Bu, değerin hesabınıza özel olmasını, yeniden denemelerde aynı şekilde üretilebilmesini ve başka hiç kimse tarafından tahmin edilememesini sağlar:

python

import hashlib
import hmac

def make_idempotency_key(api_key: str, address: str, amount: int, nonce: str) -> str:
    message = f"{address}:{amount}:{nonce}"
    return hmac.new(api_key.encode(), message.encode(), hashlib.sha256).hexdigest()

nonce isteğe değil, siparişe aittir. Bunu bir kez, sipariş sizin tarafınızda oluşturulduğunda belirleyin ve bu siparişin her gönderiminde — hem ilk denemede hem de her yeniden denemede — aynı değeri iletin. Gönderme fonksiyonunun içinde yeni bir değer üretmek (her çağrıda str(uuid.uuid4())), her denemeye farklı bir anahtar verir; bu nedenle bir zaman aşımından sonraki yeniden deneme ikinci bir sipariş olarak kabul edilir ve tekrar ücretlendirilir. En basit ve doğru seçenek, zaten elinizde bulunan sipariş kimliğidir: ilk denemeden önce mevcuttur ve sürecinizin yeniden başlatılmasından sonra da korunur.

python

# once, when the order appears in your system
order = create_order(address="TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", amount=131000)

# on the first attempt and on every retry — the same three inputs, the same key
key = make_idempotency_key(API_KEY, order.address, order.amount, order.id)

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": API_KEY,
    "X-Idempotency-Key": key,
}

Bir anahtarın geçerlilik süresi 24 saattir. Bu sürenin ardından aynı nonce serbest kalır ve yeni bir sipariş başlatır.

Başka birinin ulaşabileceği bir değer kullanmayın — 64 adet sıfır, sabit bir kelimenin özeti gibi. Anahtarlar hesaplar arasında ortak bir alanı paylaşır. Böyle bir çakışma başka bir hesabın siparişini asla açığa çıkarmaz, ancak onların anahtarının süresi dolana kadar isteğiniz 409 ile reddedilir; bu da bir yeniden denemenin ortasında almak isteyeceğiniz yanıt değildir.

Birbiriyle Aynı İki Sipariş Verme

Bazen gerçekten aynı siparişi iki kez vermek isteyebilirsiniz — aynı adrese, peş peşe aynı miktarda enerji. Otomatik anahtar bunu bir yeniden denemeden ayırt edemez: iki istek baytına kadar aynıdır ve onları ayıran tek şey varış anlarıdır.

Kendinize ait bir anahtar olmadan sonuç, aralarındaki süre farkına bağlıdır:

İki istek arasındaki süre	Ne olur
Aynı 1 saniyelik aralık içinde	İkinci istek bir tekrar olarak kabul edilir. Yürütülmez: `208` yanıtı ve `orderId` dahil ilk siparişin yanıtını alırsınız. Bunun için hiçbir ücret kesilmez
Bir saniyeden daha uzun arayla	İki farklı anahtar — her iki sipariş de verilir ve her ikisi de ücretlendirilir

Dolayısıyla, otomatik anahtara güveniyorsanız, aynı iki sipariş arasında bir saniyeden fazla süre bırakın ve durum kodunu inceleyin: 208, az önce gönderdiğiniz siparişin verilmediği anlamına gelir.

Bekleme eklemek kalıcı bir çözüm değil, geçici bir önlemdir. Asla tekrarlamak istemediğiniz istekler de dahil olmak üzere her isteği birbirinden ayırır — bir zaman aşımından sonraki yeniden deneme, çift tıklama, kuyruğunuz tarafından yeniden teslim edilen bir mesaj. Bunlar da zaman penceresinden daha geç ulaştığından ayrı siparişler olarak verilir ve ayrı olarak ücretlendirilir. Bu uç noktanın yanıt zaman aşımı süresi 10 saniyedir, bu da zaten pencerenin oldukça dışındadır: otomatik anahtar, bir zaman aşımını izleyen yeniden denemeyi korumaz.

Kendi anahtarınız belirsizliği ortadan kaldırır; çünkü karar, doğru cevabı bilen tek tarafa aktarılır:

Ne yapıyorsunuz	Ne gönderiyorsunuz	Sonuç
İkinci, gerçekten yeni bir sipariş	Yeni bir `nonce`	Yeni bir anahtar — sipariş verilir
Sonucunu bilmediğiniz bir siparişin yeniden denemesi	İlk denemenin `nonce` değeri	Aynı anahtar — `208`, orijinal yanıt, ikinci ücretlendirme yok

İkinci satır, bu başlığın var olma nedenidir ve uygulamaların genellikle hataya düştüğü yerdir: Anahtar nasıl oluşturulur? altındaki nota bakın.

Mükerrer İstekler İçin HTTP Durum Kodları

Durum Kodu	Ad	Açıklama
200	OK	Sipariş başarıyla işlendi (ilk istek)
208	Already Reported	Sipariş zaten işlendi, önbelleğe alınmış yanıt döndürülüyor
409	Conflict	İstek şu anda işleniyor, tekrar denemeyin

Mükerrer İstek - Zaten İşlendi (208)

Zaten tamamlanmış bir sipariş için mükerrer bir istek alındığında:

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 2.54 TRX deducted",
        "data": {
            "hash": "9e4c20e21e01e4c39b21b670d1ea1fc1e4b0de94d8fbd4c190d5378ba911dfae",
            "energy": 65050,
            "orderId": "1H70bcc7962a",
            "paidTRX": 2.535,
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq"
        }
    },
    "idempotency": {
        "status": "completed",
        "cached": true,
        "original_created_at": "2025-12-03T10:34:49.104896"
    }
}

Yanıt gövdesi, orijinal başarılı yanıtla aynıdır ve bunun önbelleğe alınmış bir yanıt olduğunu belirten ek bir idempotency nesnesi içerir.

Mükerrer İstek - Halen İşleniyor (409)

Orijinal istek halen işlenirken mükerrer bir istek geldiğinde:

json

{
    "success": false,
    "error": "duplicate_request_processing",
    "message": "This request is currently being processed. Please wait and do not retry.",
    "idempotency_key": "b9e67b2412d33c92...",
    "retry_after_seconds": 3
}

Öneri: Sipariş durumunu kontrol etmeden önce belirtilen retry_after_seconds süresi kadar bekleyin.

En İyi Uygulamalar

Aynı parametrelerle paralel istekler göndermeyin - her yanıtı bekleyin
Her yeni sipariş için yeni bir nonce, siparişin her yeniden denemesi içinse ilk denemenin nonce değerini kullanın
nonce değerini asla gönderme anında yeniden oluşturmayın — yeniden deneme, yeni bir anahtar değil, ilk denemenin anahtarını tekrar üretmelidir
409 yanıtlarını, hemen tekrar deneyerek değil, bekleyerek yönetin
Önbelleğe alınmış yanıtları tanımlamak için idempotency.cached alanını kontrol edin — bir 208, az önce gönderdiğiniz siparişin verilmediği anlamına gelir

Notlar

Enerji, sipariş başarılı olduğunda anında teslim edilir (genellikle 0,5-10 saniye içinde)
API yanıt zaman aşımı: Maksimum 10 saniye, genellikle en fazla 2 saniye içinde yanıt verir
Adres etkinleştirme: Alıcı adresi etkinleştirilmemişse Netts adresi maliyet fiyatına etkinleştirir
Etkinleştirme gecikmesi: Etkinleştirilmemiş adresler için, etkinleştirme süreci nedeniyle API yanıtı 6 saniyeye kadar sürebilir
Siparişler, otomatik sağlayıcı yük devretme özelliğiyle 7/24 işlenir
Minimum enerji miktarı: 61.000 birim
Maksimum enerji miktarı: Sipariş başına 3.000.000 birim
Enerji tampon payı: Sağlayıcı telafisi için otomatik olarak eklenen +50 birim (ücretsiz)
İşlem karması (hash): Alan her zaman mevcuttur ancak sağlayıcı hemen döndürmezse boş olabilir. Karmayı almak için siparişi verdikten sonra en erken 1 dakika sonra /apiv2/order_check çağrısı yapın
Sağlayıcı seçimi: Maliyet ve kullanılabilirliğe göre otomatik
Sipariş kimliği biçimi: Birleşik izleme için 1H{request_id}
Fiyatlandırma: Günün saatine ve enerji miktarına göre dinamik
Süre: Sabit 1 saat (3600 saniye)
Hız sınırlaması: IP adresi başına saniyede 50 istek

POST /apiv2/order1h ​

Uç Nokta URL'si ​

İstek Başlıkları ​

İstek Gövdesi ​

Parametreler ​

Sağlayıcı Seçimi ​

Örnek İstekler ​

cURL ​

Python ​

Yanıt ​

Başarılı Yanıt (200 OK) ​

Yanıt Alanları ​

Hata Yanıtları ​

Kimlik Doğrulama Hatası (401) ​

Yetersiz Bakiye (403) ​

Hizmet Kullanılamıyor (503) ​

Sağlayıcı Hataları (503) ​

Sunucu İçi Hata (500) ​

Hata Kodu Referansı ​

Hız Limitleri ​

Hız Limiti Başlıkları ​

Hız Limiti Aşıldı (429) ​

Eşgüçlülük (Idempotency) ​

Eşgüçlülük Nasıl Çalışır? ​

Kendi Anahtarınızı Belirtme ​

Anahtar nasıl oluşturulur? ​

Birbiriyle Aynı İki Sipariş Verme ​

Mükerrer İstekler İçin HTTP Durum Kodları ​

Mükerrer İstek - Zaten İşlendi (208) ​

Mükerrer İstek - Halen İşleniyor (409) ​

En İyi Uygulamalar ​

Notlar ​

POST /apiv2/order1h

Uç Nokta URL'si

İstek Başlıkları

İstek Gövdesi

Parametreler

Sağlayıcı Seçimi

Örnek İstekler

cURL

Python

Yanıt

Başarılı Yanıt (200 OK)

Yanıt Alanları

Hata Yanıtları

Kimlik Doğrulama Hatası (401)

Yetersiz Bakiye (403)

Hizmet Kullanılamıyor (503)

Sağlayıcı Hataları (503)

Sunucu İçi Hata (500)

Hata Kodu Referansı

Hız Limitleri

Hız Limiti Başlıkları

Hız Limiti Aşıldı (429)

Eşgüçlülük (Idempotency)

Eşgüçlülük Nasıl Çalışır?

Kendi Anahtarınızı Belirtme

Anahtar nasıl oluşturulur?

Birbiriyle Aynı İki Sipariş Verme

Mükerrer İstekler İçin HTTP Durum Kodları

Mükerrer İstek - Zaten İşlendi (208)

Mükerrer İstek - Halen İşleniyor (409)

En İyi Uygulamalar

Notlar