Dokumentacja API

Procedura zakupu energii

Aby kupić energię, należy zarejestrować się w usłudze EnergyFather, pobrać token autoryzacyjny ze strony "Kupujący > API tokeny" i doładować saldo konta kupującego.

Po utworzeniu zlecenia (metoda ‘buy/energy’) energia może zostać dostarczona z kilkusekundowym lub nawet kilkuminutowym opóźnieniem, dlatego podczas tworzenia zautomatyzowanych systemów zaleca się okresowe sprawdzanie realizacji zlecenia za pomocą metody ‘order/get/{guid}’.

Na przykład, jeśli planujesz wysłać USDT i chcesz, aby transakcje były tańsze poprzez zakup energii, wykonujesz następujące czynności:

• zażądać metody ‘buy/energy’, aby oszacować potrzebną ilość energii i ją kupić,
• okresowo żąda metody ‘order/get/{guid}’, dopóki energia nie zostanie przekazana (zwykle zajmuje to kilka sekund),
• wyślij USDT (zakupiona energia zostanie wykorzystana do uiszczenia opłaty transakcyjnej).

Uwagi ogólne

W tej dokumentacji wyrażenie ujęte w nawiasy klamrowe, takie jak ‘{guid}’ lub ‘{id}’, oznacza wartość odpowiedniej zmiennej:

• ‘{guid}’ to globalny unikalny identyfikator obiektu w EnergyFather (zwykle 8 cyfr),
• ‘{id}’ to kolejny numer obiektu dla tego użytkownika (numeracja zaczyna się od ‘1’ dla każdego użytkownika).

API Punkt końcowy

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

Żądania należy wysyłać przy użyciu metody POST.

Autoryzacja żądań

Aby potwierdzić (autoryzować) żądania do prywatnego API, należy przekazać nagłówek HTTP:

Token: {token}

Zarządzanie tokenami autoryzacyjnymi znajduje się w panelu sterowania, na stronie "Kupujący > Tokeny API".

Na przykład informacje o zamówieniu 123456 można uzyskać w następujący sposób:

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

Status zamówienia

• "0" - Oczekujące. Zamówienie zostało właśnie utworzone.
• "1" - Oczekiwanie na płatność. Link do płatności został już wygenerowany, EnergyFather oczekuje na oddzwonienie z systemu płatności. Ten status nie jest używany, jeśli zamówienie jest opłacane w całości ze środków dostępnych na koncie wewnętrznym.
• "2" - Procedura delegowania energii jest w toku.
• "3" - Delegowany. Energia jest przekazywana.
• "4" - Odzyskana (niedelegowana). Energia została wycofana z powodu zakończenia opłaconego okresu.
• "5" - Opłacone. Zamówienie zostało opłacone i dodane do kolejki dostaw energii.
• "6" - Błąd.

Zwykła sekwencja statusów: 0, 5, 2, 3, 4.

Metoda "buy/energy" - zakup energii (płatne z konta wewnętrznego)

Żądanie zakupu energii przez zarejestrowanego klienta z obciążeniem konta wewnętrznego. Energia jest natychmiast wysyłana na podany adres.

Jeśli na koncie wewnętrznym nie ma wystarczających środków, zamówienie zostanie utworzone i natychmiast otrzyma status "6" (Błąd). W takim przypadku należy odwiedzić panel, wpłacić środki, a następnie wysłać nowe żądanie zakupu energii API.

Istnieją dwa sposoby zdefiniowania ilości energii do zakupu:

a) Można ustawić dokładną ilość energii w parametrze "amount", a następnie należy również ustawić parametr amount_source="amount".

b) Jeśli nie wiesz, ile energii wymaga transakcja, aby wysłać USDT lub inny token, możesz ustawić amount_source="estimate" i wypełnić odpowiednie parametry (estimate_to, estimate_token, estimate_adjust_percent).

buy/energy: Przykładowe żądanie z dokładną ilością energii

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: Przykładowe żądanie z obliczeniem wymaganej ilości energii

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 żądania

• to (ciąg znaków, wymagany) - adres TRON, na który ma zostać przekazana energia.
• period_amount (liczba całkowita, wymagana) - okres zakupu energii
• period_type (ciąg znaków, wymagany) - typ okresu. Możliwe wartości: days, hours.
• format (ciąg znaków, opcjonalnie) - format odpowiedzi. Możliwe wartości: json (default), xml.
• amount_source (ciąg znaków, wymagany) - algorytm określania ilości delegowanej energii. Jeśli wartość wynosi "amount", używana jest wartość parametru "amount". Jeśli wartość wynosi "estimate", wymagana ilość energii jest obliczana na podstawie parametrów estimate_to, estimate_token, estimate_adjust_percent. Możliwe wartości: amount, estimate.
• amount (liczba całkowita, wymagana, jeśli amount_source="amount") - ilość energii do zakupu. Jest ignorowana, jeśli amount_source="estimate".
• estimate_to (ciąg znaków, wymagany, jeśli amount_source="estimate") - oddzielona przecinkami lista adresów TRON, na które mają być wysyłane transakcje tokenowe.
• estimate_token (ciąg znaków, wymagany, jeśli amount_source="estimate") - token TRC20. Możliwe wartości (z uwzględnieniem wielkości liter): USDT, USDC, USDD, USDJ, JST, TUSD, stUSDT, WTRX.
• estimate_adjust_percent (dziesiętnie, wymagane, jeśli amount_source="estimate") - nadwyżka energii wyrażona w procentach. Ta nadwyżka jest potrzebna, aby uniknąć spalenia TRX, co może się zdarzyć, jeśli adres ma dokładnie wymaganą ilość energii. Zalecana wartość to 0.04%.

