API συνεργατών
API μεταξύ διακομιστών για συνεργάτες: εκδώστε κλειδί, διαβάστε τη διαμόρφωση της βιτρίνας και τις τοποθεσίες, δημιουργήστε πελάτες, αποδώστε πλάνα και διαχειριστείτε τους συνδέσμους συνδρομής από τον ιστότοπό σας ή το bot σας στο Telegram.
Το API συνεργατών σάς επιτρέπει να φτιάξετε πάνω στο CreateYourVPN τον δικό σας ιστότοπο, τη δική σας προσωπική περιοχή για πελάτες ή ένα bot στο Telegram.
Το API καλύπτει πελάτες, συνδρομές, πλάνα και τη διαμόρφωση της βιτρίνας. Η υποδομή, δηλαδή διακομιστές, κόμβοι, panels και διαπιστευτήρια SSH, βρίσκεται εκτός του δημόσιου συμβολαίου.
Μόνο για ενσωματώσεις μεταξύ διακομιστών. Φυλάξτε το κλειδί API στον διακομιστή σας και μην το προσθέτετε σε κώδικα frontend. Τα αιτήματα με κεφαλίδες προγράμματος περιήγησης απορρίπτονται με τον κωδικό 403 browser_forbidden.
Πώς παίρνετε κλειδί
Πίνακας → μενού λογαριασμού → «API», καρτέλα «Κλειδιά».
Δώστε στο κλειδί ένα όνομα (bot Telegram, σελίδα προορισμού) και ενεργοποιήστε μόνο τα δικαιώματα που χρειάζεται.
Πατήστε «Έκδοση κλειδιού» και αντιγράψτε ολόκληρη την τιμή. Το μυστικό εμφανίζεται μόνο μία φορά, επειδή η υπηρεσία αποθηκεύει μόνο το hash του.
Ένας συνεργάτης μπορεί να έχει έως 5 ενεργά κλειδιά. Για να αντικαταστήσετε ένα κλειδί, εκδώστε νέο, ενημερώστε την ενσωμάτωση και μετά ανακαλέστε το παλιό.
Πιστοποίηση
Το κλειδί αποστέλλεται ως bearer token:
curl https://api.createyourvpn.com/api/v1/partner-api/me \
-H "Authorization: Bearer cyv_live_<key_id>_<secret>"Λειτουργεί και το X-API-Key: cyv_live_…, για την περίπτωση που την κεφαλίδα Authorization τη χρησιμοποιεί ήδη ένας proxy.
Ένα κλειδί έχει τη μορφή cyv_live_<key_id>_<secret>. Το πρώτο μισό (key_id) είναι δημόσιο: αυτό βλέπετε στον πίνακα και μπορείτε με ασφάλεια να το αναφέρετε στην υποστήριξη. Το δεύτερο μισό είναι το μυστικό.
Δικαιώματα (scopes)
| Δικαίωμα | Τι επιτρέπει |
|---|---|
config:read | Ανάγνωση της διαμόρφωσης της βιτρίνας, των πλάνων, των τοποθεσιών και του /me. |
users:read | Ανάγνωση πελατών, των συνδρομών και της κίνησής τους. |
users:write | Δημιουργία πελατών, απόδοση πλάνων, επαναφορά συνδέσμων, διαγραφή πελατών. |
Το config:read αρκεί για ενσωματώσεις που μόνο διαβάζουν δεδομένα της βιτρίνας. Προσθέστε users:read ή users:write μόνο όταν η ενσωμάτωση χρειάζεται τις αντίστοιχες λειτουργίες για πελάτες.
Συμβόλαιο API και παραδείγματα
Το πλήρες, εκτελέσιμο συμβόλαιο βρίσκεται στη δημόσια συλλογή Postman. Περιλαμβάνει όλα τα endpoints, τα δικαιώματα, τις παραμέτρους, τα σώματα αιτημάτων, τα παραδείγματα αποκρίσεων και τους σταθερούς κωδικούς σφαλμάτων. Η συλλογή παράγεται από το συμβόλαιο του backend και περιέχει τα τρέχοντα σχήματα αιτημάτων και αποκρίσεων.
Όρια
Το όριο μετριέται χωριστά για κάθε κλειδί και δεν εξαρτάται από τη διεύθυνση IP του αιτήματος.
- 120 αιτήματα ανά λεπτό συνολικά ανά κλειδί.
- 10 αιτήματα ανά λεπτό χωριστά για το
GET /users.
Το GET /users έχει ξεχωριστό όριο, επειδή κάθε αίτημα φορτώνει ολόκληρη τη λίστα πελατών. Για τακτικούς ελέγχους χρησιμοποιήστε το GET /users/{id} ή την αναζήτηση με externalId.
Προτεινόμενο σχήμα. Αποθηκεύστε το ID του πελάτη στο CreateYourVPN από την απόκριση της δημιουργίας και χρησιμοποιείτε το GET /users/{id} για τα επόμενα αιτήματα. Μπορείτε να το συνδέσετε με το δικό σας αναγνωριστικό πελάτη μέσω του externalId.
Ταυτοδυναμία (idempotency)
Τρεις λειτουργίες απαιτούν την κεφαλίδα Idempotency-Key: απόδοση πλάνου, επαναφορά συνδέσμου συνδρομής και διαγραφή πελάτη.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Η επανάληψη ενός αιτήματος με το ίδιο κλειδί μέσα σε 24 ώρες επιστρέφει την αποθηκευμένη απόκριση αντί να εκτελέσει ξανά τη λειτουργία. Έτσι αποφεύγονται διπλές αλλαγές όταν η ενσωμάτωση επαναλαμβάνει ένα αίτημα μετά από λήξη χρόνου.
Δημιουργήστε ξεχωριστό κλειδί για κάθε επιχειρηματικό συμβάν (για παράδειγμα μία πληρωμή ή μία ενέργεια) και χρησιμοποιήστε το σε όλες τις επαναλήψεις αυτού του συμβάντος.
Αν η πρώτη προσπάθεια εκτελείται ακόμη ή το αποτέλεσμά της είναι προσωρινά άγνωστο, το API επιστρέφει 409 conflict χωρίς να εκτελέσει ξανά τη λειτουργία. Πριν επαναλάβετε το αίτημα, ελέγξτε την τρέχουσα κατάσταση του πελάτη.
Τα τρέχοντα σχήματα αιτημάτων και αποκρίσεων βρίσκονται στη δημόσια συλλογή Postman παραπάνω.
Επαναφορά από αντίγραφο ασφαλείας
Δύο τρόποι για να επαναφέρετε τους χρήστες σας: η επαναφορά με ένα κλικ από τον πίνακα ελέγχου που τους επανεισάγει idempotent, ή μια χειροκίνητη επαναφορά σε ένα κενό Marzban, αφού το αρχείο είναι σε εγγενή μορφή χρηστών Marzban.
Πρόσβαση έκτακτης ανάγκης
Ένας εφεδρικός τρόπος σύνδεσης όταν το δίκτυο χρησιμοποιεί λίστες επιτρεπόμενων και η κύρια σύνδεση είναι φραγμένη: δημιουργείτε μια βιντεοκλήση, μας δίνετε τον σύνδεσμό της από τον λογαριασμό σας ή με email και παίρνετε έτοιμη σύνδεση.