API de administrare a spațiului de lucru

API-ul de administrare a spațiului de lucru permite integrărilor server-la-server să administreze un singur spațiu de lucru EVCharge. Documentația este destinată administratorilor spațiilor de lucru și integratorilor API externi. Folosește tokenuri de acces revocabile, legate de spațiul de lucru, și domenii de acces detaliate; tokenurile de autentificare ale clienților și sesiunile de browser nu sunt acceptate.

Acest director este referința canonică pentru dezvoltatori a API-ului /v2/admin implementat de app-api. Nu documentează rutele pentru clienți/mobile sau rutele HTTP proprii ale portalului de administrare.

• Cererile și răspunsurile endpointurilor enumeră toate cele 87 de endpointuri înregistrate, domeniile de acces, parametrii, corpurile cererilor și corpurile de succes.
• Scheme și exemple definește tipurile reutilizabile de cereri/răspunsuri și corpurile JSON reprezentative.
• Contractul de răspunsuri și erori definește fiecare corp de nereușită comun și specific endpointurilor.

URL de bază și limita resurselor

Toate rutele sunt relative la originea implementată app-api:

https://api.evcharge.mobi/v2/admin/...

ID-ul spațiului de lucru nu este acceptat în URL, șirul de interogare sau corpul cererii. Fiecare token de acces este legat de exact un spațiu de lucru, iar API-ul derivă cpoId din identitatea tokenului autentificat. Dacă o locație, stație, utilizator, tarif, profil, atribuire sau tranzacție imbricată nu aparține acelui spațiu de lucru, API-ul returnează același răspuns 404 RESOURCE_NOT_FOUND care nu permite enumerarea resurselor.

Obținerea unui token de acces

Un administrator uman al spațiului de lucru creează tokenuri în Setările spațiului de lucru, la Acces API. Gestionarea tokenurilor nu este expusă intenționat tokenurilor spațiului de lucru.

• Accesul API este inclus în fiecare plan, inclusiv Free. Administratorul trebuie să aibă permisiunea de editare a spațiului de lucru.
• Gazda spațiului de lucru trebuie să activeze API-ul de administrare prin adminApiEnabled; altfel, un token valid primește un 404 care nu permite enumerarea de la app-api.
• Administratorul poate acorda doar domenii de acces permise de propriile permisiuni curente și drepturile spațiului de lucru.
• Tokenurile noi pot să nu expire (setarea implicită din Setările spațiului de lucru) sau pot avea o durată în zile întregi aleasă de administrator, între 1 și 365 de zile; serverul calculează momente absolute finite de expirare. Tokenurile fără expirare rămân valide până la revocare.
• Un spațiu de lucru poate avea cel mult 50 de tokenuri active.
• Credențialul în clar este afișat o singură dată. Stochează-l imediat într-un manager de secrete.
• Numele, domeniile de acces și expirarea sunt imuabile. Pentru rotație, creează un înlocuitor, implementează-l, verifică-l și revocă tokenul vechi.
• Revocarea este imediată; rândurile revocate rămân vizibile ca istoric imuabil și redactat al spațiului de lucru și nu există endpoint de introspecție a tokenurilor bearer sau de ștergere definitivă.

app-api nu are un endpoint care emite, reîmprospătează, listează sau revocă aceste credențiale. Obținerea tokenului este, așadar, o condiție prealabilă realizată prin portalul uman de administrare, nu un alt endpoint din această referință.

Nu pune niciodată tokenul în controlul versiunilor, URL-uri, șiruri de interogare, cookie-uri, jurnale, analize sau rapoarte de eroare.

Autentificare

Trimite exact un antet în stil RFC 6750 la fiecare cerere:

Authorization: Bearer evc_ws_<selector>.<secret>

Credențialul opac exact este evc_ws_ urmat de un selector base64url canonic de 16 caractere, . și un secret base64url canonic de 43 de caractere. Trimite credențialul complet exact cum este; nu îl codifica din nou în base64.

API-ul respinge antetele de autorizare duplicate, valorile unite prin virgule, alte scheme, valorile bearer goale, JWT-urile clienților și datele de autentificare furnizate în altă parte decât în acest antet.

Tokenurile malformate, necunoscute, expirate, revocate sau nevalide din alte motive primesc toate același răspuns:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Cache-Control: no-store
Content-Type: application/json

