مستندات API - EnergyFather.com

سرویس EnergyFather به خرید (اجاره) انرژی و پهنای باند مورد نیاز برای ارسال تراکنش ها در USDT و سایر توکن های رمزنگاری TRC20 کمک می کند. پهنای باند نیز برای ارسال هر نوع تراکنش در بلاک چین TRON، مانند ارسال TRX، مطالبه پاداش و رای دادن به Super Representatives مورد نیاز است.

روش خرید انرژی

برای خرید انرژی باید در سرویس EnergyFather ثبت نام کنید، رمز مجوز را از صفحه "خریدار > توکن های API" بگیرید و موجودی حساب خریدار را شارژ کنید.

پس از ایجاد یک سفارش (روش ‘buy/energy’) می توان انرژی را با تأخیر چند ثانیه یا حتی چند دقیقه تحویل داد، بنابراین در هنگام توسعه سیستم های خودکار توصیه می شود با استفاده از روش درخواستی ‘order/get/{guid}’، به صورت دوره ای اجرای سفارش را بررسی کنید.

به عنوان مثال، اگر قصد ارسال USDT را دارید و می خواهید با خرید انرژی معاملات را ارزان تر کنید، موارد زیر را انجام می دهید:

درخواست روش ‘buy/energy’ برای برآورد مقدار انرژی مورد نیاز و خرید آن،
به طور دوره ای درخواست روش ‘order/get/{guid}’ تا زمانی که انرژی تفویض شود (معمولا چند ثانیه طول می کشد)،
ارسال USDT (انرژی خریداری شده برای پرداخت کارمزد تراکنش استفاده می شود).

یادداشت های عمومی

در این مستندات، عبارتی که در پرانتز های فرفری مانند ‘{guid}’ یا ‘{id}’ پیچیده شده است، به معنای مقدار متغیر مربوطه است:

‘{guid}’ شناسه منحصر به فرد جهانی شی در EnergyFather (معمولا 8 رقمی) است.
‘{id}’ عدد متوالی شی برای این کاربر است (شماره گذاری با ‘1’ برای هر کاربر شروع می شود).

API نقطه پایانی

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

درخواست ها را با استفاده از روش POST ارسال کنید.

مجوز درخواست ها

برای تأیید (مجوز) درخواست ها به یک API خصوصی، یک سربرگ HTTP باید ارسال شود:

Token: {token}

مدیریت توکن های مجوز در کنترل پنل، در صفحه "خریدار > توکن های API" قرار دارد.

به عنوان مثال می توانید اطلاعات مربوط به 123456 سفارش را به روش زیر دریافت کنید:

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

وضعیت سفارش

"0" - در انتظار. سفارش به تازگی ایجاد شده است.
"1" - در انتظار پرداخت. لینک پرداخت قبلا ایجاد شده است، EnergyFather منتظر تماس از سیستم پرداخت است. اگر سفارش به طور کامل توسط وجوه موجود در حساب داخلی پرداخت شود، از این وضعیت استفاده نمی شود.
"2" - روند تفویض انرژی در حال انجام است.
"3" - تفویض شده. انرژی داده می شود.
"4" - بازپس گرفته شده (بدون تفویض نظر). انرژی به دلیل پایان دوره زمانی پرداخت شده برداشت می شود.
"5" - پرداخت شده. سفارش پرداخت می شود و به صف تحویل انرژی اضافه می شود.
"6" - خطا.

توالی معمول وضعیتها: 0, 5, 2, 3, 4.

روش های API

/api/v1/private/buy/energy – خرید انرژی (پرداخت از حساب داخلی)
/api/v1/private/order/list - لیستی از سفارشات خود را دریافت کنید
/api/v1/private/order/get/{guid} – اطلاعات مربوط به سفارش خود را دریافت کنید
/api/v1/private/account/list – لیستی از حساب های داخلی خود را دریافت کنید
/api/v1/private/account/get/{id} – اطلاعات مربوط به حساب داخلی خود را دریافت کنید

