Documentazione API

Procedura di acquisto di energia

Per acquistare energia, è necessario registrarsi al servizio EnergyFather, ottenere il token di autorizzazione dalla pagina "Acquirente > token API" e ricaricare il saldo del conto dell'acquirente.

Dopo la creazione di un ordine (metodo ‘buy/energy’) l'energia può essere consegnata con un ritardo di alcuni secondi o addirittura di minuti, pertanto nello sviluppo di sistemi automatici si raccomanda di controllare periodicamente l'esecuzione dell'ordine richiedendo il metodo ‘order/get/{guid}’.

Ad esempio, se si intende inviare USDT e si desidera rendere le transazioni più economiche acquistando energia, si procede come segue:

• richiedere il metodo ‘buy/energy’ per stimare la quantità di energia necessaria e acquistarla,
• richiede periodicamente il metodo ‘order/get/{guid}’ finché l'energia non viene delegata (di solito ci vogliono alcuni secondi),
• inviare USDT (l'energia acquistata verrà utilizzata per pagare la commissione di transazione).

Note generali

In questa documentazione, un'espressione racchiusa tra parentesi graffe come ‘{guid}’ o ‘{id}’ indica il valore della variabile corrispondente:

• ‘{guid}’ è l'identificatore univoco globale dell'oggetto in EnergyFather (di solito 8 cifre),
• ‘{id}’ è il numero sequenziale dell'oggetto per questo utente (la numerazione inizia con ‘1’ per ogni utente).

API Punto finale

https://panel.energyfather.com/api/v1/private

Inviare le richieste con il metodo POST.

Autorizzazione delle richieste

Per confermare (autorizzare) le richieste a un API privato, si deve passare un'intestazione HTTP:

Token: {token}

La gestione dei gettoni di autorizzazione si trova nel pannello di controllo, alla pagina "Acquirente > Gettoni API".

Ad esempio, è possibile ottenere informazioni sull'ordine 123456 nel modo seguente:

CURL -X POST 'https://panel.energyfather.com/api/v1/private/order/get/123456' 
-H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS'

Stato dell'ordine

• "0" - In attesa. L'ordine è stato appena creato.
• "1" - In attesa del pagamento. Il link di pagamento è già stato generato, EnergyFather è in attesa di un richiamo dal sistema di pagamento. Questo stato non viene utilizzato se l'ordine viene pagato interamente con fondi disponibili sul conto interno.
• "2" - La procedura di delega energetica è in corso.
• "3" - Delegato. L'energia viene distribuita.
• "4" - Recupero (non delegato). L'energia viene ritirata a causa della fine del periodo di tempo pagato.
• "5" - Pagato. L'ordine è stato pagato e aggiunto alla coda di consegna dell'energia.
• "6" - Errore.

La consueta sequenza di stati: 0, 5, 2, 3, 4.

Il metodo "buy/energy" - acquistare energia (pagata dal conto interno)

Richiesta di acquisto di energia da parte di un cliente registrato con addebito sul conto interno. L'energia viene immediatamente inviata all'indirizzo specificato.

Se il conto interno non ha fondi sufficienti, l'ordine viene creato e ottiene immediatamente lo stato "6" (errore). In questo caso è necessario visitare il pannello, depositare dei fondi e poi inviare una nuova richiesta API per l'acquisto di energia.

Esistono due modi per definire la quantità di energia da acquistare:

a) È possibile impostare la quantità esatta di energia nel parametro "amount", quindi è necessario impostare anche amount_source="amount".

b) Se non si conosce la quantità di energia necessaria a una transazione per inviare USDT o un altro token, è possibile impostare amount_source="estimate" e compilare i parametri appropriati (estimate_to, estimate_token, estimate_adjust_percent).

buy/energy: esempio di richiesta con quantità esatta di energia

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/buy/energy' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS' 
  -d '{
    "format": "json",
    "to":     "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
    "amount_source": "amount", 
    "amount": "31895",
    "period_type": "days",
    "period_amount": "3"
}'

buy/energy: Esempio di richiesta con calcolo della quantità di energia necessaria

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/buy/energy' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS' 
  -d '{
    "format": "json",
    "to":     "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
    "amount_source": "estimate", 
    "estimate_to": "TLVkYEp4Ue2RpK5v1XNZAB3769g44BSZyH,TJm6HiCMVZdBHbNHThdMv1RambstJPrfYo",
    "estimate_token": "USDT",
    "estimate_adjust_percent": 0.04,
    "period_type": "days",
    "period_amount": "3"
}'

buy/energy: parametri della richiesta

