API dokumentace

Postup nákupu energie

Pro nákup energie se musíte zaregistrovat ve službě EnergyFather, získat autorizační token na stránce "Kupující > API tokeny" a dobít zůstatek na účtu kupujícího.

Po vytvoření objednávky (metoda ‘buy/energy’) může být energie dodána se zpožděním několika sekund nebo dokonce minut, proto se při vývoji automatizovaných systémů doporučuje pravidelně kontrolovat provedení objednávky pomocí metody ‘order/get/{guid}’.

Pokud například plánujete odeslat USDT a chcete transakce zlevnit nákupem energie, postupujte následovně:

• požádat o metodu ‘buy/energy’ pro odhad potřebného množství energie a její nákup,
• pravidelně žádat ‘order/get/{guid}’ metodu, dokud není energie delegována (obvykle to trvá několik sekund),
• odeslat USDT (nakoupená energie bude použita na úhradu transakčního poplatku).

Obecné poznámky

V této dokumentaci výraz zabalený do kulatých závorek jako ‘{guid}’ nebo ‘{id}’ znamená hodnotu příslušné proměnné:

• ‘{guid}’ je globální jedinečný identifikátor objektu v EnergyFather (obvykle 8 číslic),
• ‘{id}’ je pořadové číslo objektu pro tohoto uživatele (číslování začíná ‘1’ pro každého uživatele).

API Koncový bod

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

Odesílejte požadavky pomocí metody POST.

Autorizace žádostí

Pro potvrzení (autorizaci) požadavků na soukromé API by měla být předána hlavička HTTP:

Token: {token}

Správa autorizačních tokenů se nachází v ovládacím panelu na stránce "Kupující > API tokeny".

Například informace o objednávce 123456 můžete získat následujícím způsobem:

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

Stav objednávky

• "0" - Čeká na vyřízení. Objednávka byla právě vytvořena.
• "1" - Čekáme na platbu. Odkaz na platbu již byl vygenerován, EnergyFather čeká se na zpětné volání z platebního systému. Tento stav se nepoužívá, pokud je objednávka hrazena výhradně z prostředků dostupných na interním účtu.
• "2" - Probíhá postup předávání energie.
• "3" - Delegováno. Energie se vydává.
• "4" - Reclaimed (Undelegated). Energie je odebrána z důvodu ukončení zaplaceného časového období.
• "5" - Placené. Objednávka je zaplacena a zařazena do fronty na dodávku energie.
• "6" - Chyba.

Obvyklá posloupnost stavů: 0, 5, 2, 3, 4.

Metoda "buy/energy" - nákup energie (hrazeno z interního účtu)

Požadavek registrovaného zákazníka na nákup energie s odúčtováním z interního účtu. Energie je okamžitě odeslána na zadanou adresu.

Pokud interní účet nemá dostatek prostředků, objednávka se vytvoří a okamžitě dostane stav "6" (Chyba). V takovém případě musíte navštívit panel, vložit nějaké prostředky a poté odeslat novou API žádost o nákup energie.

Existují dva způsoby, jak definovat množství nakupované energie:

a) V parametru "amount" můžete nastavit přesné množství energie, pak byste měli nastavit také amount_source="amount".

b) Pokud nevíte, kolik energie je potřeba k odeslání transakce USDT nebo jiného tokenu, můžete nastavit amount_source="estimate" a vyplnit příslušné parametry (estimate_to, estimate_token, estimate_adjust_percent).

buy/energy: Příklad požadavku s přesným množstvím 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: Příklad požadavku s výpočtem potřebného množství 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: Request params

• to (string, povinné) - TRON adresa, na kterou má být energie delegována
• period_amount (celé číslo, povinné) - doba nákupu energie
• period_type (řetězec, povinné) - typ časového období. Možné hodnoty: days, hours.
• format (řetězec, nepovinné) - formát odpovědi. Možné hodnoty: json (default), xml.
• amount_source (string, povinné) - algoritmus pro určení množství delegované energie. Pokud je hodnota "amount", použije se hodnota parametru "amount". Pokud je hodnota "estimate", vypočítá se požadované množství energie na základě parametrů estimate_to, estimate_token, estimate_adjust_percent. Možné hodnoty: amount, estimate.
• amount (celé číslo, povinné, pokud amount_source="amount") - množství nakupované energie. Ignoruje se, pokud je amount_source="estimate".
• estimate_to (řetězec, povinný, pokud amount_source="estimate") - čárkou oddělený seznam TRON adres, na které se plánují zasílat tokenové transakce.
• estimate_token (řetězec, povinný, pokud amount_source="estimate") - token TRC20. Možné hodnoty (rozlišuje se velikost písmen): USDT, USDC, USDD, USDJ, JST, TUSD, stUSDT, WTRX.
• estimate_adjust_percent (desetinné číslo, povinné v případě amount_source="estimate") - množství přebytečné energie vyjádřené v procentech. Tento přebytek je nutný, aby nedošlo ke spálení TRX, což se může stát, pokud má adresa přesně potřebné množství energie. Doporučená hodnota je 0.04%.

