Contractul de răspunsuri și erori al API-ului de administrare

Acest fișier completează contractul de răspuns pentru fiecare endpoint din Referința endpointurilor. Citește rândul endpointului pentru corpul său de succes și tabelele de mai jos pentru fiecare corp de nereușită comun sau specific endpointului. Implicit, erorile folosesc mai multe structuri de compatibilitate; apelanții pot opta pentru o singură anvelopă universală.

Anvelopă structurată opțională pentru erori

Trimite acest antet de cerere la orice endpoint:

X-Error-Format: envelope

Comparația valorii elimină spațiile de la capete și nu distinge literele mari de cele mici. Cu acea valoare exactă, fiecare răspuns JSON cu starea 400 sau mai mare este convertit în:

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

Exemplu de conversie a unui corp de validare implicit:

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

Regulile de conversie sunt exacte:

• validationErrors devine details.fields, iar code devine VALIDATION_FAILED chiar dacă corpul implicit avea și un cod de domeniu.
• Un code implicit la nivel superior este păstrat când nu există câmpuri de validare.
• Celelalte proprietăți de nivel superior, în afară de error, message, validationErrors și code, sunt mutate în details; de exemplu, limit al exportului de rapoarte devine details.limit.
• Un error de tip șir la nivel superior devine message. Dacă nu există, este folosită valoarea de rezervă a stării.
• Codurile de rezervă sunt AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 și alte 4xx neclasificate), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) și INTERNAL_ERROR (alte 5xx, inclusiv 503).
• requestId este antetul de răspuns exact X-Request-Id. Un ID de cerere furnizat de apelant este folosit doar dacă se potrivește cu [A-Za-z0-9._:-]{1,128} după eliminarea spațiilor de la capete; altfel serverul generează un UUID.

Această transformare nu modifică starea sau antetele care nu țin de corp. Se aplică și reluărilor idempotente conform antetului X-Error-Format al cererii de reluare. Răspunsurile binare de succes rămân binare; erorile lor JSON sunt încapsulate. Tabelele rămase afișează corpurile implicite; aplicarea regulilor de mai sus produce celălalt corp de răspuns posibil pentru fiecare rând.

Notația răspunsurilor

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

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

PlainError = { error: string }

error și textul mesajelor de validare sunt descriptive, nu un discriminator programatic stabil. Diferențiază cazurile pe baza lui code când este prezent. Validarea cererii returnează 422 ValidationError; validarea unui obiect întreg poate produce { "validationErrors": {} } când nu este identificat un câmp individual. JSON-ul nevalid și erorile neașteptate returnează răspunsul global 500 PlainError afișat mai jos.

Toate exemplele JSON reprezintă structurile exacte ale corpului. Textul afișat ca <message> este mesajul de validare sau de operare returnat și este un șir JSON, nu o valoare literală între paranteze unghiulare.

Ordinea de procesare a cererilor

Cererile sunt procesate în această ordine:

1. configurarea și autentificarea tokenurilor spațiului de lucru;
2. politica gazdei și limitele de rată ale tokenului/spațiului de lucru;
3. filtrarea drepturilor curente;
4. pentru fiecare modificare, validare/rezervare de idempotență;
5. verificările domeniilor de acces ale endpointului, validarea cererii și operațiunea solicitată.

Prin urmare, o modificare cu un token valid, dar cu domenii de acces insuficiente, trebuie în continuare să trimită Idempotency-Key. Răspunsul unei modificări 403, 404, 409 sau 422 finalizate poate fi reluat pentru aceeași cheie/cerere.

Răspunsuri de autentificare, politică și limitare a ratei

Aceste răspunsuri pot apărea la fiecare endpoint /v2/admin înregistrat, înainte de procesarea specifică endpointului.

Accesul API este inclus în fiecare plan. Dezactivarea setării adminApiEnabled a gazdei spațiului de lucru returnează 404; pierderea dreptului la o funcție suplimentară elimină doar domeniile de acces afectate. Refuzul domeniului de acces rezultat folosește răspunsul de mai jos, nu un flux de reîmprospătare a tokenului.

Erori de domeniu de acces, idempotență, parsare, proprietate și erori neașteptate

ID-urile din căile resurselor trebuie să fie numere pozitive. Un :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId sau :localUserId nepozitiv ori nenumeric returnează 422 ValidationError, nu 400.

Erori pentru locații și gestionarea puterii

Erori ale stațiilor

mapChargerErrors() este folosit de crearea/actualizarea stațiilor, credențiale, setări de conector, listare publică, rezolvarea conținutului QR, modificarea/reîncărcarea configurației, pornirea firmware-ului, toate cele patru comenzi de bază și cererea de program compozit.

Operațiunile simple de citire returnează doar răspunsurile comune 401/403/404/429/500/503, plus validarea interogării/căii 422. Ștergerea unei stații poate returna răspunsul comun 500 PlainError dacă ștergerea eșuează fără un răspuns de eroare mai specific.

Erori ale rapoartelor

Exportul reușit este binar; toate erorile de export rămân JSON.

Erori ale tarifelor

Erori ale profilurilor de încărcare

Erori ale domeniului utilizatorilor

Erorile de validare ale utilizatorilor care identifică un câmp folosesc ValidationError plus code; celelalte erori ale utilizatorilor folosesc CodedError. Toate cazurile de resurse lipsă folosesc răspunsul comun RESOURCE_NOT_FOUND, care nu permite enumerarea.

POST /users/invitations poate returna și răspunsul comun 403 INSUFFICIENT_SCOPE după parsarea corpului dacă lipsește users:access sau dacă a fost furnizat un RFID și lipsește users:rfid. Endpointurile pentru utilizatori locali enumeră fiecare domeniu de acces obligatoriu în Referința endpointurilor.

Codurile de eroare ale utilizatorilor se aplică astfel:

Toate rezultatele privind proprietatea și resursele lipsă din acele familii, inclusiv o adresă de email neînregistrată pe POST /users, folosesc corpul comun 404 RESOURCE_NOT_FOUND.

Răspunsuri fără corp și de reluare

Un răspuns 204 reușit nu are corp. Acest lucru se aplică fiecărei ștergeri documentate care enumeră 204 empty. O reluare idempotentă finalizată setează Idempotency-Replayed: true și folosește starea/corpul stocat; pentru 204, răspunsul HTTP rămâne fără corp. API-ul nu returnează niciodată un obiect JSON de succes pentru o operațiune 204 documentată.