{
  "error": "Unauthorized",
  "code": "INVALID_WORKSPACE_TOKEN"
}

Serviciul verifică starea tokenului și drepturile curente ale spațiului de lucru la fiecare cerere. Eliminarea unui drept poate, așadar, dezactiva domeniile afectate înainte de expirarea tokenului.

Tokenurile spațiului de lucru sunt credențiale opace, nu JWT-uri. Nu au token de reîmprospătare și nu există endpoint de reîmprospătare. Un token finit nu mai autentifică la momentul absolut expiresAt; un token fără expirare rămâne valid până la revocare. Rotația înseamnă crearea unui credențial înlocuitor în portal, implementarea lui în client și revocarea celui vechi.

Convenții pentru cereri

• Folosește Content-Type: application/json pentru cereri cu corp JSON.
• Spațiile de la capetele valorilor opționale de cerere X-Request-Id sunt eliminate, iar valorile sunt acceptate doar dacă au 1–128 de caractere din A-Z, a-z, 0-9, ., _, : sau -; altfel serverul generează un UUID. Fiecare răspuns returnează valoarea aleasă ca X-Request-Id.
• Opțiunea X-Error-Format: envelope convertește fiecare răspuns de eroare JSON în anvelopa structurată documentată în Contractul de răspunsuri și erori. Orice altă valoare păstrează corpul implicit de compatibilitate.
• ID-urile din parametrii căii sunt numere întregi pozitive. ID-urile tokenurilor de acces returnate de portal sunt șiruri zecimale deoarece reprezintă valori de bază de date pe 64 de biți fără semn.
• Valorile de dată și oră sunt șiruri RFC 3339 cu un decalaj explicit, de exemplu 2026-08-13T12:30:00Z.
• Ștergerile reușite returnează de obicei 204 No Content.
• Operațiunile de creare returnează de obicei 201 Created.
• O activitate OCPP care a fost doar pusă în coadă poate returna 202 Accepted; nu interpreta acest lucru ca pe o confirmare a stației, decât dacă răspunsul o spune explicit.
• Răspunsurile autentificate folosesc Cache-Control: no-store. Endpointurile QR și de export al rapoartelor returnează corpuri binare cu antete explicite de conținut.
• Originile de browser permise pot citi X-Request-Id, Idempotency-Replayed, Retry-After și Content-Disposition prin CORS. Astfel, clienții de browser pot corela cereri, detecta reluări idempotente, respecta intervalele de reîncercare și păstra numele fișierelor descărcate alese de server.

Idempotență

Toate cererile administrative POST, PUT, PATCH și DELETE trebuie să includă un antet Idempotency-Key. Cheile conțin 1–255 de caractere vizibile și sunt limitate la token, metodă și cale.

Idempotency-Key: provisioning-2026-08-13-site-42

Reutilizarea unei chei finalizate cu URL și corp identice reia răspunsul stocat și adaugă:

Idempotency-Replayed: true

Reutilizarea unei chei cu o cerere diferită returnează 409 IDEMPOTENCY_CONFLICT. O cerere încă în curs de procesare returnează 409 IDEMPOTENT_REQUEST_PROCESSING cu Retry-After: 5.

Răspunsurile finalizate și rezultatele terminale sunt păstrate pentru reluare sau reconciliere timp de șapte zile de la ultima actualizare. După această perioadă, aceeași cheie poate fi tratată ca o comandă nouă, deci clienții trebuie să folosească chei unice global și să nu le reutilizeze intenționat.

Dacă expiră o rezervare de procesare, conexiunea se închide după începerea execuției sau operațiunea returnează o eroare de server, API-ul nu poate demonstra în siguranță dacă s-a produs un efect extern. În intervalul de păstrare de șapte zile, cheia este definitiv nedeterminată și returnează 409 IDEMPOTENCY_OUTCOME_UNKNOWN; nu este recuperată și nu este executată din nou automat. Verifică efectele operațiunii înainte de o recuperare manuală și nu trimite aceeași operațiune cu o cheie nouă până când reconcilierea nu este încheiată.

Toate endpointurile administrative care modifică date, inclusiv POST /reports/send, necesită Idempotency-Key.

Limite de rată

Limitele se aplică atât tokenului individual, cât și spațiului său de lucru. Valorile implicite din cod sunt:

O cerere limitată returnează 429 Too Many Requests și un antet Retry-After. Implementările pot suprascrie aceste valori.

Erori

Erorile JSON folosesc un code stabil când apelantul trebuie să distingă între cazuri:

{
  "error": "Insufficient workspace-token scope",
  "code": "INSUFFICIENT_SCOPE"
}

Erorile de validare folosesc tablouri de câmpuri:

{
  "validationErrors": {
    "name": ["String must contain at least 1 character(s)"]
  }
}

Stările frecvente sunt:

Catalogul domeniilor de acces

Catalogul de domenii de acces de mai jos este folosit când un administrator creează un token. Un domeniu de scriere sau cu impact mare poate implica domeniul de citire corespunzător, dar domeniile de citire nu acordă niciodată scriere. Domeniile disponibile depind de permisiunile administratorului și de funcțiile activate ale spațiului de lucru.

Accesul API în sine este inclus în fiecare plan și este controlat de setarea adminApiEnabled a gazdei. Drepturile suplimentare la funcțiile de mai sus se aplică în continuare; accesul API nu acordă funcții din afara planului spațiului de lucru.

Referința endpointurilor

Tabelele de mai jos enumeră toate cele 87 de rute de administrare a spațiului de lucru. Toate domeniile de acces dintr-o celulă cu mai multe sunt obligatorii.

Spațiu de lucru

Câmpuri de actualizare parțială a spațiului de lucru: name, email, website, addressLine1, addressLine2, postalCode, city, state și countryId. Este necesar cel puțin un câmp. Șirurile goale care pot fi null sunt normalizate la null.

Locații și gestionarea puterii

Corpurile de creare și actualizare parțială ale locațiilor folosesc:

{
  "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
}

Geocodificarea locațiilor acceptă câmpurile opționale de interogare street, city, state, country și countryCode din două litere, plus antetul de cerere Accept-Language. Căutarea combinată de stradă/oraș/stat trebuie să conțină cel puțin două caractere. Răspunsurile conțin doar placeId, displayName, latitude și longitude; nu sunt expuse datele de autentificare și metadatele specifice furnizorului. Serverul aplică coada comună a furnizorului de o cerere pe secundă, limita de timp de opt secunde, cache-ul limitat de 24 de ore și limitele globale de rată ale tokenurilor spațiului de lucru.

Gestionarea puterii acceptă { "pools": [...] }. Un grup are id, name, limit, opțional meterSources și children recursiv. Un element copil de tip stație are chargepointId și priority. API-ul limitează dimensiunea arborelui și numărul contoarelor și efectuează ștergere/revalidare OCPP în două faze când înlocuiește starea instalată. O modificare refuzată, expirată sau afectată de concurență returnează 409 POWER_MANAGEMENT_CONFLICT, păstrând configurația precedentă.

Stații de încărcare

Parametrii de interogare ai jurnalelor stației sunt cursor, limit (implicit 50, maximum 200), from, to, action, direction și levelId. Parametrii sesiunilor sunt page, limit (implicit 25, maximum 100), from, to și customerId (un ID pozitiv sau unknown). Istoricul programului compozit folosește cursor, limit (implicit 20, maximum 50) și opțional connectorId.

Rapoarte

Filtrele pentru datele rapoartelor și export sunt from, to, siteId, chargerId, userId, anonymous și active. from/to au implicit ultimul interval de 90 de zile și nu pot depăși 90 de zile. userId nu poate fi combinat cu anonymous=true.

• Paginarea datelor: cursor opac, implicit limit=50, maximum 100.
• Măsurători: transactionLogId obligatoriu, cursor opac, implicit limit=500, maximum 1.000.
• Export: format=csv|pdf, implicit csv, limită strictă de 2.000 de rânduri.
• Răspunsurile de export folosesc Content-Disposition: attachment, Cache-Control: private, no-store și X-Content-Type-Options: nosniff.

Corpul programului:

{
  "enabled": true,
  "recipientEmail": "reports@example.com",
  "format": "csv",
  "sendDay": 5,
  "sendTime": "08:30"
}

