Crear un pedido

Cada evento de negocio necesita un client_request_id único y estable. Esa es la protección obligatoria contra duplicados en los reintentos de red.

Cuerpo de la petición

{"client_request_id":"order-1042","address":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8","energy":65000,"duration_minutes":60,"expected_total_trx":"3.200000"}

Campo	Tipo	Obligatorio	Descripción
client_request_id	cadena	sí	Tu ID único de la operación. Reutilízalo solo para este mismo pedido.
address	cadena	sí	Dirección de destino de TRON válida.
energy	entero	sí	Cantidad positiva divisible por el tamaño de la porción.
duration_minutes	entero	sí	Duración permitida de las opciones, en minutos.
expected_total_trx	cadena	sí	El total_trx exacto, con seis decimales, de la última cotización.

Las propiedades JSON desconocidas se rechazan. Envía Content-Type: application/json.

Respuesta 201 o 200

{"id":"7c0c9a54-517c-4bbb-a946-bf14bf86c113","client_request_id":"order-1042","address":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8","energy":65000,"duration_minutes":60,"total_trx":"3.200000","status":"created","lifecycle_final":false,"delivery_final":false,"created_at":1784376000,"updated_at":1784376000,"energy_usable":false}

La respuesta trae la forma completa de un pedido, la que describe consultar un pedido, y deja fuera todos los campos que aún no tienen valor: un pedido recién creado no trae la clave rental_expires_at ni la clave failure en vez de traerlas con null.

• 201 Created: un pedido nuevo; Location contiene /v1/energy/orders/{id}.
• 200 OK: una repetición idéntica devolvió el pedido que ya existía.
• 409 Conflict con code: energy_order_idempotency_conflict: el mismo client_request_id se usó con otra dirección, otra cantidad u otra duración.
• 409 Conflict con code: energy_price_changed: pide una cotización nueva y envíalo otra vez. No se creó ningún pedido ni se retuvo ningún TRX.
• 409 Conflict con code: insufficient_balance: el total cotizado supera available_trx. Recarga la cuenta y envíalo otra vez. No se creó ningún pedido ni se retuvo ningún TRX.

Idempotencia

Si se agota el tiempo, no generes un ID nuevo. Repite el mismo cuerpo y el mismo client_request_id. Genera un ID nuevo solo para un evento de negocio nuevo.

Campos de estado

status describe la etapa actual. Tu automatización debe usar lifecycle_final y delivery_final, no una lista de estados fija en el código. Consulta consultar un pedido.

Errores

Los estados posibles son 400, 401, 409, 413, 415, 429, 500 y 503. No reintentes automáticamente un 400, 401, 409, 413 o 415 sin corregir antes la causa.