روش "buy/energy" – خرید انرژی (پرداخت شده از حساب داخلی)

درخواست خرید انرژی توسط مشتری ثبت نام شده با بدهی از حساب داخلی. انرژی بلافاصله به آدرس مشخص شده ارسال می شود.

اگر حساب داخلی وجوه کافی نداشته باشد، سفارش ایجاد می شود و فورا وضعیت "6" (خطا) را دریافت می کند. در این صورت باید به پنل مراجعه کنید، مقداری وجوه واریز کنید و سپس درخواست جدید API برای خرید انرژی ارسال کنید.

دو راه برای تعیین میزان انرژی خریداری شده وجود دارد:

الف) می توانید مقدار دقیق انرژی را در پارامتر "amount" تنظیم کنید، سپس باید amount_source="amount" را نیز تنظیم کنید.

ب) اگر نمی دانید برای ارسال USDT یا توکن دیگری چقدر انرژی لازم است، می توانید amount_source="estimate" را تنظیم کنید و پارامترهای مناسب (estimate_to, estimate_token, estimate_adjust_percent) را پر کنید.

buy/energy: درخواست نمونه با مقدار دقیق انرژی

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: درخواست نمونه با محاسبه مقدار انرژی مورد نیاز

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: پارامترهای درخواست

to (رشته، الزامی) – آدرس TRON که انرژی باید به آن تفویض شود
period_amount (عدد صحیح، الزامی) – دوره زمانی برای خرید انرژی
period_type (رشته، الزامی) - نوع دوره زمانی. مقادیر ممکن: days, hours.
format (رشته، اختیاری) - فرمت پاسخ. مقادیر ممکن: json (default), xml.
amount_source (رشته، الزامی) - الگوریتم برای تعیین میزان انرژی تفویض شده. اگر مقدار "amount" باشد، از مقدار پارامتر "amount" استفاده می شود. اگر مقدار "estimate" باشد، مقدار انرژی مورد نیاز بر اساس پارامترهای estimate_to, estimate_token, estimate_adjust_percent محاسبه می شود. مقادیر ممکن: amount, estimate.
amount (عدد صحیح، در صورت amount_source="amount" مورد نیاز است) - مقدار انرژی خریداری شده. اگر amount_source="estimate" نادیده گرفته شود.
estimate_to (رشته، در صورت amount_source="estimate" مورد نیاز است) - لیست جدا شده با کاما از آدرس های TRON که تراکنش های توکن برای ارسال به آنها برنامه ریزی شده است
estimate_token (رشته، در صورت amount_source="estimate" مورد نیاز است) – توکن TRC20. مقادیر احتمالی (حساس به حروف و بزرگ): USDT, USDC, USDD, USDJ, JST, TUSD, stUSDT, WTRX.
estimate_adjust_percent (اعشاری، در صورت amount_source="estimate" مورد نیاز است) - مقدار انرژی اضافی که به صورت درصد بیان می شود. این مازاد برای جلوگیری از سوختن TRX مورد نیاز است، که ممکن است در صورتی اتفاق بیفتد که آدرس دقیقا مقدار انرژی لازم را داشته باشد. مقدار توصیه شده 0.04%. است

مهم: در حال حاضر، فقط 6 دوره معتبر هستند: 1 hour و 1, 3, 7, 15, 30 days.

buy/energy: پاسخ

در صورت موفقیت، پاسخ حاوی سفارش GUID خواهد بود که بعدا می توانید جزئیات واقعی آن را به دست آورید.

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

اگر درخواست حاوی amount_source="estimate" باشد، پاسخ دارای یک بخش اضافی "estimate_task" است. مثلا:

