API dokumentácia

Postup nákupu energie

Ak chcete nakupovať energiu, musíte sa zaregistrovať v službe EnergyFather, zobrať autorizačný token zo stránky "Kupujúci > API tokeny" a doplniť zostatok na účte kupujúceho.

Po vytvorení objednávky (metóda ‘buy/energy’) môže byť energia dodaná s oneskorením niekoľkých sekúnd alebo dokonca minút, preto sa pri vývoji automatizovaných systémov odporúča pravidelne kontrolovať vykonanie objednávky pomocou metódy ‘order/get/{guid}’.

Ak napríklad plánujete poslať USDT a chcete zlacniť transakcie nákupom energie, urobíte nasledovné:

• požiadať o metódu ‘buy/energy’ na odhad potrebného množstva energie a jej nákup,
• pravidelne žiadať ‘order/get/{guid}’ metódu, kým nie je energia delegovaná (zvyčajne to trvá niekoľko sekúnd),
• poslať USDT (zakúpená energia sa použije na zaplatenie transakčného poplatku).

Všeobecné poznámky

V tejto dokumentácii výraz zabalený do kučeravých zátvoriek ako ‘{guid}’ alebo ‘{id}’ znamená hodnotu príslušnej premennej:

• ‘{guid}’ je globálny jedinečný identifikátor objektu v EnergyFather (zvyčajne 8 číslic),
• ‘{id}’ je poradové číslo objektu pre tohto používateľa (číslovanie začína ‘1’ pre každého používateľa).

API Koncový bod

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

Požiadavky posielajte pomocou metódy POST.

Autorizácia žiadostí

Na potvrdenie (autorizáciu) požiadaviek na súkromné API by sa mala odovzdať hlavička HTTP:

Token: {token}

Správa autorizačných tokenov sa nachádza v ovládacom paneli na stránke "Kupujúci > API tokeny".

Napríklad informácie o objednávke 123456 môžete získať nasledujúcim spôsobom:

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

Stav objednávky

• "0" - Čaká na vybavenie. Objednávka bola práve vytvorená.
• "1" - Čakáme na platbu. Platobný odkaz už bol vygenerovaný, EnergyFather čaká na spätné volanie z platobného systému. Tento stav sa nepoužíva, ak je objednávka hradená výlučne z prostriedkov dostupných na internom účte.
• "2" - Prebieha postup delegovania energie.
• "3" - Delegované. Energia sa odovzdáva.
• "4" - Reclaimed (Undelegated). Energia je stiahnutá z dôvodu ukončenia zaplateného časového obdobia.
• "5" - Platené. Objednávka je zaplatená a zaradená do frontu na dodávku energie.
• "6" - Chyba.

Obvyklá postupnosť stavov: 0, 5, 2, 3, 4.

Metóda "buy/energy" - nákup energie (platba z interného účtu)

Žiadosť registrovaného zákazníka o nákup energie s odpísaním z interného účtu. Energia sa okamžite odošle na zadanú adresu.

Ak interný účet nemá dostatok prostriedkov, objednávka sa vytvorí a okamžite dostane stav "6" (Chyba). V takom prípade musíte navštíviť panel, vložiť nejaké prostriedky a potom poslať novú požiadavku API na nákup energie.

Existujú dva spôsoby, ako definovať množstvo energie, ktoré sa má nakúpiť:

a) V parametri "amount" môžete nastaviť presné množstvo energie, potom by ste mali nastaviť aj amount_source="amount".

b) Ak neviete, koľko energie je potrebné na odoslanie transakcie USDT alebo iného tokenu, môžete nastaviť amount_source="estimate" a vyplniť príslušné parametre (estimate_to, estimate_token, estimate_adjust_percent).

buy/energy: Príklad požiadavky s presným množstvom 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: Príklad požiadavky s výpočtom potrebného množstva energie

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: Požiadavka params

• to (reťazec, povinné) - TRON adresa, na ktorú sa má energia delegovať
• period_amount (celé číslo, povinné) - časové obdobie nákupu energie
• period_type (reťazec, povinné) - typ časového obdobia. Možné hodnoty: days, hours.
• format (reťazec, nepovinné) - formát odpovede. Možné hodnoty: json (default), xml.
• amount_source (reťazec, povinné) - algoritmus na určenie množstva delegovanej energie. Ak je hodnota "amount", použije sa hodnota parametra "amount". Ak je hodnota "estimate", požadované množstvo energie sa vypočíta na základe parametrov estimate_to, estimate_token, estimate_adjust_percent. Možné hodnoty: amount, estimate.
• amount (celé číslo, povinné, ak amount_source="amount") - množstvo nakupovanej energie. Ignoruje sa, ak je amount_source="estimate".
• estimate_to (reťazec, povinný, ak amount_source="estimate") - čiarou oddelený zoznam TRON adries, na ktoré sa plánujú posielať tokenové transakcie
• estimate_token (reťazec, povinný, ak amount_source="estimate") - token TRC20. Možné hodnoty (rozlišuje sa veľkosť písmen): USDT, USDC, USDD, USDJ, JST, TUSD, stUSDT, WTRX.
• estimate_adjust_percent (desatinné číslo, povinné, ak amount_source="estimate") - množstvo prebytočnej energie vyjadrené v percentách. Tento prebytok je potrebný, aby nedošlo k spáleniu TRX, čo sa môže stať, ak má adresa presne potrebné množstvo energie. Odporúčaná hodnota je 0.04%.

