Administratorski API radnog prostora

Administratorski API radnog prostora omogućuje integracijama između poslužitelja administriranje jednog EVCharge radnog prostora. Ova dokumentacija namijenjena je administratorima radnih prostora i vanjskim API integratorima. Upotrebljava opozive pristupne tokene vezane uz radni prostor i precizno definirane opsege pristupa; tokeni korisničke prijave i sesije preglednika ne prihvaćaju se.

Ovaj je direktorij mjerodavna referenca za razvojne programere API-ja /v2/admin koji implementira app-api. Ne dokumentira korisničke/mobilne rute ni vlastite HTTP rute administratorskog portala.

• Zahtjevi i odgovori krajnjih točaka navode svih 87 registriranih krajnjih točaka, opsege pristupa, parametre, tijela zahtjeva i tijela uspješnih odgovora.
• Sheme i primjeri definiraju višekratno upotrebljive tipove zahtjeva i odgovora te reprezentativna JSON tijela.
• Ugovor odgovora i pogrešaka definira sva zajednička tijela neuspješnih odgovora i ona specifična za krajnju točku.

Osnovni URL i granica resursa

Sve su rute relativne u odnosu na ishodište postavljene usluge app-api:

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

ID radnog prostora ne prihvaća se u URL-u, nizu upita ni tijelu zahtjeva. Svaki pristupni token vezan je uz točno jedan radni prostor, a API izvodi cpoId iz autentificiranog identiteta tokena. Ako ugniježđena lokacija, punjač, korisnik, tarifa, profil, dodjela ili transakcija ne pripada tom radnom prostoru, API vraća isti odgovor 404 RESOURCE_NOT_FOUND koji ne otkriva postojanje resursa.

Dobivanje pristupnog tokena

Administrator radnog prostora stvara tokene u Postavkama radnog prostora, u odjeljku Pristup API-ju. Upravljanje tokenima namjerno nije dostupno tokenima radnog prostora.

• Pristup API-ju uključen je u sve pakete, uključujući Free. Administrator mora imati dopuštenje za uređivanje radnog prostora.
• Pružatelj radnog prostora mora omogućiti administratorski API putem adminApiEnabled; u suprotnom valjani token dobiva odgovor 404, koji ne otkriva postojanje resursa, od app-api.
• Administrator može dodijeliti samo opsege pristupa dopuštene vlastitim trenutačnim dopuštenjima i pravima radnog prostora.
• Novi tokeni mogu biti bez roka isteka (zadano u Postavkama radnog prostora) ili imati rok trajanja u cijelim danima od 1 do 365 dana, koji odabire administrator; poslužitelj izračunava konačni apsolutni trenutak isteka. Tokeni bez roka isteka ostaju valjani dok se ne opozovu.
• Radni prostor može imati najviše 50 aktivnih tokena.
• Vjerodajnica u otvorenom tekstu prikazuje se samo jednom. Odmah je spremite u sustav za upravljanje tajnama.
• Naziv, opsezi pristupa i istek ne mogu se mijenjati. Za rotaciju stvorite zamjenski token, uvedite ga, provjerite i opozovite stari token.
• Opoziv je trenutačan; opozvani zapisi ostaju vidljivi kao nepromjenjiva povijest radnog prostora sa skrivenim osjetljivim podacima, a nema krajnje točke za provjeru Bearer tokena ni trajno brisanje.

app-api nema krajnju točku koja izdaje, osvježava, navodi ili opoziva te vjerodajnice. Dobivanje tokena zato je preduvjet koji osoba obavlja u administratorskom portalu, a ne druga krajnja točka u ovoj referenci.

Nikada nemojte stavljati token u sustav za upravljanje izvornim kodom, URL-ove, nizove upita, kolačiće, dnevnike, analitiku ili izvještaje o pogreškama.

Autentifikacija

U svakom zahtjevu pošaljite točno jedno zaglavlje u stilu RFC 6750:

Authorization: Bearer evc_ws_<selector>.<secret>

Točna neprozirna vjerodajnica sastoji se od evc_ws_, nakon čega slijede kanonski base64url selektor od 16 znakova, . i kanonska base64url tajna od 43 znaka. Pošaljite potpunu vjerodajnicu bez izmjena; nemojte je ponovno kodirati u base64.

API odbija duplicirana zaglavlja autorizacije, vrijednosti spojene zarezom, druge sheme, prazne Bearer vrijednosti, korisničke JWT-ove i vjerodajnice poslane bilo gdje osim u tom zaglavlju.

