Dokumentace API

Postup nákupu energie

Chcete-li si koupit energii, musíte se zaregistrovat ve službě EnergyFather, získat autorizační token na stránce "Kupující > API tokeny" a doplnit 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, takže při vývoji automatizovaných systémů se doporučuje pravidelně kontrolovat provedení objednávky pomocí metody ‘order/get/{guid}’.

Pokud například plánujete odeslat USDT a chcete zlevnit transakce 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 o metodu ‘order/get/{guid}’, dokud není energie delegována (obvykle to trvá několik sekund),
• zašlete 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 privátní 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í > Tokeny API".

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á 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 konce zaplaceného časového období.
• "5" - Zaplaceno. Objednávka je zaplacena a zařazena do fronty na dodání 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 žádost API o nákup energie.

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

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

b) Pokud nevíte, kolik energie je zapotřebí 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: Parametry požadavku

• to (string, povinné) - adresa TRON, 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, required) - 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í energie, které má být nakoupeno. Ignoruje se, pokud amount_source="estimate".
• estimate_to (řetězec, povinné, pokud amount_source="estimate") - čárkou oddělený seznam adres TRON, na které se plánuje zasílání tokenových transakcí.
• 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, vyžadováno, pokud 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, k němuž může dojí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 získat její skutečné ú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 žádost 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: Reakce params

• guid - objednávka GUID
• balance - prostředky, které jsou v současné době 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í transakcí TRC20 z jedné adresy TRON na seznam jiných adres TRON

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 odezvy

• guid - objednávka GUID
• balance - prostředky, které jsou v současné době 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 se dodává energie
• energy_amount - množství energie
• order_cost - objednací cena, TRX
• order_cost_paid - již uhrazená částka, TRX (v případě nedostatku prostředků na vnitřní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 blockchainu TRON, kde jsou prostředky delegovány a vráceny (undelegated).
• status - stav objednávky, možné hodnoty jsou popsány na začátku tohoto návodu.
• payment_status - stav platby objednávky 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 - Požadované parametry

• 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 položek

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 odezvy

• 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 (buyer, affiliate, seller, dealer) existuje samostatný interní účet, 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 odezvy

• guid - GUID interního účtu
• id - pořadové číslo ID interního účtu
• section - do které sekce EnergyFather tento zůstatek patří
• balance - dostupné 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’ zjistit zůstatek konkrétního účtu.

account/get/{id} - Příklad požadavku

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 odezvy

• guid - GUID interního účtu
• id - pořadové ID interního účtu
• section - do které sekce EnergyFather tato bilance patří
• balance - dostupné prostředky
• currency - měna
• user_id - GUID uživatele