Documentação API

O serviço EnergyFather ajuda a comprar (alugar) a energia e a largura de banda necessárias para enviar transações no USDT e outros cripto-tokens TRC20; a largura de banda também é necessária para enviar qualquer tipo de transação na blockchain TRON, como enviar TRX, reivindicar recompensas e votar no Super Representatives.

Procedimento de compra de energia

Para comprar energia, é necessário registar-se no serviço EnergyFather, obter o token de autorização na página "Comprador > API tokens" e carregar o saldo da conta do Comprador.

Depois de criar uma ordem (método ‘buy/energy’), a energia pode ser entregue com um atraso de vários segundos ou mesmo minutos, pelo que, ao desenvolver sistemas automatizados, recomenda-se verificar periodicamente a execução da ordem solicitando o método ‘order/get/{guid}’.

Por exemplo, se estiver a planear enviar USDT e desejar tornar as transacções mais baratas através da compra de energia, deve fazer o seguinte

  • solicitar o método ‘buy/energy’ para estimar a quantidade de energia necessária e comprá-la,
  • solicita periodicamente o método ‘order/get/{guid}’ até a energia ser delegada (normalmente demora alguns segundos),
  • enviar USDT (a energia adquirida será utilizada para pagar a taxa de transação).

Notas gerais

Nesta documentação, uma expressão entre chavetas como ‘{guid}’ ou ‘{id}’ significa o valor da variável correspondente:

  • ‘{guid}’ é o identificador global único do objeto em EnergyFather (normalmente 8 dígitos),
  • ‘{id}’ é o número sequencial do objeto para este utilizador (a numeração começa com ‘1’ para cada utilizador).

API Ponto final

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

Os pedidos devem ser enviados utilizando o método POST.

Autorização de pedidos

Para confirmar (autorizar) os pedidos a um API privado, deve ser passado um cabeçalho HTTP:

Token: {token}

A gestão dos tokens de autorização encontra-se no painel de controlo, na página "Comprador > API tokens".

Por exemplo, é possível obter informações sobre a encomenda 123456 da seguinte forma:

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

Estado da encomenda

  • "0" - Pendente. A encomenda acabou de ser criada.
  • "1" - A aguardar o pagamento. A ligação de pagamento já foi gerada, EnergyFather está à espera de uma chamada de retorno do sistema de pagamento. Este estado não é utilizado se a encomenda for paga inteiramente com fundos disponíveis na conta interna.
  • "2" - O processo de delegação de energia está em curso.
  • "3" - Delegado. A energia é distribuída.
  • "4" - Reclamada (Não delegada). A energia é retirada devido ao fim do período de tempo pago.
  • "5" - Pago. A encomenda é paga e adicionada à fila de espera para entrega de energia.
  • "6" - Erro.

A sequência habitual de estados: 0, 5, 2, 3, 4.

Métodos API
  • /api/v1/private/buy/energy - comprar energia (paga a partir de uma conta interna)
  • /api/v1/private/order/list - obter uma lista das suas encomendas
  • /api/v1/private/order/get/{guid} - obter informações sobre a sua encomenda
  • /api/v1/private/account/list - obter uma lista das suas contas internas
  • /api/v1/private/account/get/{id} - obter informações sobre a sua conta interna

O método "buy/energy" - comprar energia (paga a partir de uma conta interna)

Pedido de compra de energia por um cliente registado com débito na conta interna. A energia é imediatamente enviada para o endereço indicado.

Se a conta interna não tiver fundos suficientes, a ordem será criada e receberá instantaneamente o estado "6" (Erro). Neste caso, é necessário visitar o painel, depositar alguns fundos e, em seguida, enviar um novo pedido API para a compra de energia.

Há duas maneiras de definir a quantidade de energia a comprar:

a) Pode definir a quantidade exacta de energia no parâmetro "amount", depois deve definir também amount_source="amount".

b) Se não souber quanta energia é necessária para que uma transação envie USDT ou outro token, pode definir amount_source="estimate" e preencher os parâmetros adequados (estimate_to, estimate_token, estimate_adjust_percent).

buy/energy: Exemplo de pedido com quantidade exacta de energia

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: Exemplo de pedido com cálculo da quantidade de energia necessária

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: Parâmetros do pedido

  • to (string, obrigatório) - Endereço TRON no qual a energia deve ser delegada
  • period_amount (número inteiro, obrigatório) - período de tempo para comprar energia
  • period_type (cadeia, obrigatório) - tipo de período de tempo. Valores possíveis: days, hours.
  • format (cadeia, facultativo) - formato da resposta. Valores possíveis: json (default), xml.
  • amount_source (string, obrigatório) - algoritmo para determinar a quantidade de energia delegada. Se o valor for "amount", é utilizado o valor do parâmetro "amount". Se o valor for "estimate", a quantidade de energia necessária é calculada com base nos parâmetros estimate_to, estimate_token, estimate_adjust_percent. Valores possíveis: amount, estimate.
  • amount (número inteiro, obrigatório se amount_source="amount") - quantidade de energia a comprar. É ignorado se amount_source="estimate".
  • estimate_to (string, obrigatório se amount_source="estimate") - lista separada por vírgulas de endereços TRON para os quais está previsto o envio de transacções de token
  • estimate_token (string, obrigatório se amount_source="estimate") - o token TRC20. Valores possíveis (sensíveis a maiúsculas e minúsculas): USDT, USDC, USDD, USDJ, JST, TUSD, stUSDT, WTRX.
  • estimate_adjust_percent (decimal, obrigatório se amount_source="estimate") - quantidade de energia em excesso expressa em percentagem. Este excesso é necessário para evitar queimar TRX, o que pode acontecer se o endereço tiver exatamente a quantidade de energia necessária. O valor recomendado é 0.04%.

