Admin API χώρου εργασίας
Το Admin API χώρου εργασίας επιτρέπει σε ενσωματώσεις διακομιστή-προς-διακομιστή να διαχειρίζονται έναν χώρο EVCharge. Η τεκμηρίωση αφορά διαχειριστές και εξωτερικούς ενσωματωτές API. Χρησιμοποιεί ανακλητά διακριτικά συνδεδεμένα με χώρο εργασίας και λεπτομερή πεδία πρόσβασης· δεν δέχεται διακριτικά σύνδεσης πελατών ή συνεδρίες προγράμματος περιήγησης.
Αυτός ο κατάλογος είναι η κανονική αναφορά προγραμματιστών για το API /v2/admin που υλοποιεί το app-api. Δεν τεκμηριώνει διαδρομές πελατών/κινητού ή τις HTTP διαδρομές της ίδιας της πύλης διαχείρισης.
- Τα Αιτήματα και αποκρίσεις endpoints παραθέτουν και τα 87 καταχωρισμένα endpoints, πεδία πρόσβασης, παραμέτρους, σώματα αιτημάτων και επιτυχίας.
- Τα Σχήματα και παραδείγματα ορίζουν επαναχρησιμοποιήσιμους τύπους αιτημάτων/αποκρίσεων και αντιπροσωπευτικά σώματα JSON.
- Η Σύμβαση αποκρίσεων και σφαλμάτων ορίζει κάθε κοινό και ειδικό ανεπιτυχές σώμα.
Βασικό URL και όριο πόρων
Όλες οι διαδρομές είναι σχετικές με την εγκατεστημένη προέλευση app-api:
https://api.evcharge.mobi/v2/admin/...
Το ID χώρου εργασίας δεν γίνεται δεκτό σε URL, ερώτημα ή σώμα αιτήματος. Κάθε διακριτικό συνδέεται με ακριβώς έναν χώρο και το API εξάγει cpoId από την επαληθευμένη ταυτότητα διακριτικού. Αν ένθετη τοποθεσία, φορτιστής, χρήστης, τιμολόγιο, προφίλ, ανάθεση ή συναλλαγή δεν ανήκει σε αυτόν, επιστρέφει την ίδια απόκριση 404 RESOURCE_NOT_FOUND χωρίς αποκάλυψη ύπαρξης πόρων.
Λήψη διακριτικού πρόσβασης
Ένας διαχειριστής δημιουργεί διακριτικά στις Ρυθμίσεις χώρου εργασίας, στην πρόσβαση API. Η διαχείριση διακριτικών σκόπιμα δεν παρέχεται στα διακριτικά χώρου εργασίας.
- Η πρόσβαση API περιλαμβάνεται σε κάθε πρόγραμμα, ακόμη και στο Free. Ο διαχειριστής πρέπει να έχει άδεια επεξεργασίας χώρου εργασίας.
- Το κεντρικό σύστημα χώρου εργασίας πρέπει να ενεργοποιήσει Admin API μέσω
adminApiEnabled· αλλιώς έγκυρο διακριτικό λαμβάνει μη αποκαλυπτικό404απόapp-api. - Ο διαχειριστής μπορεί να παρέχει μόνο πεδία πρόσβασης που επιτρέπουν τα τρέχοντα δικαιώματά του και του χώρου εργασίας.
- Τα νέα διακριτικά μπορεί να μην λήγουν (προεπιλογή Ρυθμίσεων χώρου εργασίας) ή να έχουν διάρκεια 1–365 ολόκληρων ημερών που επιλέγει ο διαχειριστής· ο διακομιστής υπολογίζει τις πεπερασμένες απόλυτες λήξεις. Τα μη λήγοντα παραμένουν έγκυρα μέχρι ανάκλησης.
- Ο χώρος εργασίας μπορεί να έχει έως 50 ενεργά διακριτικά.
- Το διαπιστευτήριο απλού κειμένου εμφανίζεται μία φορά. Αποθηκεύστε το αμέσως σε διαχειριστή μυστικών.
- Όνομα, πεδία πρόσβασης και λήξη είναι αμετάβλητα. Για περιστροφή, δημιουργήστε αντικατάσταση, εγκαταστήστε και ελέγξτε την και ανακαλέστε το παλιό διακριτικό.
- Η ανάκληση είναι άμεση· οι ανακληθείσες εγγραφές παραμένουν ορατές ως αμετάβλητο ιστορικό χώρου εργασίας με απόκρυψη, και δεν υπάρχει endpoint ελέγχου bearer διακριτικού ή οριστικής διαγραφής.
Το app-api δεν έχει endpoint που εκδίδει, ανανεώνει, παραθέτει ή ανακαλεί αυτά τα διαπιστευτήρια. Η λήψη διακριτικού είναι προαπαιτούμενο μέσω ανθρώπινης πύλης διαχείρισης, όχι άλλο endpoint αυτής της αναφοράς.
Μην βάζετε ποτέ το διακριτικό σε έλεγχο πηγαίου κώδικα, URL, συμβολοσειρές ερωτημάτων, cookies, καταγραφές, αναλύσεις ή αναφορές σφαλμάτων.
Έλεγχος ταυτότητας
Στείλτε ακριβώς μία κεφαλίδα τύπου RFC 6750 σε κάθε αίτημα:
Authorization: Bearer evc_ws_<selector>.<secret>
Το ακριβές αδιαφανές διαπιστευτήριο είναι evc_ws_, ακολουθούμενο από κανονικό επιλογέα base64url 16 χαρακτήρων, . και κανονικό μυστικό base64url 43 χαρακτήρων. Στείλτε ολόκληρο το διαπιστευτήριο αυτούσιο· μην το κωδικοποιήσετε ξανά με base64.
Το API απορρίπτει διπλές κεφαλίδες εξουσιοδότησης, τιμές ενωμένες με κόμμα, άλλα σχήματα, κενές τιμές bearer, JWT πελατών και διαπιστευτήρια εκτός αυτής της κεφαλίδας.
Κακοσχηματισμένα, άγνωστα, ληγμένα, ανακληθέντα ή άλλα μη έγκυρα διακριτικά λαμβάνουν ίδια απόκριση:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Cache-Control: no-store
Content-Type: application/json
{
"error": "Unauthorized",
"code": "INVALID_WORKSPACE_TOKEN"
}
Η υπηρεσία ελέγχει κατάσταση διακριτικού και τρέχοντα δικαιώματα χώρου εργασίας σε κάθε αίτημα. Η αφαίρεση δικαιώματος μπορεί έτσι να απενεργοποιήσει πεδία πρόσβασης πριν λήξει το διακριτικό.
Τα διακριτικά χώρου εργασίας είναι αδιαφανή διαπιστευτήρια, όχι JWT. Δεν έχουν διακριτικό ανανέωσης ούτε endpoint ανανέωσης. Πεπερασμένο διακριτικό παύει να επαληθεύει στο απόλυτο expiresAt· μη λήγον ισχύει μέχρι ανάκλησης. Περιστροφή σημαίνει δημιουργία αντικατάστασης στην πύλη, εγκατάσταση στον πελάτη και ανάκληση παλιού.
Συμβάσεις αιτημάτων
- Χρησιμοποιήστε
Content-Type: application/jsonγια αιτήματα με σώμα JSON. - Οι προαιρετικές τιμές αιτήματος
X-Request-Idπερικόπτονται και γίνονται δεκτές μόνο αν έχουν 1–128 χαρακτήρες απόA-Z,a-z,0-9,.,_,:ή-· αλλιώς ο διακομιστής δημιουργεί UUID. Κάθε απόκριση επιστρέφει την επιλεγμένη τιμή ωςX-Request-Id. - Το προαιρετικό
X-Error-Format: envelopeμετατρέπει κάθε απόκριση σφάλματος JSON στον δομημένο φάκελο της Σύμβασης αποκρίσεων και σφαλμάτων. Κάθε άλλη τιμή διατηρεί το προεπιλεγμένο σώμα συμβατότητας. - Τα ID παραμέτρων διαδρομής είναι θετικοί ακέραιοι. Τα ID διακριτικών πρόσβασης της πύλης είναι δεκαδικές συμβολοσειρές επειδή είναι μη προσημασμένες τιμές βάσης 64 bit.
- Οι τιμές ημερομηνίας-ώρας είναι συμβολοσειρές RFC 3339 με ρητή μετατόπιση, π.χ.
2026-08-13T12:30:00Z. - Οι επιτυχείς διαγραφές συνήθως επιστρέφουν
204 No Content. - Οι λειτουργίες δημιουργίας συνήθως επιστρέφουν
201 Created. - Εργασία OCPP που έχει μόνο μπει σε ουρά μπορεί να επιστρέψει
202 Accepted· μην το ερμηνεύετε ως επιβεβαίωση φορτιστή, εκτός αν η απόκριση το δηλώνει ρητά. - Οι επαληθευμένες αποκρίσεις χρησιμοποιούν
Cache-Control: no-store. Τα endpoints QR και εξαγωγής αναφορών επιστρέφουν δυαδικά σώματα με ρητές κεφαλίδες περιεχομένου. - Οι επιτρεπόμενες προελεύσεις προγράμματος περιήγησης μπορούν να διαβάζουν
X-Request-Id,Idempotency-Replayed,Retry-AfterκαιContent-Dispositionμέσω CORS. Έτσι οι πελάτες συσχετίζουν αιτήματα, εντοπίζουν ιδιοδύναμες επαναλήψεις, τηρούν τους χρόνους επανάληψης και διατηρούν τα ονόματα λήψης που επέλεξε ο διακομιστής.
Ιδιοδυναμία
Όλα τα διαχειριστικά αιτήματα POST, PUT, PATCH και DELETE πρέπει να περιλαμβάνουν μία κεφαλίδα Idempotency-Key. Τα κλειδιά έχουν 1–255 ορατούς χαρακτήρες και περιορίζονται στο διακριτικό, τη μέθοδο και τη διαδρομή.
Idempotency-Key: provisioning-2026-08-13-site-42
Η επαναχρησιμοποίηση ολοκληρωμένου κλειδιού με ίδιο URL και σώμα επαναλαμβάνει την αποθηκευμένη απόκριση και προσθέτει:
Idempotency-Replayed: true
Επαναχρησιμοποίηση κλειδιού με διαφορετικό αίτημα επιστρέφει 409 IDEMPOTENCY_CONFLICT. Αίτημα που επεξεργάζεται ακόμη επιστρέφει 409 IDEMPOTENT_REQUEST_PROCESSING με Retry-After: 5.
Ολοκληρωμένες αποκρίσεις και τελικά αποτελέσματα διατηρούνται για επανάληψη ή συμφωνία επί επτά ημέρες από την τελευταία ενημέρωση. Μετά, το ίδιο κλειδί μπορεί να θεωρηθεί νέα εντολή, γι’ αυτό οι πελάτες πρέπει να χρησιμοποιούν καθολικά μοναδικά κλειδιά και να μην τα ανακυκλώνουν σκόπιμα.
Αν λήξει η μίσθωση επεξεργασίας, κλείσει η σύνδεση μετά την έναρξη εκτέλεσης ή η λειτουργία επιστρέψει σφάλμα διακομιστή, το API δεν μπορεί να αποδείξει με ασφάλεια αν συνέβη εξωτερική επίδραση. Κατά τη διατήρηση επτά ημερών, το κλειδί παραμένει οριστικά ακαθόριστο και επιστρέφει 409 IDEMPOTENCY_OUTCOME_UNKNOWN· δεν ανακτάται ούτε εκτελείται ξανά αυτόματα. Επαληθεύστε τα αποτελέσματα πριν από χειροκίνητη ανάκτηση και μη στείλετε την ίδια λειτουργία με νέο κλειδί πριν ολοκληρωθεί η συμφωνία.
Όλα τα διαχειριστικά endpoints μεταβολών, συμπεριλαμβανομένου του POST /reports/send, απαιτούν Idempotency-Key.
Όρια αιτημάτων
Τα όρια εφαρμόζονται και στο διακριτικό και στον χώρο εργασίας του. Οι αποθηκευμένες προεπιλογές είναι:
| Όριο | Προεπιλογή |
|---|---|
| Παράθυρο | 60 δευτερόλεπτα |
| Ανά διακριτικό | 300 αιτήματα |
| Ανά χώρο εργασίας | 1.000 αιτήματα |
Ένα περιορισμένο αίτημα επιστρέφει 429 Too Many Requests και κεφαλίδα Retry-After. Οι εγκαταστάσεις μπορούν να παρακάμψουν αυτές τις τιμές.
Σφάλματα
Τα σφάλματα JSON χρησιμοποιούν σταθερό code όπου ο καλών χρειάζεται διακλάδωση:
{
"error": "Insufficient workspace-token scope",
"code": "INSUFFICIENT_SCOPE"
}
Τα σφάλματα επικύρωσης χρησιμοποιούν πίνακες πεδίων:
{
"validationErrors": {
"name": ["String must contain at least 1 character(s)"]
}
}
Συνήθεις καταστάσεις:
| Κατάσταση | Σημασία |
|---|---|
400 | Μη έγκυρη σύμβαση ιδιοδυναμίας/δρομέα χρήστη/γεωκωδικοποιητή· οι αποτυχίες σχήματος διαδρομής/σώματος/ερωτήματος είναι συνήθως 422 |
401 | Μη έγκυρο διακριτικό χώρου εργασίας |
403 | Έγκυρο διακριτικό χωρίς απαιτούμενο ενεργό πεδίο πρόσβασης ή δικαίωμα |
404 | Ο χώρος εργασίας ή ένθετος πόρος δεν είναι ορατός στο διακριτικό |
409 | Διένεξη κατάστασης πόρου, εξάρτησης, ταυτόχρονης πρόσβασης ή ιδιοδυναμίας |
422 | Αποτυχία επικύρωσης πεδίου, οριοθετημένου εύρους ή ορίου εξαγωγής |
429 | Υπέρβαση ορίου αιτημάτων διακριτικού ή χώρου εργασίας |
502 | Απέτυχε επακόλουθη λειτουργία, όπως η παράδοση αναφοράς |
503 | Η αποθήκευση εξουσιοδότησης ή ιδιοδυναμίας δεν είναι προσωρινά διαθέσιμη |
Κατάλογος πεδίων πρόσβασης
Ο παρακάτω κατάλογος πεδίων πρόσβασης χρησιμοποιείται όταν ο διαχειριστής δημιουργεί διακριτικό. Πεδίο εγγραφής ή υψηλής επίδρασης μπορεί να συνεπάγεται το αντίστοιχο ανάγνωσης, αλλά η ανάγνωση δεν δίνει ποτέ εγγραφή. Τα διαθέσιμα εξαρτώνται από δικαιώματα διαχειριστή και ενεργές λειτουργίες χώρου εργασίας.
| Τομέας | Πεδία πρόσβασης ανάγνωσης | Πεδία πρόσβασης εγγραφής και υψηλής επίδρασης | Πρόσθετο δικαίωμα όπου απαιτείται |
|---|---|---|---|
| Χώρος εργασίας | workspaces:read | workspaces:update | — |
| Τοποθεσίες | sites:read | sites:create, sites:update, sites:delete, sites:power-management | dlmPowerManagement για διαχείριση ισχύος |
| Φορτιστές | chargers:read | chargers:create, chargers:update, chargers:delete, chargers:credentials, chargers:configuration, chargers:firmware, chargers:commands, chargers:public, chargers:connector-settings, chargers:local-users, chargers:tariff-assignments, chargers:profile-assignments | firmwareOperations, publicCharging, tariffs ή smartCharging για την αντίστοιχη δυνατότητα |
| Χρήστες | users:read | users:create, users:update, users:delete, users:invitations, users:rfid, users:access, users:limits | — |
| Προφίλ φόρτισης | chargingProfiles:read | chargingProfiles:create, chargingProfiles:update, chargingProfiles:delete, chargingProfiles:assign | smartCharging |
| Τιμολόγια | tariffs:read | tariffs:create, tariffs:update, tariffs:delete, tariffs:components, tariffs:assign | tariffs |
| Αναφορές | reports:read | reports:export, reports:schedules, reports:send | scheduledReports για προγράμματα και άμεση αποστολή |
Η ίδια η πρόσβαση API περιλαμβάνεται σε κάθε πρόγραμμα και ελέγχεται από τη ρύθμιση adminApiEnabled του κεντρικού συστήματος. Τα παραπάνω πρόσθετα δικαιώματα λειτουργιών εξακολουθούν να ισχύουν· η πρόσβαση API δεν παρέχει λειτουργίες εκτός του προγράμματος χώρου εργασίας.
Αναφορά endpoints
Οι πίνακες αναφέρουν όλες τις 87 διαδρομές διαχείρισης χώρου εργασίας. Όλα τα πεδία πρόσβασης σε ένα κελί απαιτούνται.
Χώρος εργασίας
| Μέθοδος | Διαδρομή | Απαιτούμενο πεδίο πρόσβασης | Σκοπός |
|---|---|---|---|
GET | /v2/admin | workspaces:read | Διαβάζει ασφαλή μεταδεδομένα και δεδομένα αναφοράς χώρου εργασίας. |
PATCH | /v2/admin | workspaces:update | Ενημερώνει ένα ή περισσότερα μεταδεδομένα χώρου εργασίας. |
GET | /v2/admin/dashboard | workspaces:read + reports:read | Διαβάζει οριοθετημένα πλήθη χώρου εργασίας και λειτουργικά σύνολα 90 ημερών. |
Πεδία μερικής ενημέρωσης χώρου εργασίας: name, email, website, addressLine1, addressLine2, postalCode, city, state και countryId. Απαιτείται τουλάχιστον ένα πεδίο. Κενές συμβολοσειρές που δέχονται null κανονικοποιούνται σε null.
Τοποθεσίες και διαχείριση ισχύος
| Μέθοδος | Διαδρομή | Απαιτούμενο πεδίο πρόσβασης | Σκοπός |
|---|---|---|---|
GET | /v2/admin/sites | sites:read | Παραθέτει τοποθεσίες με οριοθετημένα σύνολα 90 ημερών και δεδομένα αναφοράς τοποθεσιών. |
GET | /v2/admin/sites/geocode | sites:read | Αναζητά κανονικοποιημένες υποψήφιες διευθύνσεις μέσω κοινού γεωκωδικοποιητή με περιορισμό ρυθμού και κρυφή μνήμη. |
POST | /v2/admin/sites | sites:create | Δημιουργήστε τοποθεσία. |
GET | /v2/admin/sites/:siteId | sites:read + reports:read | Διαβάζει στοιχεία τοποθεσίας, πρόσφατες συνεδρίες, σύνολα και λειτουργικά αθροίσματα. |
PATCH | /v2/admin/sites/:siteId | sites:update | Αντικαθιστά το επεξεργάσιμο έγγραφο τοποθεσίας. |
DELETE | /v2/admin/sites/:siteId | sites:delete | Διαγράφει κενή τοποθεσία· οι εξαρτήσεις επιστρέφουν διένεξη. |
GET | /v2/admin/sites/:siteId/power-management | sites:power-management | Διαβάζει το δέντρο δυναμικής διαχείρισης φορτίου τοποθεσίας. |
PUT | /v2/admin/sites/:siteId/power-management | sites:power-management | Αντικαθιστά ατομικά τη ρύθμιση διαχείρισης ισχύος τοποθεσίας. |
Τα σώματα δημιουργίας και μερικής ενημέρωσης τοποθεσίας χρησιμοποιούν:
{
"name": "Main depot",
"description": null,
"addressLine1": "1 Example Street",
"addressLine2": null,
"postalCode": "LV-1001",
"city": "Riga",
"state": null,
"countryId": 1,
"timezoneId": 1,
"latitude": 56.9496,
"longitude": 24.1052
}
Η γεωκωδικοποίηση τοποθεσίας δέχεται προαιρετικά πεδία ερωτήματος street, city, state, country και διγράμματο countryCode, μαζί με κεφαλίδα Accept-Language. Η συνδυασμένη αναζήτηση οδού/πόλης/πολιτείας πρέπει να έχει τουλάχιστον δύο χαρακτήρες. Οι αποκρίσεις περιέχουν μόνο placeId, displayName, latitude και longitude· δεν εκτίθενται διαπιστευτήρια ή ειδικά μεταδεδομένα παρόχου. Ο διακομιστής εφαρμόζει κοινή ουρά ενός αιτήματος ανά δευτερόλεπτο, χρονικό όριο οκτώ δευτερολέπτων, οριοθετημένη κρυφή μνήμη 24 ωρών και καθολικά όρια διακριτικών χώρου εργασίας.
Η διαχείριση ισχύος δέχεται { "pools": [...] }. Μια ομάδα έχει id, name, limit, προαιρετικό meterSources και αναδρομικά children. Ένας θυγατρικός φορτιστής έχει chargepointId και priority. Το API περιορίζει το δέντρο και τον αριθμό μετρητών και εκτελεί εκκαθάριση OCPP/επανεπικύρωση δύο φάσεων όταν αντικαθιστά εγκατεστημένη κατάσταση. Απόρριψη, λήξη χρόνου ή σύγκρουση ταυτόχρονης αλλαγής επιστρέφει 409 POWER_MANAGEMENT_CONFLICT διατηρώντας την προηγούμενη ρύθμιση.
Φορτιστές
| Μέθοδος | Διαδρομή | Απαιτούμενο πεδίο πρόσβασης | Σκοπός ή είσοδος |
|---|---|---|---|
GET | /v2/admin/chargers | chargers:read | Παραθέτει φορτιστές με κατάσταση και οριοθετημένα σύνολα ενέργειας/κόστους. |
POST | /v2/admin/chargers | chargers:create | Δημιουργεί από name, identifier και siteId, με προαιρετικό password. |
GET | /v2/admin/chargers/:chargerId | chargers:read | Διαβάζει δεδομένα φορτιστή, EVSE, υποδοχής, αναφοράς και κατάστασης. |
PATCH | /v2/admin/chargers/:chargerId | chargers:update | Ενημερώνει name, siteId, invertedRfid, smartMode ή automationDisabled. |
DELETE | /v2/admin/chargers/:chargerId | chargers:delete | Διαγράφει φορτιστή βάσει κανόνων εξαρτήσεων και χρέωσης. |
PATCH | /v2/admin/chargers/:chargerId/credentials | chargers:credentials | Αντικαθιστά τον κωδικό φορτιστή με { "password": "..." }. |
PATCH | /v2/admin/chargers/:chargerId/connectors/:portId | chargers:connector-settings | Ενημερώνει μορφή/τύπο υποδοχής, τύπο ισχύος, τάση, ρεύμα και όρια ισχύος. |
PATCH | /v2/admin/chargers/:chargerId/public-listing | chargers:public | Ορίστε `{ "isPublic": true |
GET | /v2/admin/chargers/:chargerId/public-readiness | chargers:read | Διαβάζει ετοιμότητα δημόσιας φόρτισης και ελλείπουσες απαιτήσεις. |
GET | /v2/admin/chargers/:chargerId/logs | chargers:read | Διαβάζει καταγραφές OCPP με απόκρυψη και σελιδοποίηση δρομέα. |
GET | /v2/admin/chargers/:chargerId/sessions | chargers:read + reports:read | Διαβάζει σελιδοποιημένες συνεδρίες και σύνολα. |
GET | /v2/admin/chargers/:chargerId/qr | chargers:read | Παράγει QR PNG 300 pixel· προαιρετικό connector=0..255. |
GET | /v2/admin/chargers/:chargerId/composite-schedules | chargers:read | Διαβάζει αποθηκευμένο ιστορικό σύνθετου προγράμματος. |
GET | /v2/admin/chargers/:chargerId/configuration | chargers:read | Διαβάζει ρυθμίσεις OCPP με απόκρυψη ευαίσθητων τιμών. |
PATCH | /v2/admin/chargers/:chargerId/configuration | chargers:configuration | Στέλνει αλλαγή ρύθμισης με key και value. |
POST | /v2/admin/chargers/:chargerId/configuration/reload | chargers:configuration | Ζητά νέα ρύθμιση φορτιστή. |
GET | /v2/admin/chargers/:chargerId/firmware | chargers:read | Διαβάζει τρέχον υλικολογισμικό και κατάσταση ενημέρωσης. |
POST | /v2/admin/chargers/:chargerId/firmware | chargers:firmware | Βάζει ενημέρωση από HTTP(S) { "url": "..." } στην ουρά. |
POST | /v2/admin/chargers/:chargerId/commands/reset | chargers:commands | Στείλτε `{ "resetType": "Soft" |
POST | /v2/admin/chargers/:chargerId/commands/availability | chargers:commands | Στείλτε `{ "availabilityType": "Operative" |
POST | /v2/admin/chargers/:chargerId/commands/trigger | chargers:commands | Ενεργοποιεί BootNotification, Heartbeat, StatusNotification ή MeterValues. |
POST | /v2/admin/chargers/:chargerId/commands/unlock | chargers:commands | Ξεκλειδώνει θετικό connectorId. |
POST | /v2/admin/chargers/:chargerId/commands/composite-schedule | chargers:commands | Ζητά σύνθετο πρόγραμμα για connectorId, durationSeconds και chargingRateUnit. |
Οι παράμετροι ερωτήματος καταγραφών φορτιστή είναι cursor, limit (προεπιλογή 50, μέγιστο 200), from, to, action, direction και levelId. Οι παράμετροι συνεδριών είναι page, limit (προεπιλογή 25, μέγιστο 100), from, to και customerId (θετικό ID ή unknown). Το ιστορικό σύνθετου προγράμματος χρησιμοποιεί cursor, limit (προεπιλογή 20, μέγιστο 50) και προαιρετικό connectorId.
Αναφορές
| Μέθοδος | Διαδρομή | Απαιτούμενο πεδίο πρόσβασης | Σκοπός |
|---|---|---|---|
GET | /v2/admin/reports/data | reports:read | Διαβάζει φιλτραρισμένα δεδομένα αναφοράς συνεδριών με σελιδοποίηση δρομέα. |
GET | /v2/admin/reports/measurements | reports:read | Διαβάζει οριοθετημένες μετρήσεις ιδιόκτητης συναλλαγής. |
GET | /v2/admin/reports/export | reports:export | Κατεβάστε εξαγωγή CSV ή PDF. |
GET | /v2/admin/reports/schedule | reports:read | Διαβάζει το πρόγραμμα εξαγωγής του χώρου εργασίας ή null. |
PUT | /v2/admin/reports/schedule | reports:schedules | Δημιουργεί ή αντικαθιστά το πρόγραμμα εξαγωγής του χώρου εργασίας. |
POST | /v2/admin/reports/send | reports:send | Στέλνει μέσω email την αποθηκευμένη εξαγωγή του προηγούμενου ημερολογιακού μήνα UTC· απαιτείται κλειδί ιδιοδυναμίας. |
Τα φίλτρα δεδομένων και εξαγωγής αναφορών είναι from, to, siteId, chargerId, userId, anonymous και active. Τα from/to προεπιλέγουν το τελευταίο διάστημα 90 ημερών και δεν υπερβαίνουν 90 ημέρες. Το userId δεν συνδυάζεται με anonymous=true.
- Σελιδοποίηση δεδομένων: αδιαφανές
cursor, προεπιλογήlimit=50, μέγιστο 100. - Μετρήσεις: απαιτούμενο
transactionLogId, αδιαφανέςcursor, προεπιλογήlimit=500, μέγιστο 1.000. - Εξαγωγή:
format=csv|pdf, προεπιλογήcsv, απόλυτο όριο 2.000 γραμμών. - Οι αποκρίσεις εξαγωγής χρησιμοποιούν
Content-Disposition: attachment,Cache-Control: private, no-storeκαιX-Content-Type-Options: nosniff.
Σώμα προγράμματος:
{
"enabled": true,
"recipientEmail": "reports@example.com",
"format": "csv",
"sendDay": 5,
"sendTime": "08:30"
}
Το sendDay είναι 1–28 και το sendTime ερμηνεύεται σε UTC. Ο χρονοπρογραμματιστής αναπληρώνει χαμένο προγραμματισμένο λεπτό εντός του τρέχοντος μήνα παράδοσης. Αποτυχίες δημιουργίας πριν την παράδοση επαναλαμβάνονται μετά 5 και 10 λεπτά, διακοπείσα δέσμευση building ανακτάται μετά 30 λεπτά και η αυτόματη παράδοση σταματά μετά τρεις προσπάθειες. Αποθηκεύει indeterminate αμέσως πριν την παράδοση SMTP· τόσο indeterminate όσο και παλιά κατάσταση sending είναι τελικές, επειδή η αυτόματη επανάληψη μπορεί να στείλει διπλό συνημμένο. Οι φορείς πρέπει να συμφωνήσουν χειροκίνητα τα αποτελέσματα πριν αλλάξουν κατάσταση προγράμματος. Κάθε κύκλος επιλέγει έως δέκα προγράμματα, σταματά να αρχίζει εργασίες μετά 45 δευτερόλεπτα και χρησιμοποιεί οριοθετημένα χρονικά όρια SMTP. Η εργασία είναι προεπιλεγμένα ανενεργή και ενεργοποιείται ρητά μετά επικύρωση SMTP και δυναμικότητας. Το πρόγραμμα API ανήκει στον χώρο εργασίας, δεν δανείζεται την ταυτότητα του δημιουργού διακριτικού.
Τιμολόγια
| Μέθοδος | Διαδρομή | Απαιτούμενο πεδίο πρόσβασης | Σκοπός |
|---|---|---|---|
GET | /v2/admin/tariffs | tariffs:read | Παραθέτει τιμολόγια και δεδομένα αναφοράς. |
POST | /v2/admin/tariffs | tariffs:create | Δημιουργήστε τιμολόγιο. |
GET | /v2/admin/tariffs/:tariffId | tariffs:read | Διαβάζει ένα ιδιόκτητο τιμολόγιο και τα στοιχεία του. |
PATCH | /v2/admin/tariffs/:tariffId | tariffs:update | Ενημερώνει τον ορισμό τιμολογίου. |
PUT | /v2/admin/tariffs/:tariffId/components | tariffs:components | Αντικαθιστά ατομικά έως 256 στοιχεία. |
DELETE | /v2/admin/tariffs/:tariffId | tariffs:delete | Διαγράφει αχρησιμοποίητο τιμολόγιο. |
GET | /v2/admin/tariffs/:tariffId/market-prices | tariffs:read | Διαβάζει τιμές ιδιόκτητης ζώνης προσφορών τιμολογίου από αριθμητικό startsAt. |
GET | /v2/admin/chargers/:chargerId/tariff-assignments | chargers:tariff-assignments + tariffs:read | Παραθέτει αναθέσεις τιμολογίων φορτιστή. |
POST | /v2/admin/chargers/:chargerId/tariff-assignments | chargers:tariff-assignments + tariffs:assign | Αναθέστε τιμολόγιο. |
PATCH | /v2/admin/chargers/:chargerId/tariff-assignments/:assignmentId | chargers:tariff-assignments + tariffs:assign | Αντικαθιστά τον στόχο ανάθεσης. |
DELETE | /v2/admin/chargers/:chargerId/tariff-assignments/:assignmentId | chargers:tariff-assignments + tariffs:assign | Αφαιρεί ανάθεση. |
Το σώμα τιμολογίου περιέχει name, ακριβώς ένα από currencyId, currencyCode ή currency, προαιρετικό biddingZoneId και tax. Το σώμα ανάθεσης είναι:
{ "tariffId": 17, "connectorId": 0 }
Κατά τη δημιουργία μιας ανάθεσης, το τιμολόγιο εφαρμόζεται σε όλες τις φυσικές υποδοχές αν το connectorId παραλειφθεί ή οριστεί ρητά σε 0. Οι ενημερώσεις στοχεύουν μία αποθηκευμένη ανάθεση και απαιτούν ρητό θετικό φυσικό connectorId· το 0 απορρίπτεται.
Ένα στοιχείο περιέχει typeId, seasonId, price, προαιρετικό priority και προαιρετικά όρια χρονικής ισχύος ανά μήνα, ημέρα εβδομάδας και ώρα.
Προφίλ φόρτισης
| Μέθοδος | Διαδρομή | Απαιτούμενο πεδίο πρόσβασης | Σκοπός |
|---|---|---|---|
GET | /v2/admin/charging-profiles | chargingProfiles:read | Παραθέτει προφίλ και ιδιόκτητα δεδομένα αναφοράς. |
POST | /v2/admin/charging-profiles | chargingProfiles:create | Δημιουργεί προφίλ με προαιρετικό πρόγραμμα. |
GET | /v2/admin/charging-profiles/:profileId | chargingProfiles:read | Διαβάζει ένα ιδιόκτητο προφίλ. |
PATCH | /v2/admin/charging-profiles/:profileId | chargingProfiles:update | Αντικαθιστά μεταδεδομένα προφίλ. |
PUT | /v2/admin/charging-profiles/:profileId/schedule | chargingProfiles:update | Αντικαθιστά το πρόγραμμα με 1–256 περιόδους. |
DELETE | /v2/admin/charging-profiles/:profileId | chargingProfiles:delete | Εκκαθαρίζει εγκατεστημένες αναθέσεις και διαγράφει μόνο μετά από αποδεκτά αποτελέσματα OCPP και επανεπικύρωση. |
GET | /v2/admin/chargers/:chargerId/profile-assignments | chargers:profile-assignments + chargingProfiles:read | Παραθέτει αναθέσεις προφίλ φορτιστή. |
POST | /v2/admin/chargers/:chargerId/profile-assignments | chargers:profile-assignments + chargingProfiles:assign | Αναθέτει και συγχρονίζει προφίλ. |
PATCH | /v2/admin/chargers/:chargerId/profile-assignments/:assignmentId | chargers:profile-assignments + chargingProfiles:assign | Αντικαθιστά και συγχρονίζει ανάθεση. |
DELETE | /v2/admin/chargers/:chargerId/profile-assignments/:assignmentId | chargers:profile-assignments + chargingProfiles:assign | Εκκαθαρίζει και αφαιρεί ανάθεση. |
Τα πεδία μεταδεδομένων προφίλ είναι label, locationId, stackLevel, purposeId, kindId, προαιρετικά recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId και προαιρετικό minChargingRate. Η περίοδος προγράμματος περιέχει startPeriod, limit και προαιρετικό numberOfPhases. Το σώμα ανάθεσης περιέχει profileId και connectorId (προεπιλογή 0).
Οι διαγραφές προφίλ και η αντικατάσταση διαχείρισης ισχύος μπορεί να περιμένουν επιβεβαίωση φορτιστή. Απόρριψη, λήξη χρόνου ή ταυτόχρονη αλλαγή κατάστασης επιστρέφει διένεξη και διατηρεί τη ρύθμιση βάσης, χωρίς να προσποιείται ότι ο φορτιστής εκκαθαρίστηκε.
Χρήστες, προσκλήσεις, RFID, πρόσβαση και όρια
| Μέθοδος | Διαδρομή | Απαιτούμενο πεδίο πρόσβασης | Σκοπός |
|---|---|---|---|
GET | /v2/admin/users | users:read | Παραθέτει μέλη και προσκλήσεις. |
POST | /v2/admin/users | users:create | Συνδέει ήδη εγγεγραμμένο πελάτη μέσω email και name χώρου εργασίας. |
POST | /v2/admin/users/invitations | users:invitations + users:access· επίσης users:rfid όταν παρέχεται RFID | Προσκαλεί άγνωστο email ή συνδέει υπάρχοντα πελάτη. |
POST | /v2/admin/users/invitations/resend | users:invitations | Ξαναστέλνει με { "email": "..." }, υπό την αναμονή παραλήπτη. |
DELETE | /v2/admin/users/invitations | users:invitations | Ακυρώνει πρόσκληση· το email παραμένει στο σώμα JSON. |
GET | /v2/admin/users/:userId | users:read + reports:read | Διαβάζει στοιχεία χρήστη και οριοθετημένα σύνολα συνεδριών. |
PATCH | /v2/admin/users/:userId | users:update | Ορίζει το εμφανιζόμενο name ανά χώρο εργασίας. |
DELETE | /v2/admin/users/:userId | users:delete | Αφαιρεί μέλος και σχετική πρόσβαση χώρου εργασίας υπό τους περιορισμούς διενέξεων. |
GET | /v2/admin/users/:userId/vehicles | users:read | Παραθέτει ιδιόκτητα οχήματα. |
GET | /v2/admin/users/:userId/rfids | users:read | Παραθέτει μεταδεδομένα RFID με καλυμμένα UID. |
POST | /v2/admin/users/:userId/rfids | users:rfid | Προσθέτει uid και προαιρετικό name· οι αποκρίσεις εμφανίζουν μόνο καλυμμένο UID. |
PATCH | /v2/admin/users/:userId/rfids/:rfidId | users:rfid | Ενημερώνει την ετικέτα RFID. |
DELETE | /v2/admin/users/:userId/rfids/:rfidId | users:rfid | Διαγράφει RFID και συγχρονίζει τους επηρεαζόμενους φορτιστές. |
GET | /v2/admin/users/:userId/access | users:read | Διαβάζει δικαιώματα πρόσβασης φορτιστή. |
PUT | /v2/admin/users/:userId/access | users:access | Αντικαθιστά πρόσβαση με allChargers και μοναδικό chargerIds. |
DELETE | /v2/admin/users/:userId/access/:accessId | users:access | Ανακαλεί μία εγγραφή πρόσβασης. |
GET | /v2/admin/users/:userId/limits | users:read | Παραθέτει όρια φόρτισης. |
POST | /v2/admin/users/:userId/limits | users:limits | Δημιουργεί limitTypeId, energyValue και/ή timeValue. |
PATCH | /v2/admin/users/:userId/limits/:limitId | users:limits | Ενημερώνει ένα ή περισσότερα πεδία ορίων. |
DELETE | /v2/admin/users/:userId/limits/:limitId | users:limits | Διαγράφει όριο. |
GET | /v2/admin/chargers/:chargerId/local-users | chargers:read + users:read | Παραθέτει τοπικούς χρήστες φορτιστή και εκκρεμείς προσκλήσεις. |
POST | /v2/admin/chargers/:chargerId/local-users | chargers:local-users + users:access | Προσθέτει υπάρχον customerId με προαιρετικό expiresAt. |
POST | /v2/admin/chargers/:chargerId/local-users/invitations | chargers:local-users + users:invitations + users:access | Προσθέστε ή προσκαλέστε μέσω email. |
DELETE | /v2/admin/chargers/:chargerId/local-users/invitations | chargers:local-users + users:invitations | Ακυρώνει πρόσκληση τοπικού χρήστη βάσει email. |
PATCH | /v2/admin/chargers/:chargerId/local-users/:localUserId | chargers:local-users + users:access | Ορίζει expiresAt που επιτρέπει null. |
DELETE | /v2/admin/chargers/:chargerId/local-users/:localUserId | chargers:local-users + users:access | Αφαιρεί τοπική πρόσβαση και συγχρονίζει κατάσταση OCPP. |
Η σελιδοποίηση οχημάτων και χρηστών status=members χρησιμοποιεί θετικό αριθμητικό cursor. Οι προσκλήσεις χρησιμοποιούν αδιαφανή δρομέα i2.*, ενώ το status=all χρησιμοποιεί αδιαφανή σύνθετο a2.* μετά την πρώτη σελίδα (αριθμητικός δρομέας παραμένει έγκυρος μόνο ως συνέχεια παλιού ρεύματος μελών). Η αναζήτηση χρήστη δίνεται στην κεφαλίδα X-Admin-User-Search για να μη μπαίνουν email σε URL ή καταγραφές πρόσβασης. Το limit προεπιλέγει 50 και περιορίζεται σε 100· η λίστα υποστηρίζει status=all|members|invitations. Αντιμετωπίστε κάθε επιστρεφόμενο δρομέα ως αδιαφανή και επιστρέψτε τον αμετάβλητο.
Η άμεση δημιουργία χρήστη δεν δημιουργεί κωδικό, ταυτότητα σύνδεσης ή συνεδρία. Συνδέει μόνο ήδη εγγεγραμμένο πελάτη. Για άγνωστο email χρησιμοποιήστε το endpoint πρόσκλησης. Ο προστατευμένος χρήστης συστήματος Tagless δεν τροποποιείται μέσω αυτών των διαδρομών.
Παραδείγματα
Ορίστε τιμές στο κέλυφος χωρίς εκτύπωση διακριτικού:
export ADMIN_API_BASE_URL="https://api.example.com"
export WORKSPACE_TOKEN="<read from secret manager>"
Λίστα τοποθεσιών:
curl --fail-with-body \
-H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
"${ADMIN_API_BASE_URL}/v2/admin/sites"
Δημιουργήστε τοποθεσία με ασφάλεια:
curl --fail-with-body \
-X POST \
-H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: site-main-depot-v1" \
--data '{
"name":"Main depot",
"description":null,
"addressLine1":"1 Example Street",
"addressLine2":null,
"postalCode":"LV-1001",
"city":"Riga",
"state":null,
"countryId":1,
"timezoneId":1,
"latitude":56.9496,
"longitude":24.1052
}' \
"${ADMIN_API_BASE_URL}/v2/admin/sites"
Κατεβάστε αναφορά CSV για ρητό διάστημα UTC:
curl --fail-with-body \
-H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
-o report.csv \
"${ADMIN_API_BASE_URL}/v2/admin/reports/export?format=csv&from=2026-07-01T00%3A00%3A00Z&to=2026-08-01T00%3A00%3A00Z"
Σκόπιμες εξαιρέσεις
Το API διακριτικών χώρου εργασίας δεν εκθέτει λειτουργίες που απαιτούν ανθρώπινη ταυτότητα ή ευρύτερη εξουσία. Περιλαμβάνουν:
- δημιουργία, αποκάλυψη, περιστροφή ή ανάκληση διακριτικών με άλλο διακριτικό·
- σύνδεση, επαναφορά κωδικού, συνεδρίες, ανάθεση ανθρώπινων ρόλων ή προνομίων και αλλαγές ιδιοκτησίας χώρου εργασίας·
- δημιουργία/διαγραφή χώρου εργασίας και συμμετοχή σε λογαριασμό χρέωσης·
- ρυθμίσεις πληρωμής, ένταξη Stripe, προγράμματα, παραστατικά και χρέωση κεντρικού συστήματος·
- λειτουργίες υποστήριξης όλου του κεντρικού συστήματος και webhooks παρόχων·
- ειδοποιήσεις ανθρώπων, ανακατευθύνσεις, στοιχεία επωνυμίας και διαδρομές ανάπτυξης/δοκιμών.