• to (stringa, obbligatorio) - Indirizzo TRON a cui deve essere delegata l'energia.
• period_amount (intero, obbligatorio) - periodo di acquisto dell'energia
• period_type (stringa, obbligatorio) - tipo di periodo di tempo. Valori possibili: days, hours.
• format (stringa, opzionale) - formato della risposta. Valori possibili: json (default), xml.
• amount_source (stringa, obbligatorio) - algoritmo per determinare la quantità di energia delegata. Se il valore è "amount", viene utilizzato il valore del parametro "amount". Se il valore è "estimate", la quantità di energia necessaria viene calcolata in base ai parametri estimate_to, estimate_token, estimate_adjust_percent. Valori possibili: amount, estimate.
• amount (intero, obbligatorio se amount_source="amount") - quantità di energia da acquistare. Viene ignorato se amount_source="estimate".
• estimate_to (stringa, obbligatorio se amount_source="estimate") - elenco separato da virgole degli indirizzi TRON a cui si prevede di inviare le transazioni con token
• estimate_token (stringa, obbligatoria se amount_source="estimate") - il token TRC20. Valori possibili (sensibili alle maiuscole): USDT, USDC, USDD, USDJ, JST, TUSD, stUSDT, WTRX.
• estimate_adjust_percent (decimale, obbligatorio se amount_source="estimate") - quantità di energia in eccesso espressa in percentuale. Questo eccesso è necessario per evitare la combustione di TRX, che potrebbe verificarsi se l'indirizzo ha esattamente la quantità di energia necessaria. Il valore consigliato è 0.04%.

Importante: attualmente sono validi solo 6 periodi: 1 hour e 1, 3, 7, 15, 30 days.

buy/energy: Risposta

In caso di successo, la risposta conterrà l'ordine GUID, grazie al quale sarà possibile ottenere in seguito i dettagli effettivi.

{
	"status": "ok",
	"data": {
		"guid": 81373165,
		"estimate_task_id": null,
		"status": 0,
		"order_cost": "6.051",
		"to": "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
		"energy_amount": 61000,
		"period_type": "hours",
		"energy_delegation_fee": "0.561000000000000000",
		"address_activation_fee": "0.000000000000000000",
		"hours": 1,
		"days": 0,
		"estimate_task": null
	},
	"balance": "7.29412"
}

Se la richiesta contiene amount_source="estimate", la risposta ha una sezione aggiuntiva "estimate_task". Ad esempio:

{
	"status": "ok",
	"data": {
		"guid": 77082757,
		"estimate_task_id": 42708906,
		"status": 0,
		"order_cost": "0.561",
		"to": "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
		"energy_amount": null,
		"period_type": "hours",
		"energy_delegation_fee": "0.561000000000000000",
		"address_activation_fee": "0.000000000000000000",
		"hours": 1,
		"days": 0,
		"estimate_task": {
			"id": 42708906,
			"token": "USDT",
			"currency": "USD",
			"from": "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
			"to": [
				"TLVkYEp4Ue2RpK5v1XNZAB3769g44BSZyH",
				"TJm6HiCMVZdBHbNHThdMv1RambstJPrfYo"
			]
		}
	},
	"balance": "18.29412"
}

buy/energy: Parametri della risposta

• guid - l'ordine GUID
• balance - fondi attualmente disponibili sul conto interno, TRX
• days - durata della fornitura di energia in giorni, se "period_type=days"
• hours - durata della fornitura di energia in ore, se "period_type=hours"
• estimate_task - calcolo (stima) dell'energia necessaria per l'invio di transazioni TRC20 da un indirizzo TRON all'elenco di altri indirizzi TRON

Il metodo "order/get/{guid}" - ottenere i dettagli dell'ordine

Ottenere informazioni sull'ordine specifico.

order/get/{guid} - Richiesta di esempio

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/order/get/12345' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS'

order/get/{guid} - Esempio di risposta

{
	"status": "ok",
	"data": {
		"guid": 81373165,
		"estimate_task_id": 32301594,
		"status": 3,
		"payment_status": 0,
		"order_cost_paid": "4.146350000000000000",
		"order_cost": "4.146350000000000000",
		"to": "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
		"energy_amount": 31895,
		"period_type": "hours",
		"energy_delegation_fee": "0.000000000000000000",
		"address_activation_fee": "0.000000000000000000",
		"hours": 1,
		"days": 0,
		"resource_txs": [
			{
				"order_guid": 81373165,
				"delegate_txid": "961b6fbd7cc2090d1a65abc06bfabde1046e02d35394f6eca8d05812a6e3ab7"
			}
		],
		"estimate_task": {
			"id": 42708906,
			"token": "USDT",
			"currency": "USD",
			"from": "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
			"to": [
				"TLVkYEp4Ue2RpK5v1XNZAB3769g44BSZyH",
				"TJm6HiCMVZdBHbNHThdMv1RambstJPrfYo"
			]
		}
	}
}

order/get/{guid} - Parametri della risposta