{
	"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: پارامترهای پاسخ

guid – راسته GUID
balance – وجوه موجود در حال حاضر در حساب داخلی، TRX
days – مدت زمان تامین انرژی بر حسب روز، اگر "period_type=days"
hours – مدت زمان تامین انرژی بر حسب ساعت، اگر "period_type=hours"
estimate_task – محاسبه (برآورد) انرژی مورد نیاز برای ارسال تراکنش های TRC20 از یک آدرس TRON به لیست آدرس های TRON دیگر

متد "order/get/{guid}" – دریافت جزئیات سفارش

به دست آوردن اطلاعات در مورد سفارش خاص.

order/get/{guid} – درخواست نمونه

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

order/get/{guid} - پاسخ نمونه

{
	"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} - پارامترهای پاسخ

guid – راسته GUID
balance – وجوه موجود در حال حاضر در حساب داخلی، TRX
days – مدت زمان تامین انرژی بر حسب روز، اگر "period_type=days"
hours – مدت زمان تامین انرژی بر حسب ساعت، اگر "period_type=hours"
to – آدرس TRX که انرژی در آن تحویل داده می شود
energy_amount - مقدار انرژی
order_cost - هزینه سفارش، TRX
order_cost_paid – مبلغی که قبلا پرداخت شده است، TRX (در صورت عدم وجود وجوه کافی در حساب داخلی، این مبلغ کمتر از "order_cost" خواهد بود)
address_activation_fee – میزان هزینه برای فعال سازی آدرس مقصد، TRX
energy_delegation_fee – کارمزد برای اندازه سفارش خیلی کوچک، TRX
resource_txs - آرایه ای حاوی لیست تراکنش ها در بلاک چین TRON که در آن منابع تفویض شده و بازپس گرفته می شوند (بدون واگذاری)
status – وضعیت سفارش، مقادیر احتمالی در ابتدای این راهنما شرح داده شده است
payment_status - وضعیت پرداخت سفارش در سیستم پرداخت (مقادیر احتمالی به سیستم پرداخت بستگی دارد)

متد "order/list" - دریافت لیست سفارشات

دریافت لیست سفارشات.

order/list – درخواست نمونه

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

order/list – پارامترهای درخواست

sort (رشته، اختیاری) - مرتب سازی ورودی ها، به طور پیش فرض "created_at|desc"
per_page (عدد صحیح، اختیاری) - تعداد ورودی ها را در هر پاسخ محدود کنید
page (عدد صحیح، اختیاری) - شماره متوالی صفحه پاسخ
filter (آرایه ای از arrays(objects)، اختیاری) - فیلتر ورودی ها

order/list - پاسخ نمونه

{
	"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 - پارامترهای پاسخ

guid – GUID سفارش
status – وضعیت پاسخ API

روش "account/list" – فهرست کردن حساب های داخلی

دریافت لیستی از حساب های داخلی، از جمله میزان وجوه موجود در حال حاضر. از آنجایی که برای هر بخش از سایت (buyer, affiliate, seller, dealer) یک حساب داخلی جداگانه وجود دارد، چندین حساب در حساب وجود دارد.

account/list – درخواست نمونه

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

account/list - پاسخ نمونه

{
	"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 - پارامترهای پاسخ

guid – GUID حساب داخلی
id – ID متوالی حساب داخلی
section - این تعادل متعلق به کدام بخش EnergyFather است
balance – وجوه موجود
currency – ارز
user_id – GUID کاربر

متد "account/get/{id}" – دریافت حساب داخلی دقیق

اخذ موجودی حساب داخلی برای بخش خاصی از EnergyFather. از آنجایی که هر بخش حساب مخصوص به خود را دارد (buyer, affiliate, seller, dealer)، برای هر کاربر چندین حساب وجود دارد. ابتدا می توانید از روش "account/list" برای دریافت لیست آنها استفاده کنید، ‘id’ حساب مورد نظر را پیدا کنید و سپس از این ‘id’ برای بدست آوردن موجودی یک حساب خاص استفاده کنید.

account/get/{id} – درخواست نمونه

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

account/get/{id} – پاسخ نمونه

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

account/get/{id} - پارامترهای پاسخ

guid – GUID حساب داخلی
id - شناسه متوالی حساب داخلی
section - این موجودی متعلق به کدام بخش EnergyFather است
balance - وجوه موجود
currency - واحد پول
user_id - GUID کاربر