Importante: Atualmente, apenas 6 períodos são válidos: 1 hour e 1, 3, 7, 15, 30 days.

buy/energy: Resposta

Em caso de sucesso, a resposta conterá a ordem GUID, através da qual poderá obter mais tarde os seus detalhes reais.

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

Se o pedido contiver amount_source="estimate", a resposta terá uma secção adicional "estimate_task". Por exemplo:

{
	"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: Parâmetros de resposta

  • guid - a ordem GUID
  • balance - fundos atualmente disponíveis na conta interna, TRX
  • days - duração do fornecimento de energia em dias, se "period_type=days"
  • hours - duração do fornecimento de energia em horas, se "period_type=hours"
  • estimate_task - cálculo (estimativa) da energia necessária para enviar transacções TRC20 de um endereço TRON para a lista de outros endereços TRON

O método "order/get/{guid}" - obter pormenores da encomenda

Obtenção de informações sobre a encomenda específica.

order/get/{guid} - Exemplo de pedido

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

order/get/{guid} - Exemplo de resposta

{
	"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} - Parâmetros de resposta

  • guid - a ordem GUID
  • balance - fundos atualmente disponíveis na conta interna, TRX
  • days - duração do fornecimento de energia em dias, se "period_type=days"
  • hours - duração do fornecimento de energia em horas, se "period_type=hours"
  • to - TRX endereço onde a energia é fornecida
  • energy_amount - quantidade de energia
  • order_cost - custo da encomenda, TRX
  • order_cost_paid - montante já pago, TRX (em caso de insuficiência de fundos na conta interna, este montante será inferior a "order_cost")
  • address_activation_fee - montante da taxa para a ativação do endereço de destino, TRX
  • energy_delegation_fee - taxa por tamanho de encomenda demasiado pequeno, TRX
  • resource_txs - matriz que contém a lista de transacções na cadeia de blocos TRON em que os recursos são delegados e reclamados (não delegados)
  • status - estado da encomenda, os valores possíveis são descritos no início deste manual
  • payment_status - estado do pagamento da ordem no sistema de pagamento (os valores possíveis dependem do sistema de pagamento)

O método "order/list" - obter a lista de encomendas

Obter a lista de encomendas.

order/list - Exemplo de pedido

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

order/list - Parâmetros de pedido

  • sort (string, opcional) - ordenação das entradas, por defeito "created_at|desc"
  • per_page (número inteiro, facultativo) - limitar o número de entradas por resposta
  • page (número inteiro, facultativo) - número sequencial da página de resposta
  • filter (matriz de arrays(objects), opcional) - filtro de entradas

order/list - Exemplo de resposta

{
	"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 - Parâmetros de resposta

  • guid - GUID da encomenda
  • status - estado da resposta API

O método "account/list" - listagem das contas internas

Obter uma lista das contas internas, incluindo o montante de fundos atualmente disponível. Uma vez que existe uma conta interna separada para cada secção do sítio (buyer, affiliate, seller, dealer), existem várias contas na conta.

account/list - Exemplo de pedido

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

account/list - Exemplo de resposta

{
	"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 - Parâmetros de resposta

  • guid - GUID da conta interna
  • id - ID sequencial da conta interna
  • section - a que secção de EnergyFather pertence este saldo
  • balance - fundos disponíveis
  • currency - moeda
  • user_id - GUID do utilizador

O método "account/get/{id}" - obter a conta interna exacta

Obtenção do saldo da conta interna para uma secção específica de EnergyFather. Uma vez que cada secção tem a sua própria conta (buyer, affiliate, seller, dealer), existem várias contas para cada utilizador. É possível utilizar primeiro o método "account/list" para obter a sua lista, descobrir o ‘id’ da conta de interesse e, em seguida, utilizar este ‘id’ para obter o saldo de uma determinada conta.

account/get/{id} - Exemplo de pedido

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

account/get/{id} - Exemplo de resposta

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

account/get/{id} - Parâmetros de resposta

  • guid - GUID da conta interna
  • id - ID sequencial da conta interna
  • section - a que secção de EnergyFather pertence este saldo
  • balance - fundos disponíveis
  • currency - moeda
  • user_id - GUID do utilizador