Svi neispravno oblikovani, nepoznati, istekli, opozvani ili na drugi način nevaljani tokeni dobivaju isti odgovor:

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

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

Usluga pri svakom zahtjevu provjerava status tokena i trenutačna prava radnog prostora. Uklanjanje prava zato može onemogućiti zahvaćene opsege pristupa prije isteka tokena.

Tokeni radnog prostora neprozirne su vjerodajnice, a ne JWT-ovi. Nemaju token za osvježavanje niti postoji krajnja točka za osvježavanje. Token s rokom isteka prestaje omogućivati autentifikaciju u apsolutnom trenutku expiresAt; token bez roka isteka ostaje valjan do opoziva. Rotacija znači stvaranje zamjenske vjerodajnice u portalu, uvođenje te vjerodajnice u klijent i opoziv stare.

Pravila zahtjeva

• Upotrijebite Content-Type: application/json za zahtjeve s JSON tijelom.
• Neobaveznim vrijednostima X-Request-Id u zahtjevu uklanjaju se rubni razmaci i prihvaćaju se samo ako sadrže od 1 do 128 znakova iz skupova A-Z, a-z, 0-9, ., _, : ili -; u suprotnom poslužitelj generira UUID. Svaki odgovor vraća odabranu vrijednost kao X-Request-Id.
• Neobavezni X-Error-Format: envelope pretvara svaki JSON odgovor s pogreškom u strukturiranu omotnicu dokumentiranu u odjeljku Ugovor odgovora i pogrešaka. Bilo koja druga vrijednost zadržava zadano tijelo za kompatibilnost.
• ID-jevi u parametrima putanje pozitivni su cijeli brojevi. ID-jevi pristupnih tokena koje vraća portal decimalni su tekstualni nizovi jer su u bazi podataka pohranjeni kao 64-bitne vrijednosti bez predznaka.
• Vrijednosti datuma i vremena tekstualni su nizovi u formatu RFC 3339 s izričitim vremenskim pomakom, primjerice 2026-08-13T12:30:00Z.
• Uspješna brisanja u pravilu vraćaju 204 No Content.
• Operacije stvaranja u pravilu vraćaju 201 Created.
• OCPP operacija koja je tek stavljena u red može vratiti 202 Accepted; nemojte to tumačiti kao potvrdu punjača osim ako je u odgovoru to izričito navedeno.
• Autentificirani odgovori upotrebljavaju Cache-Control: no-store. Krajnje točke za QR i izvoz izvještaja vraćaju binarna tijela s izričitim zaglavljima sadržaja.
• Dopuštena ishodišta preglednika putem CORS-a mogu čitati X-Request-Id, Idempotency-Replayed, Retry-After i Content-Disposition. To klijentima u pregledniku omogućuje povezivanje zahtjeva, otkrivanje idempotentnih ponavljanja, poštivanje vremena čekanja prije ponovnog pokušaja i zadržavanje naziva datoteka za preuzimanje koje odabere poslužitelj.

Idempotentnost

Svi administratorski zahtjevi POST, PUT, PATCH i DELETE moraju sadržavati jedno zaglavlje Idempotency-Key. Ključevi sadrže od 1 do 255 vidljivih znakova, a njihov je opseg vezan uz token, metodu i putanju.

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

Ponovna upotreba dovršenog ključa s istim URL-om i tijelom ponavlja spremljeni odgovor i dodaje:

Idempotency-Replayed: true

Ponovna upotreba ključa s drukčijim zahtjevom vraća 409 IDEMPOTENCY_CONFLICT. Zahtjev koji se još obrađuje vraća 409 IDEMPOTENT_REQUEST_PROCESSING uz Retry-After: 5.

Dovršeni odgovori i konačni ishodi čuvaju se za ponavljanje ili usklađivanje sedam dana nakon posljednjeg ažuriranja. Nakon tog razdoblja isti se ključ može smatrati novom naredbom, pa klijenti moraju upotrebljavati globalno jedinstvene ključeve i ne smiju ih namjerno ponovno koristiti.

Ako istekne vremenska rezervacija za obradu, veza se zatvori nakon početka izvršavanja ili operacija vrati pogrešku poslužitelja, API ne može pouzdano utvrditi je li došlo do vanjskog učinka. Tijekom sedmodnevnog razdoblja čuvanja ključ ostaje konačno neodređen i vraća 409 IDEMPOTENCY_OUTCOME_UNKNOWN; ne preuzima se ponovno niti se operacija automatski ponovno izvršava. Prije ručnog oporavka provjerite učinke operacije i nemojte poslati istu operaciju s novim ključem dok se to usklađivanje ne dovrši.

