Orchestrator — คำสั่งซื้อแบบกลุ่มในครั้งเดียว

ส่งที่อยู่ได้สูงสุด 100 รายการในคำขอเดียว และให้ Netts จัดการลำดับขั้นตอนทั้งหมดสำหรับแต่ละรายการ: เปิดใช้งานที่อยู่หากจำเป็น, เติม Bandwidth หากไม่เพียงพอ, จากนั้นเช่า Energy — พร้อมแบ่ง จำนวนมากออกเป็นส่วนย่อยให้อัตโนมัติ

คุณจะได้รับ 202 Accepted พร้อมคีย์สำหรับติดตามผลทันทีโดยไม่ต้องรอค้างการเชื่อมต่อ จากนั้น สามารถอ่านความคืบหน้าได้จากเอนด์พอยต์แสดงสถานะ

เหตุผลที่ควรใช้

โดยปกติแล้ว การสั่งซื้อ Energy สำหรับที่อยู่ใหม่ต้องใช้การเรียก API แยกกันสามครั้ง ตามลำดับที่ถูกต้อง และ ต้องมีลอจิกการลองใหม่ของคุณเองระหว่างขั้นตอน Orchestrator จะรวมขั้นตอนเหล่านั้นไว้ในคำขอเดียวและดำเนิน การตามลำดับสำหรับแต่ละที่อยู่:

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

ความล้มเหลวในการเปิดใช้งานหรือ Bandwidth จะไม่หยุดคำสั่งซื้อ Energy สำหรับที่อยู่นั้น และความล้มเหลวของ ที่อยู่รายการหนึ่งจะไม่ส่งผลกระทบต่อรายการอื่น

URL ฐานของเอนด์พอยต์

https://netts.io/apiv2/orchestrator

ส่วนหัวของคำขอ

ส่วนหัว	จำเป็น	คำอธิบาย
Content-Type	ใช่	application/json
X-API-KEY	ใช่	คีย์ API ของคุณจากแดชบอร์ด Netts
X-Real-IP	ใช่	ที่อยู่ IP จากไวท์ลิสต์ของคุณ
X-Idempotency-Key	ใช่*	คีย์ของคุณสำหรับคำสั่งซื้อนี้ ความยาว 12–128 อักขระจาก `A-Z a-z 0-9 . _ : -`

* ต้องระบุส่วนหัว X-Idempotency-Key หรือฟิลด์ clientRequestId ในเนื้อหาคำขออย่างใดอย่างหนึ่ง หากคุณไม่ระบุทั้งสองอย่าง คำขอจะถูกปฏิเสธด้วยรหัส 5010

คีย์นี้ใช้ระบุคำสั่งซื้อทั้งหมด การส่งคำขอซ้ำด้วยคีย์เดิมจะส่งคืนผลลัพธ์เดิม แทนที่จะสร้างคำสั่งซื้อที่สอง — ดูที่ ความสามารถในการทำซ้ำ (Idempotency)

สร้างคำสั่งซื้อ — `POST /apiv2/orchestrator`

เนื้อหาคำขอ

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

ฟิลด์ระดับบนสุด

ฟิลด์	ประเภท	จำเป็น	คำอธิบาย
`items`	array	ใช่	1 ถึง 100 ที่อยู่ รายการที่ซ้ำกันในคำสั่งซื้อเดียวกันจะถูกปฏิเสธ
`clientRequestId`	string	ไม่	ข้อมูลอ้างอิงคำสั่งซื้อของคุณ ความยาว 8–128 อักขระจาก `A-Z a-z 0-9 . _ : -` ใช้เป็นคีย์ความสามารถในการทำซ้ำได้หากไม่มีส่วนหัว
`defaults`	object	ไม่	ค่าที่นำไปใช้กับทุกรายการที่ไม่ได้เขียนทับค่าเหล่านี้

ฟิลด์ของแต่ละรายการ

