Σύμβαση αποκρίσεων και σφαλμάτων Admin API

Αυτό το αρχείο συμπληρώνει τη σύμβαση απόκρισης κάθε endpoint στην Αναφορά endpoints. Διαβάστε τη γραμμή του για επιτυχές σώμα και τους παρακάτω πίνακες για κάθε κοινό ή ειδικό ανεπιτυχές σώμα. Τα σφάλματα χρησιμοποιούν προεπιλεγμένα διάφορες δομές συμβατότητας· οι καλούντες μπορούν να επιλέξουν έναν καθολικό φάκελο.

Προαιρετικός δομημένος φάκελος σφαλμάτων

Στείλτε αυτή την κεφαλίδα σε οποιοδήποτε endpoint:

X-Error-Format: envelope

Η σύγκριση τιμής αφαιρεί περιφερειακά κενά και αγνοεί πεζά/κεφαλαία. Με αυτή την ακριβή τιμή, κάθε απόκριση JSON με κατάσταση 400 ή υψηλότερη μετατρέπεται σε:

ErrorEnvelope = {
  error: {
    code: string,
    message: string,
    details: Record<string, unknown>,
    requestId: string
  }
}

Παράδειγμα μετατροπής προεπιλεγμένου σώματος επικύρωσης:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid request",
    "details": {
      "fields": {
        "name": ["String must contain at least 1 character(s)"]
      }
    },
    "requestId": "integration-42"
  }
}

Οι κανόνες μετατροπής είναι ακριβείς:

• Το validationErrors γίνεται details.fields και το code γίνεται VALIDATION_FAILED, ακόμη αν το προεπιλεγμένο σώμα είχε κωδικό τομέα.
• Το προεπιλεγμένο code ανώτατου επιπέδου διατηρείται όταν δεν υπάρχουν πεδία επικύρωσης.
• Οι άλλες ιδιότητες ανώτατου επιπέδου εκτός error, message, validationErrors και code μετακινούνται στο details· π.χ. το limit εξαγωγής αναφοράς γίνεται details.limit.
• Ένα error συμβολοσειράς ανώτατου επιπέδου γίνεται message. Αν δεν υπάρχει, χρησιμοποιείται η εφεδρική τιμή κατάστασης.
• Οι εφεδρικοί κωδικοί είναι AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 και άλλα μη ταξινομημένα 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) και INTERNAL_ERROR (άλλα 5xx, περιλαμβανομένου του 503).
• Το requestId είναι η ακριβής κεφαλίδα απόκρισης X-Request-Id. ID αιτήματος του καλούντος χρησιμοποιείται μόνο αν ταιριάζει με [A-Za-z0-9._:-]{1,128} μετά περικοπή· αλλιώς ο διακομιστής δημιουργεί UUID.

Η μετατροπή δεν αλλάζει κατάσταση ή κεφαλίδες άσχετες με το σώμα. Ισχύει και σε ιδιοδύναμες επαναλήψεις βάσει της κεφαλίδας X-Error-Format του επαναληπτικού αιτήματος. Οι δυαδικές επιτυχείς αποκρίσεις παραμένουν δυαδικές· τα JSON σφάλματά τους μπαίνουν σε φάκελο. Οι υπόλοιποι πίνακες δείχνουν προεπιλεγμένα σώματα· οι παραπάνω κανόνες δίνουν το άλλο πιθανό σώμα για κάθε γραμμή.

Σημειογραφία αποκρίσεων

ValidationError = {
  validationErrors: Record<string, string[]>,
  code?: string
}

CodedError = {
  error: string,
  code: string,
  // a route may add fields explicitly listed below
}

PlainError = { error: string }

Το error και το κείμενο επικύρωσης είναι περιγραφικά, όχι σταθερό προγραμματιστικό κριτήριο. Διακλαδώστε βάσει code όταν υπάρχει. Η επικύρωση αιτήματος επιστρέφει 422 ValidationError· επικύρωση ολόκληρου αντικειμένου μπορεί να δώσει { "validationErrors": {} } αν δεν ορίζεται πεδίο. Μη έγκυρο JSON και απρόβλεπτες αποτυχίες επιστρέφουν το καθολικό 500 PlainError παρακάτω.

Όλα τα παραδείγματα JSON είναι ακριβείς δομές σώματος. Το κείμενο <message> είναι το επιστρεφόμενο μήνυμα επικύρωσης ή λειτουργίας και είναι συμβολοσειρά JSON, όχι κυριολεκτική τιμή σε αγκύλες γωνίας.

Σειρά επεξεργασίας αιτήματος

Τα αιτήματα επεξεργάζονται με αυτή τη σειρά:

1. ρύθμιση και έλεγχος ταυτότητας διακριτικών χώρου εργασίας·
2. πολιτική κεντρικού συστήματος και όρια διακριτικού/χώρου εργασίας·
3. φιλτράρισμα τρεχόντων δικαιωμάτων·
4. για κάθε μεταβολή, επικύρωση/δέσμευση ιδιοδυναμίας·
5. έλεγχοι πεδίων πρόσβασης endpoint, επικύρωση αιτήματος και ζητούμενη λειτουργία.

Συνεπώς, μια μεταβολή με έγκυρο αλλά ανεπαρκές διακριτικό πρέπει επίσης να στέλνει Idempotency-Key. Μια ολοκληρωμένη απόκριση μεταβολής 403, 404, 409 ή 422 επαναλαμβάνεται με το ίδιο κλειδί/αίτημα.

Αποκρίσεις ελέγχου ταυτότητας, πολιτικών και περιορισμού αιτημάτων

Αυτές οι αποκρίσεις μπορούν να προκύψουν σε κάθε καταχωρισμένο endpoint /v2/admin πριν την ειδική επεξεργασία του.

Η πρόσβαση API περιλαμβάνεται σε κάθε πρόγραμμα. Η απενεργοποίηση της ρύθμισης adminApiEnabled του κεντρικού συστήματος επιστρέφει 404· η απώλεια πρόσθετου δικαιώματος λειτουργίας αφαιρεί μόνο τα επηρεαζόμενα πεδία πρόσβασης. Η προκύπτουσα άρνηση χρησιμοποιεί την παρακάτω απόκριση, όχι διαδικασία ανανέωσης διακριτικού.

Πεδίο πρόσβασης, ιδιοδυναμία, ανάλυση, ιδιοκτησία και απρόβλεπτες αποτυχίες

Τα ID διαδρομών πόρων πρέπει να είναι θετικοί αριθμοί. Μη θετικό ή μη αριθμητικό :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId ή :localUserId επιστρέφει 422 ValidationError, όχι 400.

Σφάλματα τοποθεσίας και διαχείρισης ισχύος

Σφάλματα φορτιστών

Το mapChargerErrors() χρησιμοποιείται για δημιουργία/ενημέρωση φορτιστή, διαπιστευτήρια, ρυθμίσεις υποδοχής, δημόσια καταχώριση, επίλυση περιεχομένου QR, μεταβολή/επαναφόρτωση ρυθμίσεων, έναρξη υλικολογισμικού, τέσσερις βασικές εντολές και αίτημα σύνθετου προγράμματος.

Οι απλές αναγνώσεις επιστρέφουν μόνο τις κοινές αποκρίσεις 401/403/404/429/500/503 και επικύρωση ερωτήματος/διαδρομής 422. Η διαγραφή φορτιστή μπορεί να επιστρέψει κοινό 500 PlainError αν αποτύχει χωρίς πιο συγκεκριμένο σφάλμα.

Σφάλματα αναφορών

Η επιτυχής εξαγωγή είναι δυαδική· όλα τα σφάλματα εξαγωγής παραμένουν JSON.

Σφάλματα τιμολογίων

Σφάλματα προφίλ φόρτισης

Σφάλματα τομέα χρηστών

Σφάλματα επικύρωσης χρήστη που ορίζουν πεδίο χρησιμοποιούν ValidationError και code· άλλα χρησιμοποιούν CodedError. Όλες οι ελλείψεις πόρων χρησιμοποιούν την κοινή μη αποκαλυπτική απόκριση RESOURCE_NOT_FOUND.

Το POST /users/invitations μπορεί επίσης να επιστρέψει κοινό 403 INSUFFICIENT_SCOPE μετά την ανάλυση σώματος αν λείπει users:access, ή αν δόθηκε RFID και λείπει users:rfid. Τα endpoints τοπικών χρηστών αναφέρουν κάθε απαιτούμενο πεδίο πρόσβασης στην Αναφορά endpoints.

Οι κωδικοί σφαλμάτων χρηστών ισχύουν ως εξής:

Όλα τα αποτελέσματα ιδιοκτησίας και απόντων πόρων σε αυτές τις ομάδες, ακόμη και μη εγγεγραμμένο email στο POST /users, χρησιμοποιούν το κοινό σώμα 404 RESOURCE_NOT_FOUND.

Αποκρίσεις χωρίς σώμα και επαναλήψεων

Μια επιτυχής απόκριση 204 δεν έχει σώμα. Αυτό ισχύει για κάθε τεκμηριωμένη διαγραφή που αναφέρει 204 empty. Μια ολοκληρωμένη ιδιοδύναμη επανάληψη ορίζει Idempotency-Replayed: true και χρησιμοποιεί την αποθηκευμένη κατάσταση/σώμα· για 204, η απόκριση HTTP παραμένει χωρίς σώμα. Το API δεν επιστρέφει ποτέ αντικείμενο επιτυχίας JSON για τεκμηριωμένη λειτουργία 204.