Orchestrator — tek çağrıda toplu siparişler

Tek bir istekte 100 adede kadar adres gönderin ve Netts'in her biri için tüm diziyi yürütmesine izin verin: gerekirse adresi etkinleştirin, eksikse bandwidth miktarını tamamlayın, ardından energy kiralayın — büyük miktarları otomatik olarak parçalara bölün.

Bir takip anahtarı ile anında 202 Accepted yanıtı alırsınız ve bağlantıda asla beklemezsiniz. İlerleme daha sonra durum uç noktasından okunur.

Neden kullanılmalı

Yeni bir adres için energy siparişi vermek normalde, doğru sırada ve aralarında kendi yeniden deneme mantığınızın bulunduğu üç ayrı çağrı gerektirir. Orchestrator bunu tek bir isteğe indirger ve diziyi adres başına çalıştırır:

probe → activation (adres aktif değilse) → bandwidth (boşta olan < 400 ise) → energy

Etkinleştirme veya bandwidth aşamasındaki bir başarısızlık, o adres için energy siparişini durdurmaz ve bir adresin başarısız olması diğerlerini asla etkilemez.

Uç nokta temel URL'si

https://netts.io/apiv2/orchestrator

İ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
X-Idempotency-Key	Evet*	Bu sipariş için anahtarınız, `A-Z a-z 0-9 . _ : -` karakterlerinden oluşan 12–128 karakter

* X-Idempotency-Key başlığı veya gövdedeki clientRequestId alanından biri gereklidir. İkisini de göndermezseniz, istek 5010 ile reddedilir.

Anahtar, siparişin tamamını tanımlar. Aynı anahtarla bir isteğin tekrarlanması, ikinci bir sipariş oluşturmak yerine orijinal sonucu döndürür — bkz. Tekrarlanabilirlik (Idempotency).

Sipariş oluşturma — `POST /apiv2/orchestrator`

İstek gövdesi

json

{
    "clientRequestId": "my-batch-2026-01-01-001",
    "defaults": {
        "bandwidth": true,
        "bandwidthAmount": 400,
        "bandwidthPeriod": "1h",
        "check": true,
        "trx_send": false
    },
    "items": [
        { "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", "amount": 65000 },
        { "receiveAddress": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "amount": 131000 },
        { "receiveAddress": "TYYyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy", "amount": 61000, "bandwidth": false }
    ]
}

Üst düzey alanlar

Alan	Tür	Gerekli	Açıklama
`items`	array	Evet	1 ila 100 adres. Tek bir sipariş içindeki mükerrer kayıtlar reddedilir.
`clientRequestId`	string	Hayır	Sipariş referansınız, `A-Z a-z 0-9 . _ : -` karakterlerinden oluşan 8–128 karakter. Başlık yoksa idempotency anahtarı işlevi de görür.
`defaults`	object	Hayır	Bunları geçersiz kılmayan her bir öğeye uygulanan değerler.

Öğe alanları

receiveAddress ve amount dışındaki her alan defaults altında da ayarlanabilir. Öğe üzerindeki bir değer, varsayılan değere göre önceliklidir.

Alan	Tür	Varsayılan	Açıklama
`receiveAddress`	string	—	Energy alacak TRON adresi
`amount`	int	—	Bu adres için Energy, 61 000 … 50 000 000
`bandwidth`	bool	`true`	Yetersiz olduğunda bu adres için Bandwidth siparişi ver
`bandwidthAmount`	int	`400`	`400` veya `5000`
`bandwidthPeriod`	string	`1h`	`5m` veya `1h`
`check`	bool	aşağıya bakın	Önce boşta olan Bandwidth miktarını kontrol et ve yeterli varsa siparişi atla
`trx_send`	bool	`false`	Bandwidth servisine doğrudan iletilir
`activation`	bool	`true`	Aktif değilse adresi etkinleştir. Zaten aktif olduğunu bildiğiniz bir adres için bu adımı atlamak üzere `false` olarak ayarlayın.

check, bandwidthAmount değeri 400 olduğunda varsayılan olarak true, aksi takdirde false olur — 5 000 birim sipariş etmek genellikle halihazırda ne olduğuna bakılmaksızın bunları istediğiniz anlamına gelir.