• guid - l'ordine GUID
• balance - fondi attualmente disponibili sul conto interno, TRX
• days - durata della fornitura di energia in giorni, se "period_type=days"
• hours - durata della fornitura di energia in ore, se "period_type=hours"
• to - TRX indirizzo di fornitura dell'energia
• energy_amount - quantità di energia
• order_cost - costo dell'ordine, TRX
• order_cost_paid - importo già pagato, TRX (in caso di fondi insufficienti sul conto interno questo importo sarà inferiore a "order_cost")
• address_activation_fee - importo della tariffa per l'attivazione dell'indirizzo di destinazione, TRX
• energy_delegation_fee - tassa per ordine troppo piccolo, TRX
• resource_txs - array contenente l'elenco delle transazioni nella blockchain TRON in cui le risorse sono delegate e reclamate (non delegate)
• status - stato dell'ordine, i valori possibili sono descritti all'inizio di questo manuale
• payment_status - stato di pagamento dell'ordine nel sistema di pagamento (i valori possibili dipendono dal sistema di pagamento)

Il metodo "order/list": ottenere l'elenco degli ordini

Ottenere l'elenco degli ordini.

order/list - Esempio di richiesta

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/order/list' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS'

order/list - Richiesta di parametri

• sort (stringa, opzionale) - ordinamento delle voci, per impostazione predefinita "created_at|desc"
• per_page (intero, facoltativo) - limita il numero di voci per risposta
• page (intero, opzionale) - numero sequenziale della pagina di risposta
• filter (array di arrays(objects), facoltativo) - filtro di voci

order/list - Esempio di risposta

{
	"current_page": 1,
	"data": [
		{
			"guid": 96134274,
			"status": 4
		},
		{
			"guid": 81373165,
			"status": 3
		}
	],
	"first_page_url": "/api/v1/private/order/list?page=1",
	"from": 1,
	"last_page": 1,
	"last_page_url": "/api/v1/private/order/list?page=1",
	"links": [
		{
			"url": null,
			"label": "pagination.previous",
			"active": false
		},
		{
			"url": "/api/v1/private/order/list?page=1",
			"label": "1",
			"active": true
		},
		{
			"url": null,
			"label": "pagination.next",
			"active": false
		}
	],
	"next_page_url": null,
	"path": "/api/v1/private/order/list",
	"per_page": 15,
	"prev_page_url": null,
	"to": 2,
	"total": 2,
	"draw": null,
	"status": "ok"
}

order/list - Parametri della risposta

• guid - GUID dell'ordine
• status - Stato della risposta API

Il metodo "account/list" - elenco dei conti interni

Ottenere un elenco dei conti interni, compreso l'ammontare dei fondi attualmente disponibili. Poiché esiste un conto interno separato per ogni sezione del sito (buyer, affiliate, seller, dealer), ci sono più conti nel conto.

account/list - Esempio di richiesta

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/account/list' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS'

account/list - Esempio di risposta

{
	"current_page": 1,
	"data": [
		{
			"guid": 29778748,
			"user_id": 81841325,
			"id": 1,
			"section": "affiliate",
			"currency": "TRX",
			"balance": "2.511531"
		},
		{
			"guid": 64463815,
			"user_id": 81841325,
			"id": 2,
			"section": "buyer",
			"currency": "TRX",
			"balance": "41.704"
		}
	],
	"first_page_url": "/api/v1/private/account/list?page=1",
	"from": 1,
	"last_page": 1,
	"last_page_url": "/api/v1/private/account/list?page=1",
	"links": [
		{
			"url": null,
			"label": "pagination.previous",
			"active": false
		},
		{
			"url": "/api/v1/private/account/list?page=1",
			"label": "1",
			"active": true
		},
		{
			"url": null,
			"label": "pagination.next",
			"active": false
		}
	],
	"next_page_url": null,
	"path": "/api/v1/private/account/list",
	"per_page": 15,
	"prev_page_url": null,
	"to": 2,
	"total": 2,
	"draw": null,
	"status": "ok"
}

account/list - Parametri della risposta

• guid - GUID del conto interno
• id - ID sequenziale del conto interno
• section - a quale sezione EnergyFather appartiene questo saldo
• balance - fondi disponibili
• currency - valuta
• user_id - GUID dell'utente

Il metodo "account/get/{id}" - per ottenere il conto interno esatto

Ottenere il saldo del conto interno di una specifica sezione di EnergyFather. Poiché ogni sezione ha il proprio conto (buyer, affiliate, seller, dealer), esistono diversi conti per ogni utente. È possibile utilizzare il metodo "account/list" per ottenere l'elenco dei conti, scoprire il ‘id’ del conto di interesse e utilizzare questo ‘id’ per ottenere il saldo di un determinato conto.

account/get/{id} - Richiesta di esempio

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/account/get/1' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS'

account/get/{id} - Esempio di risposta

{
	"status": "ok",
	"data": {
		"guid": 64463815,
		"user_id": 81841325,
		"id": 2,
		"section": "buyer",
		"currency": "TRX",
		"balance": "41.704"
	}
}

account/get/{id} - Parametri della risposta

• guid - GUID del conto interno
• id - ID sequenziale del conto interno
• section - a quale sezione EnergyFather appartiene questo saldo
• balance - fondi disponibili
• currency - valuta
• user_id - GUID dell'utente