API documentație

Procedura de cumpărare a energiei

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

După crearea unui ordin (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 ordinului 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, faceți următoarele:

• 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ți USDT (energia achiziționată va fi utilizată pentru a plăti taxa de tranzacție).

Note generale

În această documentație, o expresie cuprinsă î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 este localizată î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șteptăm plata. Legătura de plată a fost deja generată, EnergyFather așteaptă un apel înapoi de la sistemul de plată. Acest statut nu este utilizat în cazul în care 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 distribuită.
• "4" - Recuperată (nedelegată). 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 trebuie 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 jeton, 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) - Adresa TRON la care trebuie 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) - algoritmul 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, doar 6 perioade sunt valabile: 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 - ordinul GUID
• balance - fonduri disponibile în prezent în contul intern, TRX
• days - durata furnizării energiei în zile, dacă "period_type=days"
• hours - durata furnizării de energie în ore, dacă "period_type=hours"
• estimate_task - calculul (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 - ordinul GUID
• balance - fonduri disponibile în prezent în contul intern, TRX
• days - durata furnizării energiei î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 dimensiune prea mică a comenzii, TRX
• resource_txs - matrice 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 - situația răspunsului API

Metoda "account/list" - listarea conturilor interne

Obținerea unei liste a conturilor interne, inclusiv valoarea 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 din contul intern
• id - ID secvențial al contului intern
• section - la care secțiune EnergyFather aparține acest sold
• balance - Fonduri disponibile
• currency - valută
• user_id - GUID ale 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 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’ al 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 din contul intern
• id - ID secvențial al contului intern
• section - secțiunea EnergyFather din care face parte acest sold
• balance - Fonduri disponibile
• currency - valută
• user_id - GUID ale utilizatorului