API documentație

Procedura de cumpărare a energiei

Pentru a cumpăra energie, trebuie să vă înregistrați în serviciul EnergyFather, să luați tokenul de autorizare de pe pagina "Cumpărător > API tokens" și să completați soldul contului Cumpărătorului.

După crearea unei comenzi (metoda ‘buy/energy’), energia poate fi livrată cu o întârziere de câteva secunde sau chiar minute, astfel încât, atunci când dezvoltați sisteme automate, este recomandat să verificați periodic executarea comenzii prin solicitarea metodei ‘order/get/{guid}’.

De exemplu, dacă intenționați să trimiteți USDT și doriți să faceți tranzacțiile mai ieftine prin achiziționarea de energie, procedați în felul următor:

• solicitați metoda ‘buy/energy’ pentru a estima cantitatea de energie necesară și pentru a o cumpăra,
• solicită periodic metoda ‘order/get/{guid}’ până când energia este delegată (de obicei durează câteva secunde),
• trimite USDT (energia achiziționată va fi utilizată pentru a plăti taxa de tranzacție).

Note generale

În această documentație, o expresie inclusă între paranteze ca ‘{guid}’ sau ‘{id}’ înseamnă valoarea variabilei corespunzătoare:

• ‘{guid}’ este identificatorul unic global al obiectului în EnergyFather (de obicei 8 cifre),
• ‘{id}’ este numărul secvențial al obiectului pentru acest utilizator (numerotarea începe cu ‘1’ pentru fiecare utilizator).

API Punct final

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

Trimiteți cererile folosind metoda POST.

Autorizarea cererilor

Pentru a confirma (autoriza) cererile către un API privat, trebuie transmis un antet HTTP:

Token: {token}

Gestionarea jetoanelor de autorizare se află în panoul de control, pe pagina "Cumpărător > API jetoane".

De exemplu, puteți obține informații despre comanda 123456 în felul următor:

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

Stadiul comenzii

• "0" - În așteptare. Comanda tocmai a fost creată.
• "1" - Așteaptă plata. Legătura de plată a fost deja generată, EnergyFather este în așteptarea unui apel de la sistemul de plată. Acest statut nu este utilizat dacă comanda este plătită integral din fondurile disponibile în contul intern.
• "2" - Procedura de delegare a energiei este în curs de desfășurare.
• "3" - Delegat. Energia este dată afară.
• "4" - Revendicat (Nelegat). Energia este retrasă ca urmare a încheierii perioadei de timp plătite.
• "5" - Plătită. Comanda este plătită și adăugată în coada de așteptare pentru livrarea de energie.
• "6" - Eroare.

Secvența obișnuită de statusuri: 0, 5, 2, 3, 4.

Metoda "buy/energy" - cumpărați energie (plătită din contul intern)

Cerere de cumpărare a energiei de către un client înregistrat cu debit din contul intern. Energia este trimisă imediat la adresa specificată.

Dacă contul intern are fonduri insuficiente, comanda va fi creată și va primi instantaneu statutul "6" (eroare). În acest caz, trebuie să vizitați panoul, să depuneți niște fonduri și apoi să trimiteți o nouă cerere API pentru cumpărarea de energie.

Există două modalități de definire a cantității de energie care urmează să fie achiziționată:

a) Puteți seta cantitatea exactă de energie în parametrul "amount", apoi ar trebui să setați și amount_source="amount".

b) Dacă nu știți câtă energie este necesară pentru ca o tranzacție să trimită USDT sau un alt token, puteți seta amount_source="estimate" și completa parametrii corespunzători (estimate_to, estimate_token, estimate_adjust_percent).

buy/energy: Exemplu de cerere cu cantitatea exactă de energie

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: Exemplu de cerere cu calcularea cantității de energie necesare

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: Parame de cerere

• to (string, obligatoriu) - TRON adresa la care urmează să fie delegată energia
• period_amount (număr întreg, obligatoriu) - perioada de timp pentru achiziționarea energiei
• period_type (string, obligatoriu) - tipul de perioadă de timp. Valori posibile: days, hours.
• format (string, opțional) - formatul răspunsului. Valori posibile: json (default), xml.
• amount_source (string, obligatoriu) - algoritm pentru determinarea cantității de energie delegată. Dacă valoarea este "amount", atunci se utilizează valoarea parametrului "amount". Dacă valoarea este "estimate", cantitatea de energie necesară este calculată pe baza parametrilor estimate_to, estimate_token, estimate_adjust_percent. Valori posibile: amount, estimate.
• amount (număr întreg, obligatoriu dacă amount_source="amount") - cantitatea de energie care urmează să fie achiziționată. Este ignorată dacă amount_source="estimate".
• estimate_to (string, obligatoriu dacă amount_source="estimate") - listă separată prin virgulă de adrese TRON la care se intenționează trimiterea tranzacțiilor cu jetoane
• estimate_token (string, obligatoriu dacă amount_source="estimate") - simbolul TRC20. Valori posibile (sensibile la majuscule): USDT, USDC, USDD, USDJ, JST, TUSD, stUSDT, WTRX.
• estimate_adjust_percent (zecimală, obligatorie dacă amount_source="estimate") - cantitatea de energie în exces exprimată ca procent. Acest exces este necesar pentru a evita arderea TRX, care se poate întâmpla dacă adresa are exact cantitatea de energie necesară. Valoarea recomandată este 0.04%.