Ważne: Obecnie ważnych jest tylko 6 okresów: 1 hour i 1, 3, 7, 15, 30 days.

buy/energy: Odpowiedź

W przypadku powodzenia, odpowiedź będzie zawierać zamówienie GUID, za pomocą którego można później uzyskać jego rzeczywiste szczegóły.

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

Jeśli żądanie zawiera amount_source="estimate", odpowiedź zawiera dodatkową sekcję "estimate_task". Na przykład:

{
	"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: Parametry odpowiedzi

• guid - zamówienie GUID
• balance - środki aktualnie dostępne na koncie wewnętrznym, TRX
• days - czas trwania dostawy energii w dniach, jeśli "period_type=days"
• hours - czas dostarczania energii w godzinach, jeśli "period_type=hours"
• estimate_task - obliczenie (oszacowanie) energii potrzebnej do wysłania transakcji TRC20 z jednego adresu TRON na listę innych adresów TRON.

Metoda "order/get/{guid}" - uzyskiwanie szczegółów zamówienia

Uzyskanie informacji o konkretnym zamówieniu.

order/get/{guid} - Przykładowe żądanie

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

order/get/{guid} - Przykładowa odpowiedź

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

• guid - zamówienie GUID
• balance - środki aktualnie dostępne na koncie wewnętrznym, TRX
• days - czas trwania dostawy energii w dniach, jeśli "period_type=days"
• hours - czas dostarczania energii w godzinach, jeśli "period_type=hours"
• to - TRX adres, pod który dostarczana jest energia
• energy_amount - ilość energii
• order_cost - koszt zamówienia, TRX
• order_cost_paid - kwota już zapłacona, TRX (w przypadku niewystarczających środków na koncie wewnętrznym kwota ta będzie mniejsza niż "order_cost")
• address_activation_fee - kwota opłaty za aktywację adresu docelowego, TRX
• energy_delegation_fee - opłata za zbyt małe zamówienie, TRX
• resource_txs - tablica zawierająca listę transakcji w łańcuchu bloków TRON, w których zasoby są delegowane i odzyskiwane (undelegated).
• status - status zamówienia, możliwe wartości zostały opisane na początku niniejszej instrukcji.
• payment_status - status płatności zamówienia w systemie płatności (możliwe wartości zależą od systemu płatności)

Metoda "order/list" - pobieranie listy zamówień

Pobieranie listy zamówień.

order/list - Przykładowe żądanie

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

order/list - Parametry żądania

• sort (ciąg znaków, opcjonalnie) - sortowanie wpisów, domyślnie "created_at|desc"
• per_page (liczba całkowita, opcjonalnie) - ograniczenie liczby wpisów na odpowiedź
• page (liczba całkowita, opcjonalnie) - kolejny numer strony odpowiedzi
• filter (tablica arrays(objects), opcjonalnie) - filtr wpisów

order/list - Przykładowa odpowiedź

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

• guid - identyfikator GUID zamówienia
• status - status odpowiedzi API

Metoda "account/list" - zestawienie kont wewnętrznych

Uzyskanie listy kont wewnętrznych, w tym kwoty aktualnie dostępnych środków. Ponieważ dla każdej sekcji witryny (buyer, affiliate, seller, dealer) istnieje oddzielne konto wewnętrzne, na koncie znajduje się wiele kont.

account/list - Przykładowe żądanie

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

account/list - Przykładowa odpowiedź

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

• guid - GUID konta wewnętrznego
• id - sekwencyjny ID konta wewnętrznego
• section - do której sekcji EnergyFather należy to saldo
• balance - dostępne środki
• currency - waluta
• user_id - GUID użytkownika

Metoda "account/get/{id}" - uzyskanie dokładnego konta wewnętrznego

Uzyskanie salda konta wewnętrznego dla określonej sekcji EnergyFather. Ponieważ każda sekcja ma własne konto (buyer, affiliate, seller, dealer), istnieje kilka kont dla każdego użytkownika. Można najpierw użyć metody "account/list", aby uzyskać ich listę, znaleźć ‘id’ interesującego konta, a następnie użyć tego ‘id’, aby uzyskać saldo określonego konta.

account/get/{id} - Przykładowe żądanie

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

account/get/{id} - Przykładowa odpowiedź

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

account/get/{id} - Parametry odpowiedzi

• guid - GUID konta wewnętrznego
• id - kolejny identyfikator konta wewnętrznego
• section - do której sekcji EnergyFather należy to saldo
• balance - dostępne środki
• currency - waluta
• user_id - GUID użytkownika