Miktarlar adres başınadır. Tek bir istek, farklı miktarları serbestçe harmanlayabilir; tek üst sınır toplam miktardır.

Limitler

Limit	Değer
Sipariş başına adres	100
Adres başına Energy	61 000 … 50 000 000
Sipariş başına toplam Energy	50 000 000
Hesap başına işlemdeki siparişler	3
Hesap başına işlemdeki adresler	300
Kabul edilmek için minimum bakiye	4 TRX

50 000 000 üst sınırı her bir adres için değil, istekteki tüm adreslerin toplamı için geçerlidir.

Yanıt — kabul edildi (202, kod `10202`)

json

{
    "detail": {
        "code": 10202,
        "status": "accepted",
        "msg": "Order accepted for processing",
        "data": {
            "idempotencyKey": "my-batch-2026-01-01-001",
            "requestId": 1234,
            "itemsAccepted": 3,
            "statusUrl": "/apiv2/orchestrator/status/my-batch-2026-01-01-001",
            "items": [
                {
                    "deliveryKey": 5001,
                    "trackingId": "my-batch-2026-01-01-001:TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "amount": 65000,
                    "energyChunks": 1,
                    "activation": "planned",
                    "bandwidth": "planned",
                    "status": "queued"
                }
            ]
        }
    }
}

202, yürütüldü değil, sıraya alındı anlamına gelir. Henüz hiçbir ücret tahsil edilmemiştir. Sonuç için statusUrl adresini sorgulayın.

trackingId, idempotency anahtarı + adres ikilisidir — siparişinizdeki tek bir adresin kimliğidir. Kendi günlüklerinizde ve mutabakatınızda bunu kullanın.

Örnek

bash

curl -X POST https://netts.io/apiv2/orchestrator \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -H "X-Idempotency-Key: my-batch-2026-01-01-001" \
  -d '{
        "items": [
          {"receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", "amount": 65000}
        ]
      }'

İlerlemeyi kontrol etme — `GET /apiv2/orchestrator/status/{idempotencyKey}`

Tüm sipariş yerine tek bir adresi almak için ?address=T… ekleyin.

json

{
    "detail": {
        "code": 10000,
        "status": "processing",
        "data": {
            "idempotencyKey": "my-batch-2026-01-01-001",
            "requestId": 1234,
            "clientRequestId": "my-batch-2026-01-01-001",
            "summary": {
                "total": 3, "queued": 1, "processing": 1, "completed": 1,
                "partial": 0, "failed": 0, "insufficient_balance": 0,
                "credentials_revoked": 0, "cancelled": 0
            },
            "items": [
                {
                    "deliveryKey": 5001,
                    "trackingId": "my-batch-2026-01-01-001:TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "status": "completed",
                    "energy": {
                        "requested": 65000,
                        "delegated": 65000,
                        "status": "done",
                        "chunks": { "total": 1, "done": 1 },
                        "orderIds": ["1Hxxxxxxxxxx"],
                        "hashes": ["0000000000000000000000000000000000000000000000000000000000000000"]
                    },
                    "activation": { "status": "not_needed", "orderId": null, "hash": null },
                    "bandwidth": {
                        "status": "enough", "orderId": "B1Hxxxxxxxxxxxxxx",
                        "amount": 400, "period": "1h", "hashes": [], "skipReason": null
                    },
                    "attempts": 1,
                    "startedAt": "2026-01-01T00:00:00+00:00",
                    "finishedAt": "2026-01-01T00:00:03+00:00"
                }
            ]
        }
    }
}

Bilinmeyen bir anahtar veya başka bir hesaba ait olan bir anahtar 404 döndürür.

Adres durum değerleri

Durum	Anlamı
`queued`	İşleme alınmayı bekliyor
`processing`	Devam ediyor
`completed`	İstenen tüm Energy delege edildi
`partial`	Bazı parçalar teslim edildi, bazıları başarısız oldu
`failed`	Hiçbir şey teslim edilmedi
`insufficient_balance`	Durduruldu — bakiyeniz minimum tutarın altına düştü
`credentials_revoked`	Sipariş çalışırken API anahtarınız kaldırıldı veya devre dışı bırakıldı
`cancelled`	İptal talebinizle kuyruktan kaldırıldı