ทุกฟิลด์ยกเว้น receiveAddress และ amount สามารถกำหนดใน defaults ได้เช่นกัน โดยค่าที่กำหนดในรายการ จะมีผลเหนือกว่าค่าเริ่มต้น

ฟิลด์	ประเภท	ค่าเริ่มต้น	คำอธิบาย
`receiveAddress`	string	—	ที่อยู่ TRON ที่รับ Energy
`amount`	int	—	Energy สำหรับที่อยู่นี้, 61 000 … 50 000 000
`bandwidth`	bool	`true`	สั่งซื้อ Bandwidth สำหรับที่อยู่นี้เมื่อมีไม่เพียงพอ
`bandwidthAmount`	int	`400`	`400` หรือ `5000`
`bandwidthPeriod`	string	`1h`	`5m` หรือ `1h`
`check`	bool	ดูด้านล่าง	ตรวจสอบ Bandwidth ที่ฟรีก่อน และข้ามการสั่งซื้อหากมีเพียงพอแล้ว
`trx_send`	bool	`false`	ส่งต่อไปยังบริการ Bandwidth
`activation`	bool	`true`	เปิดใช้งานที่อยู่หากยังไม่ได้เปิดใช้งาน ตั้งค่าเป็น `false` เพื่อข้ามขั้นตอนนี้สำหรับที่อยู่ที่คุณทราบว่าเปิดใช้งานอยู่แล้ว

check มีค่าเริ่มต้นเป็น true เมื่อ bandwidthAmount คือ 400 และเป็น false ในกรณีอื่นๆ — การสั่งซื้อ 5 000 หน่วยมักหมายถึงคุณต้องการใช้งานโดยไม่คำนึงถึงสิ่งที่มีอยู่แล้ว

จำนวนจะคิดแยกตามที่อยู่ คำขอเดียวสามารถรวมจำนวนที่แตกต่างกันได้อย่างอิสระ โดยมีขีดจำกัดเพียงแค่ ยอดรวมทั้งหมด

ขีดจำกัด

ขีดจำกัด	ค่า
ที่อยู่ต่อคำสั่งซื้อ	100
Energy ต่อที่อยู่	61 000 … 50 000 000
Energy รวมต่อคำสั่งซื้อ	50 000 000
คำสั่งซื้อที่กำลังดำเนินการต่อบัญชี	3
ที่อยู่ที่กำลังดำเนินการต่อบัญชี	300
ยอดคงเหลือขั้นต่ำที่ยอมรับได้	4 TRX

เพดาน 50 000 000 จะใช้กับผลรวมของทุกที่อยู่ในคำขอ ไม่ใช่สำหรับแต่ละรายการ