Důležité: V současné době je platných pouze 6 období: 1 hour a 1, 3, 7, 15, 30 days.

buy/energy: Reakce

V případě úspěchu bude odpověď obsahovat objednávku GUID, podle které můžete později zjistit její aktuální ú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"
}

Pokud požadavek obsahuje amount_source="estimate", pak odpověď obsahuje další část "estimate_task". Napří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: Response params

• guid - objednávka GUID
• balance - finanční prostředky, které jsou aktuálně k dispozici na vnitřním účtu, TRX
• days - doba poskytování energie ve dnech, pokud "period_type=days"
• hours - doba poskytování energie v hodinách, pokud "period_type=hours"
• estimate_task - výpočet (odhad) energie potřebné k odeslání TRC20 transakcí z jedné TRON adresy na seznam dalších TRON adres.

Metoda "order/get/{guid}" - získání podrobností o objednávce

Získání informací o konkrétní zakázce.

order/get/{guid} - Příklad požadavku

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

order/get/{guid} - Příklad odpovědi

{
	"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} - Parametry odpovědi

• guid - objednávka GUID
• balance - finanční prostředky, které jsou aktuálně k dispozici na vnitřním účtu, TRX
• days - doba poskytování energie ve dnech, pokud "period_type=days"
• hours - doba poskytování energie v hodinách, pokud "period_type=hours"
• to - TRX adresa, kam je energie dodávána
• energy_amount - množství energie
• order_cost - náklady na objednávku, TRX
• order_cost_paid - již uhrazená částka, TRX (v případě nedostatku prostředků na interním účtu bude tato částka nižší než "order_cost").
• address_activation_fee - výše poplatku za aktivaci cílové adresy, TRX
• energy_delegation_fee - poplatek za příliš malou velikost objednávky, TRX
• resource_txs - pole obsahující seznam transakcí v TRON blockchainu, kde jsou prostředky delegovány a vráceny (undelegated).
• status - stav objednávky, možné hodnoty jsou popsány na začátku této příručky.
• payment_status - stav platby příkazu v platebním systému (možné hodnoty závisí na platebním systému).

Metoda "order/list" - získání seznamu objednávek

Získání seznamu objednávek.

order/list - Příklad požadavku

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

order/list - Parametry požadavku

• sort (řetězec, nepovinné) - třídění záznamů, ve výchozím nastavení "created_at|desc"
• per_page (celé číslo, nepovinné) - omezení počtu záznamů v jedné odpovědi
• page (celé číslo, nepovinné) - pořadové číslo stránky s odpovědí
• filter (pole arrays(objects), nepovinné) - filtr záznamů

order/list - Příklad odpovědi

{
	"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 - Parametry odpovědi

• guid - GUID objednávky
• status - stav odpovědi API

Metoda "account/list" - výpis interních účtů

Získání seznamu interních účtů, včetně výše aktuálně dostupných prostředků. Vzhledem k tomu, že pro každou sekci webu existuje samostatný interní účet (buyer, affiliate, seller, dealer), je na účtu více účtů.

account/list - Příklad požadavku

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

account/list - Příklad odpovědi

{
	"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 - Parametry odpovědi

• guid - GUID interního účtu
• id - pořadové číslo ID interního účtu
• section - do které sekce EnergyFather tento zůstatek patří
• balance - dostupné finanční prostředky
• currency - měna
• user_id - GUID uživatele

Metoda "account/get/{id}" - získání přesného interního účtu

Zjištění zůstatku interního účtu pro určitou sekci EnergyFather. Protože každá sekce má svůj vlastní účet (buyer, affiliate, seller, dealer), existuje pro každého uživatele několik účtů. Nejprve můžete pomocí metody "account/list" získat jejich seznam, zjistit ‘id’ účtu, který vás zajímá, a poté pomocí tohoto ‘id’ získat zůstatek konkrétního účtu.

account/get/{id} - Příklad žádosti

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

account/get/{id} - Příklad odpovědi

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

account/get/{id} - Parametry odpovědi

• guid - GUID interního účtu
• id - pořadové číslo interního účtu
• section - do které sekce EnergyFather tento zůstatek patří
• balance - dostupné finanční prostředky
• currency - měna
• user_id - GUID uživatele