Adım durum değerleri

Adım	Değerler
`activation`	`not_needed`, `done`, `failed`, `skipped`, `skipped_unavailable`
`bandwidth`	`enough`, `done`, `failed`, `skipped`
`energy`	`done`, `partial`, `failed`

bandwidth.skipReason, bir skipped durumunu açıklar: option_off (devre dışı bıraktınız), energy_gt_600000 (büyük Energy siparişleri bir Bandwidth takviyesine ihtiyaç duymaz).

Delegasyon karmaları (hashes)

energy.hashes teslimat kanıtınızdır. Energy harici bir sağlayıcıdan geldiğinde karma sipariş anında bilinmez — yaklaşık bir dakika sonra doldurulur ve karmalar toplanana ya da bekleme penceresi sona erene kadar adres tamamlandı olarak bildirilmez. Karma değeri mevcut olan completed durumundaki bir adres tamamen sonuçlandırılmıştır.

İptal etme — `POST /apiv2/orchestrator/cancel/{idempotencyKey}`

Henüz işleme alınmamış her adresi kuyruktan kaldırır.

json

{
    "detail": {
        "code": 10005,
        "status": "cancelled",
        "msg": "Order cancelled: 7 addresses removed from queue",
        "data": { "cancelled": 7 }
    }
}

Zaten processing durumunda olan adresler kesintiye uğratılmaz: Energy miktarlarının bir kısmı için zaten ödeme yapılmış olabilir. İptal işlemi, geri kalan kısım için elden gelen en iyi çaba ilkesiyle (best-effort) çalışır.

Tekrarlanabilirlik (Idempotency)

Sipariş, anahtarınız tarafından tanımlanır — X-Idempotency-Key başlığı veya başlık olmadığında clientRequestId.

Tekrarlanan istek	Sonuç
Aynı anahtar, aynı gövde	Orijinal sipariş ve `originalAcceptedAt` ile 208 — ikinci bir sipariş oluşturulmaz
Aynı anahtar, farklı gövde	409 `4090 IDEMPOTENCY_CONFLICT`

Bu nedenle, tarafınızdaki bir ağ zaman aşımında aynı isteği birebir yeniden denemek güvenlidir. Zaten kullanılmış bir anahtar altındaki yükü değiştirmek, sessizce uygulanmak yerine reddedilir.

Sipariş içinde her adres kendi dahili anahtarını taşır, bu nedenle bir tekrar asla tek bir adresten çift ücret alınmasına da yol açmaz.

Faturalandırma

Orchestrator'ın kendisi hiçbir ücret talep etmez. Her adım, işlemi gerçekleştiren servis tarafından kendi normal fiyatı üzerinden faturalandırılır:

Adım	Faturalandırma biçimi
Activation	ayrı kesinti, sipariş numarası `A…`
Bandwidth	ayrı kesinti, sipariş numarası `B1H…` — yalnızca fiilen delege edildiğinde
Energy	parça başına bir kesinti, sipariş numarası `1H…`

Yeterli boş Bandwidth varken check: true hiçbir maliyet getirmez — durum enough olur ve sipariş verilmez. Büyük Energy miktarları Bandwidth adımını tamamen atlar.

Bakiyeniz toplu işlemin ortasında biterse, kalan adresler denenmeden insufficient_balance olarak sonuçlanır.

Hata Kodu Referansı

