Orchestrator — pesanan massal dalam satu panggilan

Kirim hingga 100 alamat dalam satu permintaan dan biarkan Netts menjalankan seluruh rangkaian untuk setiap alamat: mengaktifkan alamat jika diperlukan, mengisi bandwidth jika kurang, lalu menyewa energy — membagi jumlah besar menjadi beberapa bagian secara otomatis.

Anda langsung mendapatkan 202 Accepted dengan kunci pelacakan dan tidak perlu menunggu koneksi. Progres kemudian dibaca dari endpoint status.

Mengapa menggunakannya

Memesan energy untuk alamat baru biasanya memerlukan tiga panggilan terpisah, dalam urutan yang tepat, dengan logika percobaan ulang (retry) Anda sendiri di antaranya. Orchestrator menyederhanakan hal tersebut menjadi satu permintaan dan menjalankan rangkaian proses per alamat:

probe → activation (if the address is not active) → bandwidth (if free < 400) → energy

Kegagalan dalam aktivasi atau bandwidth tidak menghentikan pesanan energy untuk alamat tersebut, dan satu alamat yang gagal tidak akan pernah memengaruhi alamat lainnya.

URL dasar endpoint

https://netts.io/apiv2/orchestrator

Header Permintaan

Header	Diperlukan	Deskripsi
Content-Type	Ya	application/json
X-API-KEY	Ya	Kunci API Anda dari dashboard Netts
X-Real-IP	Ya	Alamat IP dari daftar putih (whitelist) Anda
X-Idempotency-Key	Ya*	Kunci Anda untuk pesanan ini, 12–128 karakter berupa A-Z a-z 0-9 . _ : -

* Salah satu dari header X-Idempotency-Key atau bidang clientRequestId di dalam body wajib diisi. Jika Anda tidak mengirimkan keduanya, permintaan akan ditolak dengan 5010.

Kunci tersebut mengidentifikasi seluruh pesanan. Mengulangi permintaan dengan kunci yang sama akan mengembalikan hasil asli alih-alih membuat pesanan kedua — lihat Idempotensi.

---

Membuat pesanan — POST /apiv2/orchestrator

Body permintaan

{
    "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 }
    ]
}

Bidang tingkat atas

Bidang	Tipe	Diperlukan	Deskripsi
items	array	Ya	1 hingga 100 alamat. Duplikat dalam satu pesanan akan ditolak.
clientRequestId	string	Tidak	Referensi pesanan Anda, 8–128 karakter berupa A-Z a-z 0-9 . _ : -. Berfungsi ganda sebagai kunci idempotensi jika header tidak ada.
defaults	object	Tidak	Nilai yang diterapkan ke setiap item yang tidak menggantikannya.

Bidang item

Setiap bidang kecuali receiveAddress dan amount juga dapat diatur di defaults. Nilai pada item lebih diutamakan daripada nilai default.

Bidang	Tipe	Default	Deskripsi
receiveAddress	string	—	Alamat TRON yang menerima energy
amount	int	—	Energy untuk alamat ini, 61 000 … 50 000 000
bandwidth	bool	true	Pesan bandwidth untuk alamat ini jika kurang
bandwidthAmount	int	400	400 atau 5000
bandwidthPeriod	string	1h	5m atau 1h
check	bool	lihat di bawah	Periksa bandwidth gratis terlebih dahulu dan lewati pesanan jika sudah cukup
trx_send	bool	false	Diteruskan ke layanan bandwidth
activation	bool	true	Aktifkan alamat jika belum aktif. Atur ke false untuk melewati langkah ini bagi alamat yang Anda tahu sudah aktif.

check secara default bernilai true ketika bandwidthAmount adalah 400, dan false untuk nilai lainnya — memesan 5 000 unit biasanya berarti Anda menginginkannya terlepas dari apa yang sudah ada.

Jumlah dihitung per alamat. Satu permintaan dapat menggabungkan jumlah yang berbeda secara bebas; satu-satunya batas maksimal adalah total keseluruhan.

Batasan

Batasan	Nilai
Alamat per pesanan	100
Energy per alamat	61 000 … 50 000 000
Total energy per pesanan	50 000 000
Pesanan yang sedang berjalan per akun	3
Alamat yang sedang berjalan per akun	300
Saldo minimum agar diterima	4 TRX

Batas maksimal 50 000 000 berlaku untuk jumlah dari semua alamat dalam permintaan, bukan untuk masing-masing alamat.

Respons — diterima (202, kode 10202)

{
    "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 berarti dimasukkan ke antrean, belum dieksekusi. Belum ada biaya yang dipotong. Lakukan polling pada statusUrl untuk melihat hasilnya.

trackingId adalah pasangan idempotency key + address — identitas dari satu alamat di dalam pesanan Anda. Gunakan ini di log dan rekonsiliasi Anda sendiri.

Contoh

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}
        ]
      }'

---

Memeriksa progres — GET /apiv2/orchestrator/status/{idempotencyKey}

Tambahkan ?address=T… untuk mendapatkan satu alamat saja alih-alih seluruh pesanan.

{
    "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"
                }
            ]
        }
    }
}

Kunci yang tidak dikenal, atau kunci milik akun lain, akan mengembalikan 404.

Nilai status alamat

Status	Arti
queued	Menunggu untuk diproses
processing	Sedang berlangsung
completed	Semua energy yang diminta telah didelegasikan
partial	Beberapa chunk terkirim, beberapa gagal
failed	Tidak ada yang terkirim
insufficient_balance	Dihentikan — saldo Anda turun di bawah batas minimum
credentials_revoked	Kunci API Anda dihapus atau dinonaktifkan saat pesanan sedang berjalan
cancelled	Dihapus dari antrean atas permintaan pembatalan Anda