Sve administratorske krajnje točke koje mijenjaju podatke, uključujući POST /reports/send, zahtijevaju Idempotency-Key.

Ograničenja učestalosti zahtjeva

Ograničenja se primjenjuju i na pojedinačni token i na njegov radni prostor. Zadane vrijednosti u repozitoriju su:

Zahtjev koji je dosegnuo ograničenje vraća 429 Too Many Requests i zaglavlje Retry-After. U pojedinim implementacijama te se vrijednosti mogu nadjačati.

Pogreške

JSON pogreške upotrebljavaju stabilni code kada pozivatelj mora odabrati daljnji postupak:

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

Pogreške validacije upotrebljavaju nizove polja:

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

Uobičajeni statusi su:

Katalog opsega pristupa

Sljedeći katalog opsega pristupa upotrebljava se kada administrator stvara token. Opseg za pisanje ili radnje velikog utjecaja može podrazumijevati odgovarajući opseg za čitanje, ali opsezi za čitanje nikada ne omogućuju pisanje. Dostupni opsezi ovise o dopuštenjima administratora i uključenim značajkama radnog prostora.

Sam pristup API-ju uključen je u sve pakete i njime upravlja postavka adminApiEnabled kod pružatelja usluge. Dodatna prava na značajke navedena iznad i dalje vrijede; pristup API-ju ne omogućuje značajke izvan paketa radnog prostora.

Referentni pregled krajnjih točaka

Tablice u nastavku navode svih 87 administratorskih ruta radnog prostora. Kada je u ćeliji navedeno više opsega pristupa, svi su obavezni.

Radni prostor

Polja izmjene radnog prostora: name, email, website, addressLine1, addressLine2, postalCode, city, state i countryId. Obavezno je barem jedno polje. Prazni tekstualni nizovi koji dopuštaju null normaliziraju se na null.

Lokacije i upravljanje snagom

Tijela za stvaranje i izmjenu lokacije upotrebljavaju:

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

Geokodiranje lokacije prihvaća neobavezna polja upita street, city, state, country i dvoslovni countryCode te zaglavlje zahtjeva Accept-Language. Kombinirano pretraživanje ulice/grada/pokrajine mora sadržavati barem dva znaka. Odgovori sadrže samo placeId, displayName, latitude i longitude; vjerodajnice pružatelja usluge i njegovi specifični metapodaci ne otkrivaju se. Poslužitelj primjenjuje zajednički red pružatelja usluge s jednim zahtjevom u sekundi, rok od osam sekundi, ograničenu predmemoriju na 24 sata i globalna ograničenja učestalosti za tokene radnog prostora.

Upravljanje snagom prihvaća { "pools": [...] }. Skupina sadrži id, name, limit, neobavezni meterSources i rekurzivni children. Podređeni punjač sadrži chargepointId i priority. API ograničava veličinu stabla i broj brojila te pri zamjeni instaliranog stanja provodi dvofazno OCPP čišćenje i ponovnu provjeru. Odbijena promjena, istek vremena ili promjena zahvaćena utrkom istodobnih operacija vraća 409 POWER_MANAGEMENT_CONFLICT, a prethodna konfiguracija ostaje sačuvana.

Punjači

Parametri upita dnevnika punjača su cursor, limit (zadano 50, najviše 200), from, to, action, direction i levelId. Parametri sesija su page, limit (zadano 25, najviše 100), from, to i customerId (pozitivan ID ili unknown). Povijest objedinjenog rasporeda upotrebljava cursor, limit (zadano 20, najviše 50) i neobavezni connectorId.

Izvještaji

Filtri podataka izvještaja i izvoza su from, to, siteId, chargerId, userId, anonymous i active. Zadane vrijednosti from/to obuhvaćaju najnovije razdoblje od 90 dana i ne smiju obuhvaćati više od 90 dana. userId se ne može kombinirati s anonymous=true.

• Podjela podataka na stranice: neprozirni cursor, zadani limit=50, najviše 100.
• Mjerenja: obavezan transactionLogId, neprozirni cursor, zadano limit=500, najviše 1.000.
• Izvoz: format=csv|pdf, zadano csv, čvrsto ograničenje od 2.000 redaka.
• Odgovori izvoza upotrebljavaju Content-Disposition: attachment, Cache-Control: private, no-store i X-Content-Type-Options: nosniff.

Tijelo rasporeda:

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