Kod	Açıklama	HTTP Durumu
`10202`	Sipariş kabul edildi / zaten kabul edildi	202 / 208
`10000`	Durum döndürüldü	200
`10005`	Sipariş iptal edildi	200
`5004`	Geçersiz alan: adres biçimi, `amount` aralık dışında, `bandwidthAmount` 400/5000 değil, `bandwidthPeriod` 5m/1h değil, gövde bir JSON nesnesi değil	400
`5005`	`items` eksik veya boş	400
`5006`	Tek bir siparişte mükerrer `receiveAddress`	400
`5009`	Hatalı biçimlendirilmiş `X-Idempotency-Key` veya `clientRequestId`	400
`5010`	Ne `X-Idempotency-Key` ne de `clientRequestId` sağlandı	400
`5012`	İstekteki toplam Energy 50 000 000 sınırını aşıyor	400
`-1`	Geçersiz API anahtarı / IP beyaz listede değil	401
`1004`	Bakiye 4 TRX minimum tutarının altında	402
`-1`	Sipariş bulunamadı (veya size ait değil)	404
`4090`	`IDEMPOTENCY_CONFLICT` — aynı anahtar, farklı gövde	409
`4220`	İstek doğrulaması başarısız oldu (ayrıntılar `data.errors` içinde)	422
`429` / `5011`	İşlemde çok fazla sipariş, adres veya parça var	429
`5003`	Sipariş kabul edilmedi — servis geçici olarak kullanılamıyor, yeniden denemek güvenlidir	503

Oluşturma sırasındaki bir 503 güvenli başarısızlıktır (fail-secure): hiçbir şey depolanmadı ve hiçbir ücret tahsil edilmedi.

İstek Limitleri (Rate Limits)

Kaynak IP başına sınırlandırılmıştır:

Dönem	Limit
1 saniye	20 istek

İstek Limiti Aşıldı (429)

json

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

Notlar

202 bir teslimat makbuzu değildir. Bunu "sıraya alındı" olarak kabul edin. Sonuç, durum uç noktasında yer alır.
Adresler paralel olarak çalışır, tek bir sipariş içinde aynı anda en fazla 5 adet çalışır, böylece büyük bir grup tek bir yavaş adres yüzünden beklemez. Tamamlanma sırası garanti edilmez.
Parçalara ayırma (chunking) otomatiktir: 1 000 000 üzerindeki miktarlar eşit parçalara bölünür ve her biri kendi Energy siparişi haline gelir. energy.orderIds ve energy.hashes bunların tümünü listeler.
Bir bütün olarak orchestrator siparişleri için webhook yoktur. Her Energy delegasyonu yine de alışılagelmiş delegation.confirmed webhook'unu üretir, bkz. Webhooks.
İlgili uç noktalar: Activator, Bandwidth, Order 1H.

Orchestrator — tek çağrıda toplu siparişler ​

Neden kullanılmalı ​

Uç nokta temel URL'si ​

İstek Başlıkları ​

Sipariş oluşturma — POST /apiv2/orchestrator ​

İstek gövdesi ​

Üst düzey alanlar ​

Öğe alanları ​

Limitler ​

Yanıt — kabul edildi (202, kod 10202) ​

Örnek ​

İlerlemeyi kontrol etme — GET /apiv2/orchestrator/status/{idempotencyKey} ​

Adres durum değerleri ​

Adım durum değerleri ​

Delegasyon karmaları (hashes) ​

İptal etme — POST /apiv2/orchestrator/cancel/{idempotencyKey} ​

Tekrarlanabilirlik (Idempotency) ​

Faturalandırma ​

Hata Kodu Referansı ​

İstek Limitleri (Rate Limits) ​

İstek Limiti Aşıldı (429) ​

Notlar ​

Orchestrator — tek çağrıda toplu siparişler

Neden kullanılmalı

Uç nokta temel URL'si

İstek Başlıkları

Sipariş oluşturma — `POST /apiv2/orchestrator`

İstek gövdesi

Üst düzey alanlar

Öğe alanları

Limitler

Yanıt — kabul edildi (202, kod `10202`)

Örnek

İlerlemeyi kontrol etme — `GET /apiv2/orchestrator/status/{idempotencyKey}`

Adres durum değerleri

Adım durum değerleri

Delegasyon karmaları (hashes)

İptal etme — `POST /apiv2/orchestrator/cancel/{idempotencyKey}`

Tekrarlanabilirlik (Idempotency)

Faturalandırma

Hata Kodu Referansı

İstek Limitleri (Rate Limits)

İstek Limiti Aşıldı (429)

Notlar