Nilai status langkah

Langkah	Nilai
activation	not_needed, done, failed, skipped, skipped_unavailable
bandwidth	enough, done, failed, skipped
energy	done, partial, failed

bandwidth.skipReason menjelaskan alasan skipped: option_off (Anda menonaktifkannya), energy_gt_600000 (pesanan energy dalam jumlah besar tidak memerlukan isi ulang bandwidth).

Hash delegasi

energy.hashes adalah bukti pengiriman Anda. Ketika energy berasal dari penyedia eksternal, hash tidak langsung diketahui pada saat pemesanan — hash akan diisi sekitar satu menit kemudian, dan alamat tidak dilaporkan sebagai selesai hingga hash terkumpul atau batas waktu tunggu berakhir. Alamat dengan status completed yang memiliki hash berarti telah diselesaikan sepenuhnya.

---

Membatalkan — POST /apiv2/orchestrator/cancel/{idempotencyKey}

Menghapus dari antrean setiap alamat yang belum mulai diproses.

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

Alamat yang sudah dalam status processing tidak dihentikan: sebagian dari energy mereka mungkin sudah dibayar. Pembatalan dilakukan dengan upaya terbaik (best-effort) pada alamat yang tersisa.

---

Idempotensi

Pesanan diidentifikasi oleh kunci Anda — header X-Idempotency-Key, atau clientRequestId jika header tidak ada.

Permintaan berulang	Hasil
Kunci sama, body sama	208 dengan pesanan asli dan originalAcceptedAt — tidak ada pesanan kedua
Kunci sama, body berbeda	409 4090 IDEMPOTENCY_CONFLICT

Jadi, jika terjadi batas waktu jaringan (timeout) di pihak Anda, permintaan aman untuk dicoba ulang persis sama. Mengubah muatan (payload) dengan kunci yang sudah digunakan akan ditolak, bukan diterapkan secara diam-diam.

Di dalam pesanan, setiap alamat memiliki kunci internalnya sendiri, sehingga pengulangan juga tidak akan pernah menagih ganda satu alamat pun.

---

Penagihan

Orchestrator itu sendiri tidak membebankan biaya apa pun. Setiap langkah ditagih oleh layanan yang menjalankannya, pada harga normalnya:

Langkah	Ditagih sebagai
Aktivasi	pemotongan terpisah, nomor pesanan A…
Bandwidth	pemotongan terpisah, nomor pesanan B1H… — hanya jika benar-benar didelegasikan
Energy	satu pemotongan per chunk, nomor pesanan 1H…

check: true dengan bandwidth gratis yang cukup tidak dikenakan biaya apa pun — statusnya adalah enough dan tidak ada pesanan yang dibuat. Jumlah energy yang besar akan melewati bandwidth sepenuhnya.

Jika saldo Anda habis di tengah proses batch, alamat yang tersisa akan berstatus insufficient_balance tanpa dicoba untuk diproses.

---

Referensi Kode Kesalahan

Kode	Deskripsi	Status HTTP
10202	Pesanan diterima / sudah diterima	202 / 208
10000	Status dikembalikan	200
10005	Pesanan dibatalkan	200
5004	Bidang tidak valid: format alamat, amount di luar rentang, bandwidthAmount bukan 400/5000, bandwidthPeriod bukan 5m/1h, body bukan objek JSON	400
5005	items tidak ada atau kosong	400
5006	Duplikat receiveAddress dalam satu pesanan	400
5009	X-Idempotency-Key atau clientRequestId salah format	400
5010	Baik X-Idempotency-Key maupun clientRequestId tidak disediakan	400
5012	Total energy dalam permintaan melebihi 50 000 000	400
-1	Kunci API tidak valid / IP tidak ada dalam whitelist	401
1004	Saldo di bawah minimum 4 TRX	402
-1	Pesanan tidak ditemukan (atau bukan milik Anda)	404
4090	IDEMPOTENCY_CONFLICT — kunci sama, body berbeda	409
4220	Validasi permintaan gagal (detail di data.errors)	422
429 / 5011	Terlalu banyak pesanan, alamat, atau chunk yang sedang berjalan	429
5003	Pesanan tidak diterima — layanan sementara tidak tersedia, aman untuk dicoba ulang	503

Status 503 saat pembuatan bersifat fail-secure: tidak ada yang disimpan dan tidak ada biaya yang dikenakan.

Batas Laju (Rate Limits)

Dibatasi per IP sumber:

Periode	Batasan
1 detik	20 permintaan

Batas Laju Terlampaui (429)

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

Catatan

• 202 bukan tanda terima pengiriman. Anggap sebagai "masuk antrean". Hasilnya ada di endpoint status.
• Alamat diproses secara paralel, hingga 5 sekaligus dalam satu pesanan, sehingga batch yang besar tidak perlu menunggu satu alamat yang lambat. Urutan penyelesaian tidak dijamin.
• Pembagian chunk dilakukan otomatis: jumlah di atas 1 000 000 dibagi menjadi chunk yang merata, masing-masing menjadi pesanan energy tersendiri. energy.orderIds dan energy.hashes mencantumkan semuanya.
• Tidak ada webhook untuk pesanan orchestrator secara keseluruhan. Setiap delegasi energy tetap menghasilkan webhook delegation.confirmed seperti biasa, lihat Webhook.
• Endpoint terkait: Activator, Bandwidth, Order 1H.