Dôležité: V súčasnosti je platných len 6 období: 1 hour a 1, 3, 7, 15, 30 days.

buy/energy: Odpoveď

V prípade úspechu bude odpoveď obsahovať objednávku GUID, pomocou ktorej môžete neskôr získať jej aktuálne údaje.

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

Ak žiadosť obsahuje amount_source="estimate", potom odpoveď obsahuje dodatočnú časť "estimate_task". Napríklad:

{
	"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: Parametre odpovede

• guid - objednávka GUID
• balance - finančné prostriedky, ktoré sú aktuálne k dispozícii na internom účte, TRX
• days - dĺžka poskytovania energie v dňoch, ak "period_type=days"
• hours - trvanie dodávky energie v hodinách, ak "period_type=hours"
• estimate_task - výpočet (odhad) energie potrebnej na odoslanie TRC20 transakcií z jednej TRON adresy do zoznamu iných TRON adries

Metóda "order/get/{guid}" - získanie podrobností o objednávke

Získanie informácií o konkrétnej objednávke.

order/get/{guid} - Príklad žiadosti

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

order/get/{guid} - Príklad odpovede

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

• guid - objednávka GUID
• balance - finančné prostriedky, ktoré sú aktuálne k dispozícii na internom účte, TRX
• days - dĺžka poskytovania energie v dňoch, ak "period_type=days"
• hours - trvanie dodávky energie v hodinách, ak "period_type=hours"
• to - TRX adresa, na ktorú sa dodáva energia
• energy_amount - množstvo energie
• order_cost - náklady na objednávku, TRX
• order_cost_paid - už zaplatená suma, TRX (v prípade nedostatku finančných prostriedkov na internom účte bude táto suma nižšia ako "order_cost")
• address_activation_fee - výška poplatku za aktiváciu cieľovej adresy, TRX
• energy_delegation_fee - poplatok za príliš malú veľkosť objednávky, TRX
• resource_txs - pole obsahujúce zoznam transakcií v TRON blockchaine, kde sú zdroje delegované a vrátené (undelegated)
• status - stav objednávky, možné hodnoty sú opísané na začiatku tejto príručky
• payment_status - stav platby príkazu v platobnom systéme (možné hodnoty závisia od platobného systému)

Metóda "order/list" - získanie zoznamu objednávok

Získanie zoznamu objednávok.

order/list - Príklad žiadosti

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

order/list - Parametre požiadavky

• sort (reťazec, nepovinné) - triedenie záznamov, predvolene "created_at|desc"
• per_page (celé číslo, nepovinné) - obmedzenie počtu záznamov v jednej odpovedi
• page (celé číslo, nepovinné) - poradové číslo stránky s odpoveďou
• filter (pole arrays(objects), nepovinné) - filter záznamov

order/list - Príklad odpovede

{
	"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 - Parametre odpovede

• guid - GUID objednávky
• status - stav odpovede API

Metóda "account/list" - výpis interných účtov

Získanie zoznamu interných účtov vrátane výšky aktuálne dostupných finančných prostriedkov. Keďže pre každú časť stránky existuje samostatný interný účet (buyer, affiliate, seller, dealer), v účte je viacero účtov.

account/list - Príklad žiadosti

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

account/list - Príklad odpovede

{
	"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 - Parametre odpovede

• guid - GUID interného účtu
• id - postupnosť ID interného účtu
• section - do ktorej sekcie EnergyFather tento zostatok patrí
• balance - dostupné finančné prostriedky
• currency - mena
• user_id - GUID používateľa

Metóda "account/get/{id}" - získanie presného interného účtu

Získanie zostatku interného účtu pre konkrétnu časť EnergyFather. Keďže každá sekcia má svoj vlastný účet (buyer, affiliate, seller, dealer), pre každého používateľa existuje niekoľko účtov. Najprv môžete pomocou metódy "account/list" získať ich zoznam, zistiť ‘id’ účtu, ktorý vás zaujíma, a potom pomocou tohto ‘id’ získať zostatok konkrétneho účtu.

account/get/{id} - Príklad žiadosti

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

account/get/{id} - Príklad odpovede

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

account/get/{id} - Parametre odpovede

• guid - GUID interného účtu
• id - poradové číslo interného účtu
• section - do ktorej sekcie EnergyFather tento zostatok patrí
• balance - dostupné finančné prostriedky
• currency - mena
• user_id - GUID používateľa