sendDay este între 1 și 28, iar sendTime este interpretat în UTC. Planificatorul recuperează o minută programată ratată în luna curentă de livrare. Generările eșuate înainte de predare sunt reîncercate după 5 și 10 minute, o revendicare building întreruptă poate fi recuperată după 30 de minute, iar livrarea automată se oprește după trei încercări. Planificatorul persistă indeterminate imediat înainte de predarea către SMTP; atât indeterminate, cât și starea veche sending sunt terminale, deoarece reîncercarea automată a oricăreia ar putea trimite un atașament duplicat. Operatorii trebuie să reconcilieze manual aceste rezultate înainte de a modifica starea programului. Fiecare execuție selectează cel mult zece programe, nu mai începe activități după un buget de 45 de secunde și folosește limite de timp SMTP stricte. Sarcina este dezactivată implicit și trebuie activată explicit după validarea SMTP și a capacității. Programul API este deținut de spațiul de lucru, nu folosește identitatea persoanei care a creat tokenul.

Tarife

Corpul unui tarif conține name, exact unul dintre currencyId, currencyCode sau currency, opțional biddingZoneId și tax. Corpul unei atribuiri este:

{ "tariffId": 17, "connectorId": 0 }

La crearea unei atribuiri, tariful se aplică tuturor conectorilor fizici dacă connectorId este omis sau setat explicit la 0. Actualizările de atribuire vizează o singură atribuire persistentă și necesită, prin urmare, un connectorId fizic pozitiv explicit; 0 este respins.

O componentă conține typeId, seasonId, câmpul opțional priority, câmpul obligatoriu price și limite opționale de valabilitate pentru lună, ziua săptămânii și oră.

Profiluri de încărcare

Câmpurile de metadate ale profilului sunt label, locationId, stackLevel, purposeId, kindId, opțional recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId și opțional minChargingRate. O perioadă de program conține startPeriod, limit și opțional numberOfPhases. Corpul unei atribuiri conține profileId și connectorId (implicit 0).

Ștergerea profilurilor și înlocuirea gestionării puterii pot aștepta confirmarea stației. Un refuz, o expirare sau o modificare concurentă a stării returnează un conflict și păstrează configurația bazei de date, fără a pretinde că stația a fost golită.

Utilizatori, invitații, RFID, acces și limite

Paginarea vehiculelor și paginarea utilizatorilor status=members folosesc un cursor numeric pozitiv. Paginile invitațiilor folosesc un cursor opac i2.*, iar status=all folosește un cursor compozit opac a2.* după prima pagină (un cursor numeric rămâne valid doar ca o continuare veche a fluxului de membri). Căutarea utilizatorilor este furnizată în antetul de cerere X-Admin-User-Search, astfel încât adresele de email să nu apară în URL-uri sau jurnale de acces. limit are implicit 50 și este limitat la 100; listarea utilizatorilor acceptă status=all|members|invitations. Tratează toate cursoarele returnate ca opace și returnează-le nemodificate.

Crearea directă a unui utilizator nu creează parolă, identitate de autentificare sau sesiune. Ea doar asociază un client deja înregistrat. Folosește endpointul de invitații pentru o adresă de email necunoscută. Utilizatorul de sistem Tagless protejat nu poate fi modificat prin aceste rute.

Exemple

Setează valorile în shell fără a afișa tokenul:

export ADMIN_API_BASE_URL="https://api.example.com"
export WORKSPACE_TOKEN="<read from secret manager>"

Listează locațiile:

curl --fail-with-body \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  "${ADMIN_API_BASE_URL}/v2/admin/sites"

Creează o locație în siguranță:

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"

Descarcă un raport CSV pentru un interval UTC explicit:

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"

Excluderi deliberate

API-ul tokenurilor de spațiu de lucru nu expune operațiuni care necesită o identitate umană sau o autoritate mai largă. Acestea includ:

• crearea, afișarea, rotirea sau revocarea tokenurilor folosind alt token;
• autentificare, resetarea parolei, sesiuni, delegarea rolurilor sau privilegiilor umane și schimbarea proprietarului spațiului de lucru;
• crearea/ștergerea spațiilor de lucru și apartenența la contul de facturare;
• setări de plată, înregistrarea Stripe, planuri, facturi și facturarea gazdei;
• operațiuni de asistență la nivel de gazdă și webhookuri ale furnizorilor;
• notificări pentru oameni, redirecționări de navigare, resurse de marcă și rute de dezvoltare/test.