Important: În prezent, sunt valabile doar 6 perioade: 1 hour și 1, 3, 7, 15, 30 days.

buy/energy: Răspuns

În caz de succes, răspunsul va conține comanda GUID, prin care puteți obține ulterior detaliile sale reale.

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

Dacă cererea conține amount_source="estimate", atunci răspunsul are o secțiune suplimentară "estimate_task". De exemplu:

{
	"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: Parame de răspuns

• guid - ordinea GUID
• balance - fonduri disponibile în prezent în contul intern, TRX
• days - durata furnizării de energie în zile, dacă "period_type=days"
• hours - durata furnizării de energie în ore, dacă "period_type=hours"
• estimate_task - calcularea (estimarea) energiei necesare pentru trimiterea tranzacțiilor TRC20 de la o adresă TRON la lista de alte adrese TRON

Metoda "order/get/{guid}" - obținerea detaliilor comenzii

Obținerea de informații despre comanda specifică.

order/get/{guid} - Exemplu de cerere

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

order/get/{guid} - Exemplu de răspuns

{
	"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} - Parame de răspuns

• guid - ordinea GUID
• balance - fonduri disponibile în prezent în contul intern, TRX
• days - durata furnizării de energie în zile, dacă "period_type=days"
• hours - durata furnizării de energie în ore, dacă "period_type=hours"
• to - TRX adresa la care este livrată energia
• energy_amount - cantitate de energie
• order_cost - costul comenzii, TRX
• order_cost_paid - suma deja plătită, TRX (în caz de fonduri insuficiente în contul intern, această sumă va fi mai mică decât "order_cost")
• address_activation_fee - valoarea taxei pentru activarea adresei de destinație, TRX
• energy_delegation_fee - taxă pentru o comandă prea mică, TRX
• resource_txs - array care conține lista tranzacțiilor din blockchain-ul TRON în care resursele sunt delegate și revendicate (nedelegate)
• status - starea comenzii, valorile posibile sunt descrise la începutul acestui manual
• payment_status - starea plății comenzii în sistemul de plată (valorile posibile depind de sistemul de plată)

Metoda "order/list" - obținerea listei de comenzi

Obținerea listei de comenzi.

order/list - Exemplu de cerere

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

order/list - Parame de cerere

• sort (string, opțional) - sortarea intrărilor, implicit "created_at|desc"
• per_page (număr întreg, opțional) - limitează numărul de intrări per răspuns
• page (număr întreg, opțional) - numărul secvențial al paginii de răspuns
• filter (matrice de arrays(objects), opțional) - filtru de intrări

order/list - Exemplu de răspuns

{
	"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 - Parame de răspuns

• guid - GUID al comenzii
• status - starea răspunsului API

Metoda "account/list" - listarea conturilor interne

Obținerea unei liste a conturilor interne, inclusiv suma fondurilor disponibile în prezent. Deoarece există un cont intern separat pentru fiecare secțiune a site-ului (buyer, affiliate, seller, dealer), există mai multe conturi în cont.

account/list - Exemplu de cerere

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

account/list - Exemplu de răspuns

{
	"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 - Parame de răspuns

• guid - GUID a contului intern
• id - secvențial ID al contului intern
• section - secțiunea EnergyFather din care face parte acest sold
• balance - fonduri disponibile
• currency - monedă
• user_id - GUID al utilizatorului

Metoda "account/get/{id}" - obținerea contului intern exact

Obținerea soldului contului intern pentru o anumită secțiune a EnergyFather. Deoarece fiecare secțiune are propriul său cont (buyer, affiliate, seller, dealer), există mai multe conturi pentru fiecare utilizator. Puteți utiliza mai întâi metoda "account/list" pentru a obține lista acestora, pentru a afla ‘id’ contului de interes și apoi pentru a utiliza acest ‘id’ pentru a obține soldul unui anumit cont.

account/get/{id} - Exemplu de cerere

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

account/get/{id} - Exemplu de răspuns

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

account/get/{id} - Parame de răspuns

• guid - GUID a contului intern
• id - ID secvențial al contului intern
• section - secțiunea EnergyFather din care face parte acest sold
• balance - fonduri disponibile
• currency - monedă
• user_id - GUID al utilizatorului