การตอบกลับ — ยอมรับแล้ว (202, รหัส `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 หมายถึง เข้าคิวแล้ว แต่ยังไม่ได้ดำเนินการ ยังไม่มีการเรียกเก็บเงิน ตรวจสอบ statusUrl เป็นระยะเพื่อดูผลลัพธ์

trackingId คือคู่ของ คีย์ความสามารถในการทำซ้ำ + ที่อยู่ — ข้อมูลระบุตัวตนของที่อยู่หนึ่งรายการภายใน คำสั่งซื้อของคุณ ใช้ค่านี้ในบันทึกและการตรวจสอบยอดของคุณเอง

ตัวอย่าง

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

ตรวจสอบความคืบหน้า — `GET /apiv2/orchestrator/status/{idempotencyKey}`

เพิ่ม ?address=T… เพื่อดูเฉพาะที่อยู่เดียวแทนที่จะเป็นทั้งคำสั่งซื้อ

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

หากไม่พบคีย์ หรือคีย์เป็นของบัญชีอื่น จะส่งคืนรหัส 404

ค่าสถานะของที่อยู่

สถานะ	ความหมาย
`queued`	กำลังรอการประมวลผล
`processing`	อยู่ระหว่างดำเนินการ
`completed`	มอบสิทธิ์ Energy ตามที่ขอทั้งหมดเรียบร้อยแล้ว
`partial`	ส่งมอบบางส่วนสำเร็จ และบางส่วนล้มเหลว
`failed`	ไม่มีการส่งมอบใดๆ สำเร็จ
`insufficient_balance`	หยุดการทำงาน — ยอดคงเหลือของคุณลดลงต่ำกว่าขั้นต่ำ
`credentials_revoked`	คีย์ API ของคุณถูกลบหรือปิดใช้งานขณะที่คำสั่งซื้อกำลังทำงาน
`cancelled`	นำออกจากคิวตามคำขอยกเลิกของคุณ

ค่าสถานะของขั้นตอน

ขั้นตอน	ค่า
`activation`	`not_needed`, `done`, `failed`, `skipped`, `skipped_unavailable`
`bandwidth`	`enough`, `done`, `failed`, `skipped`
`energy`	`done`, `partial`, `failed`

bandwidth.skipReason อธิบายเหตุผลของ skipped: option_off (คุณปิดใช้งานตัวเลือกนี้), energy_gt_600000 (คำสั่งซื้อ Energy จำนวนมากไม่จำเป็นต้องเติม Bandwidth)

แฮชการมอบสิทธิ์

energy.hashes คือหลักฐานการส่งมอบของคุณ เมื่อ Energy มาจากผู้ให้บริการภายนอก จะยังไม่ทราบแฮช ในเวลาที่สั่งซื้อ — แฮชจะถูกกรอกข้อมูลในอีกประมาณหนึ่งนาทีต่อมา และจะยังไม่รายงานว่าที่อยู่นั้น เสร็จสิ้นจนกว่าจะรวบรวมแฮชได้หรือหมดเวลาการรอ ที่อยู่ในสถานะ completed ที่มีแฮชปรากฏอยู่ถือว่าดำเนินการเสร็จสมบูรณ์แล้ว

ยกเลิก — `POST /apiv2/orchestrator/cancel/{idempotencyKey}`

นำทุกที่อยู่ที่ยังไม่ถูกหยิบไปประมวลผลออกจากคิว

json

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

ที่อยู่อยู่ในสถานะ processing แล้วจะไม่ถูกขัดจังหวะ เนื่องจาก Energy บางส่วนของที่อยู่เหล่านั้นอาจได้รับการชำระเงิน ไปแล้ว การยกเลิกจะเป็นแบบพยายามทำให้ดีที่สุด (best-effort) สำหรับส่วนที่เหลือ

ความสามารถในการทำซ้ำ (Idempotency)

คำสั่งซื้อจะถูกระบุด้วยคีย์ของคุณ — ส่วนหัว X-Idempotency-Key หรือ clientRequestId เมื่อไม่มี ส่วนหัวดังกล่าว

คำขอซ้ำ	ผลลัพธ์
คีย์เดิม, เนื้อหาเดิม	208 พร้อมคำสั่งซื้อเดิมและ `originalAcceptedAt` — ไม่มีการสร้างคำสั่งซื้อที่สอง
คีย์เดิม, เนื้อหาต่างกัน	409 `4090 IDEMPOTENCY_CONFLICT`

ดังนั้น การหมดเวลาของเครือข่าย (timeout) ฝั่งคุณจึงสามารถลองใหม่ด้วยข้อมูลเดิมได้อย่างปลอดภัย การเปลี่ยนแปลงเพย์โหลดภายใต้คีย์ ที่ใช้งานไปแล้วจะถูกปฏิเสธแทนที่จะนำไปปรับใช้เงียบๆ

ภายในคำสั่งซื้อ แต่ละที่อยู่จะมีคีย์ภายในของตัวเอง ดังนั้นการทำซ้ำจะไม่เรียกเก็บเงินซ้ำกับ ที่อยู่รายการเดียวเช่นกัน

การเรียกเก็บเงิน

ตัว Orchestrator เองไม่มีการคิดค่าบริการ แต่ละขั้นตอนจะถูกเรียกเก็บเงินโดยบริการที่ดำเนินการตาม ราคาปกติของบริการนั้นๆ:

ขั้นตอน	เรียกเก็บเป็น
Activation	หักเงินแยกต่างหาก, หมายเลขคำสั่งซื้อ `A…`
Bandwidth	หักเงินแยกต่างหาก, หมายเลขคำสั่งซื้อ `B1H…` — เฉพาะเมื่อมีการมอบสิทธิ์จริงเท่านั้น
Energy	หักเงินหนึ่งครั้งต่อหนึ่งส่วนย่อย, หมายเลขคำสั่งซื้อ `1H…`

check: true ที่มี Bandwidth ฟรีเพียงพอจะไม่มีค่าใช้จ่าย — สถานะจะเป็น enough และไม่มีการส่งคำสั่งซื้อ จำนวน Energy ขนาดใหญ่จะข้าม Bandwidth โดยสิ้นเชิง

หากยอดคงเหลือของคุณหมดลงระหว่างการประมวลผลกลุ่ม ที่อยู่ที่เหลือจะจบลงด้วยสถานะ insufficient_balance โดย ไม่ถูกพยายามดำเนินการ

การอ้างอิงรหัสข้อผิดพลาด

รหัส	คำอธิบาย	สถานะ HTTP
`10202`	ยอมรับคำสั่งซื้อแล้ว / เคยยอมรับแล้ว	202 / 208
`10000`	ส่งคืนสถานะแล้ว	200
`10005`	ยกเลิกคำสั่งซื้อแล้ว	200
`5004`	ฟิลด์ไม่ถูกต้อง: รูปแบบที่อยู่, `amount` อยู่นอกช่วง, `bandwidthAmount` ไม่ใช่ 400/5000, `bandwidthPeriod` ไม่ใช่ 5m/1h, เนื้อหาคำขอไม่ใช่ออบเจกต์ JSON	400
`5005`	ไม่มี `items` หรือว่างเปล่า	400
`5006`	มี `receiveAddress` ซ้ำกันในคำสั่งซื้อเดียว	400
`5009`	รูปแบบ `X-Idempotency-Key` หรือ `clientRequestId` ไม่ถูกต้อง	400
`5010`	ไม่ได้ระบุทั้ง `X-Idempotency-Key` และ `clientRequestId`	400
`5012`	Energy รวมในคำขอเกิน 50 000 000	400
`-1`	คีย์ API ไม่ถูกต้อง / IP ไม่อยู่ในไวท์ลิสต์	401
`1004`	ยอดคงเหลือต่ำกว่าขั้นต่ำ 4 TRX	402
`-1`	ไม่พบคำสั่งซื้อ (หรือไม่ใช่ของคุณ)	404
`4090`	`IDEMPOTENCY_CONFLICT` — คีย์เดิม แต่เนื้อหาคำขอต่างกัน	409
`4220`	การตรวจสอบคำขอล้มเหลว (ดูรายละเอียดใน `data.errors`)	422
`429` / `5011`	มีคำสั่งซื้อ, ที่อยู่ หรือส่วนย่อยที่กำลังดำเนินการอยู่มากเกินไป	429
`5003`	คำสั่งซื้อไม่ได้รับการยอมรับ — บริการไม่พร้อมใช้งานชั่วคราว สามารถลองใหม่ได้อย่างปลอดภัย	503

รหัส 503 เมื่อสร้างคำสั่งซื้อเป็นแบบปลอดภัยเมื่อล้มเหลว (fail-secure): ไม่มีการบันทึกข้อมูลและไม่มีการเรียกเก็บเงิน

ขีดจำกัดอัตราการเรียกใช้

จำกัดต่อ IP ต้นทาง:

ช่วงเวลา	ขีดจำกัด
1 วินาที	20 คำขอ

เกินขีดจำกัดอัตราการเรียกใช้ (429)

json

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

หมายเหตุ

202 ไม่ใช่ใบเสร็จการส่งมอบ ให้ถือว่าอยู่ในสถานะ "เข้าคิวแล้ว" ผลลัพธ์จะแสดงในเอนด์พอยต์สถานะ
ที่อยู่จะประมวลผลแบบขนานกัน สูงสุด 5 รายการพร้อมกันภายในหนึ่งคำสั่งซื้อ ดังนั้นชุดข้อมูลขนาดใหญ่จึงไม่ต้องรอ ที่อยู่เดียวที่ประมวลผลช้า ไม่รับประกันลำดับการเสร็จสิ้น
การแบ่งส่วนย่อยเป็นไปโดยอัตโนมัติ: จำนวนที่มากกว่า 1 000 000 จะถูกแบ่งออกเป็นส่วนย่อยๆ เท่ากัน โดยแต่ละส่วนจะกลายเป็น คำสั่งซื้อ Energy ของตัวเอง energy.orderIds และ energy.hashes จะแสดงรายการทั้งหมดเหล่านั้น
ไม่มีเว็บฮุกสำหรับคำสั่งซื้อ Orchestrator ในภาพรวม การมอบสิทธิ์ Energy แต่ละรายการจะยังคงสร้างเว็บฮุก delegation.confirmed ตามปกติ โปรดดูที่ เว็บฮุก
เอนด์พอยต์ที่เกี่ยวข้อง: Activator, Bandwidth, Order 1H

Orchestrator — คำสั่งซื้อแบบกลุ่มในครั้งเดียว ​

เหตุผลที่ควรใช้ ​

URL ฐานของเอนด์พอยต์ ​

ส่วนหัวของคำขอ ​

สร้างคำสั่งซื้อ — POST /apiv2/orchestrator ​

เนื้อหาคำขอ ​

ฟิลด์ระดับบนสุด ​

ฟิลด์ของแต่ละรายการ ​

ขีดจำกัด ​

การตอบกลับ — ยอมรับแล้ว (202, รหัส 10202) ​

ตัวอย่าง ​

ตรวจสอบความคืบหน้า — GET /apiv2/orchestrator/status/{idempotencyKey} ​

ค่าสถานะของที่อยู่ ​

ค่าสถานะของขั้นตอน ​

แฮชการมอบสิทธิ์ ​

ยกเลิก — POST /apiv2/orchestrator/cancel/{idempotencyKey} ​

ความสามารถในการทำซ้ำ (Idempotency) ​

การเรียกเก็บเงิน ​

การอ้างอิงรหัสข้อผิดพลาด ​

ขีดจำกัดอัตราการเรียกใช้ ​

เกินขีดจำกัดอัตราการเรียกใช้ (429) ​

หมายเหตุ ​

Orchestrator — คำสั่งซื้อแบบกลุ่มในครั้งเดียว

เหตุผลที่ควรใช้

URL ฐานของเอนด์พอยต์

ส่วนหัวของคำขอ

สร้างคำสั่งซื้อ — `POST /apiv2/orchestrator`

เนื้อหาคำขอ

ฟิลด์ระดับบนสุด

ฟิลด์ของแต่ละรายการ

ขีดจำกัด

การตอบกลับ — ยอมรับแล้ว (202, รหัส `10202`)

ตัวอย่าง

ตรวจสอบความคืบหน้า — `GET /apiv2/orchestrator/status/{idempotencyKey}`

ค่าสถานะของที่อยู่

ค่าสถานะของขั้นตอน

แฮชการมอบสิทธิ์

ยกเลิก — `POST /apiv2/orchestrator/cancel/{idempotencyKey}`

ความสามารถในการทำซ้ำ (Idempotency)

การเรียกเก็บเงิน

การอ้างอิงรหัสข้อผิดพลาด

ขีดจำกัดอัตราการเรียกใช้

เกินขีดจำกัดอัตราการเรียกใช้ (429)

หมายเหตุ