sendDay je od 1 do 28, a sendTime tumači se prema UTC-u. Raspoređivač nadoknađuje propuštenu zakazanu minutu tijekom tekućeg mjeseca dostave. Neuspjele izrade prije predaje ponovno se pokušavaju nakon 5 i 10 minuta, prekinuta rezervacija zadatka building može se ponovno preuzeti nakon 30 minuta, a automatska dostava prestaje nakon tri pokušaja. Raspoređivač pohranjuje indeterminate neposredno prije predaje SMTP-u; i indeterminate i stariji status sending konačni su jer bi automatski ponovni pokušaj bilo kojeg mogao poslati dvostruki privitak. Operateri moraju ručno uskladiti te ishode prije promjene stanja rasporeda. Svaki ciklus odabire najviše deset rasporeda, prestaje započinjati nove zadatke nakon vremenskog ograničenja od 45 sekundi i upotrebljava ograničene SMTP rokove čekanja. Zadatak je zadano isključen i mora se izričito uključiti nakon provjere SMTP-a i kapaciteta. API raspored pripada radnom prostoru i ne preuzima identitet osobe koja je stvorila token.

Tarife

Tijelo tarife sadrži name, točno jedno od polja currencyId, currencyCode ili currency, neobavezni biddingZoneId i tax. Tijelo dodjele glasi:

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

Pri stvaranju dodjele tarifa se primjenjuje na sve fizičke priključke ako je connectorId izostavljen ili izričito postavljen na 0. Ažuriranja dodjele ciljaju jednu pohranjenu dodjelu i zato zahtijevaju izričito naveden pozitivni fizički connectorId; 0 se odbija.

Komponenta sadrži obavezne typeId, seasonId i price; priority i ograničenja valjanosti po mjesecu, danu u tjednu i satu nisu obavezni.

Profili punjenja

Polja metapodataka profila su label, locationId, stackLevel, purposeId, kindId, neobavezni recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId i neobavezni minChargingRate. Razdoblje rasporeda sadrži startPeriod, limit i neobavezni numberOfPhases. Tijelo dodjele sadrži profileId i connectorId (zadano 0).

Brisanje profila i zamjena upravljanja snagom mogu čekati potvrdu punjača. Odbijanje, istek vremena ili istodobna promjena stanja vraćaju sukob i zadržavaju konfiguraciju baze podataka umjesto da lažno prikažu da je punjač očišćen.

Korisnici, pozivnice, RFID, pristup i ograničenja

Straničenje vozila i straničenje korisnika status=members upotrebljavaju pozitivan brojčani cursor. Stranice pozivnica upotrebljavaju neprozirni pokazivač i2.*, dok status=all nakon prve stranice upotrebljava neprozirni objedinjeni pokazivač a2.* (brojčani pokazivač ostaje valjan samo kao nastavak starijeg toka članova). Pretraživanje korisnika šalje se u zaglavlju zahtjeva X-Admin-User-Search kako se adrese e-pošte ne bi stavljale u URL-ove ili dnevnike pristupa. limit zadano iznosi 50, a ograničen je na 100; popis korisnika podržava status=all|members|invitations. Sve vraćene pokazivače smatrajte neprozirnima i vraćajte ih nepromijenjene.

Izravno stvaranje korisnika ne stvara lozinku, identitet za prijavu ni sesiju. Time se samo povezuje već registrirani korisnik. Za nepoznatu adresu e-pošte upotrijebite krajnju točku za pozivnice. Zaštićeni sistemski korisnik Tagless ne može se mijenjati putem ovih ruta.

Primjeri

Postavite vrijednosti u svojoj ljusci bez ispisivanja tokena:

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

Dohvatite popis lokacija:

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

Sigurno stvorite lokaciju:

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"

Preuzmite CSV izvještaj za izričito naveden UTC raspon:

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"

Namjerno izostavljene mogućnosti

API tokena radnog prostora ne izlaže operacije koje zahtijevaju ljudski identitet ili šire ovlasti. One uključuju:

• stvaranje, otkrivanje, rotaciju ili opoziv tokena pomoću drugog tokena;
• prijavu, ponovno postavljanje lozinke, sesije, delegiranje ljudskih uloga ili ovlasti te promjene vlasništva radnog prostora;
• stvaranje/brisanje radnog prostora i članstvo u računu za naplatu;
• postavke plaćanja, uključivanje u Stripe, pakete, račune i naplatu pružatelja usluge;
• operacije podrške za cijelog pružatelja usluge i webhookove pružatelja;
• obavijesti osobama, navigacijska preusmjeravanja, resurse brenda te razvojne i testne rute.