Τεκμηρίωση API

Διαδικασία αγοράς ενέργειας

Για να αγοράσετε ενέργεια, πρέπει να εγγραφείτε στην υπηρεσία EnergyFather, να λάβετε το κουπόνι εξουσιοδότησης από τη σελίδα "Buyer > API tokens" και να συμπληρώσετε το υπόλοιπο του λογαριασμού Buyer.

Μετά τη δημιουργία μιας εντολής (μέθοδος ‘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.

Η μέθοδος "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 (string, απαιτείται) - τύπος χρονικής περιόδου. Πιθανές τιμές: 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 με διαχωρισμό με κόμμα, στις οποίες προβλέπεται να αποστέλλονται οι συναλλαγές token.
• 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 όπου οι πόροι έχουν εκχωρηθεί και διεκδικηθεί (undelegated)
• 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 του χρήστη