Admin API delovnega prostora

Admin API delovnega prostora omogoča integracijam med strežniki upravljanje enega delovnega prostora EVCharge. Ta dokumentacija je za skrbnike delovnega prostora in zunanje integratorje API. Uporablja preklicljive žetone dostopa, vezane na delovni prostor, in podrobne obsege; prijavni žetoni strank in seje brskalnika niso sprejeti.

Ta imenik je kanonična razvijalska referenca API /v2/admin, ki ga izvaja app-api. Ne dokumentira poti strank/mobilnih naprav ali lastnih poti HTTP skrbniškega portala.

• Zahteve in odgovori končnih točk navaja vseh 87 registriranih končnih točk, obsege, parametre, telesa zahtev in uspešna telesa.
• Sheme in primeri določa ponovno uporabne tipe zahtev/odgovorov in značilne vsebine JSON.
• Pogodba odgovorov in napak določa vsako skupno in posebno neuspešno telo.

Osnovni URL in meja virov

Vse poti so relativne glede na nameščeni izvor app-api:

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

ID delovnega prostora ni sprejet v URL-ju, poizvedbenem nizu ali telesu zahteve. Vsak žeton dostopa je vezan na natanko en delovni prostor, API pa določi cpoId iz overjene identitete žetona. Če gnezdena lokacija, polnilnica, uporabnik, tarifa, profil, dodelitev ali transakcija ne pripada temu prostoru, API vrne isti odgovor 404 RESOURCE_NOT_FOUND, ki ne razkriva obstoja virov.

Pridobitev žetona za dostop

Skrbnik delovnega prostora ustvari žetone v nastavitvah delovnega prostora pod Dostop API. Upravljanje žetonov namenoma ni na voljo žetonom delovnega prostora.

• Dostop API je vključen v vsak paket, tudi Free. Skrbnik mora imeti dovoljenje za urejanje delovnega prostora.
• Gostitelj delovnega prostora mora omogočiti Admin API prek adminApiEnabled; sicer veljaven žeton prejme nerazkrivajoči 404 iz app-api.
• Skrbnik lahko dodeli samo obsege, ki jih dovoljujejo njegova trenutna dovoljenja in pravice delovnega prostora.
• Novi žetoni so lahko brez poteka (privzeto v nastavitvah delovnega prostora) ali z življenjsko dobo od 1 do 365 celih dni, ki jo izbere skrbnik; strežnik izračuna končne absolutne roke. Žetoni brez poteka ostanejo veljavni do preklica.
• Delovni prostor ima lahko največ 50 aktivnih žetonov.
• Poverilnica v navadnem besedilu se prikaže enkrat. Takoj jo shranite v upravljalnik skrivnosti.
• Ime, obsegi in potek so nespremenljivi. Za rotacijo ustvarite zamenjavo, jo namestite, preverite in prekličite stari žeton.
• Preklic velja takoj; preklicane vrstice ostanejo vidne kot nespremenljiva, zakrita zgodovina delovnega prostora, končne točke za introspekcijo žetona bearer ali trajni izbris pa ni.

app-api nima končne točke, ki izdaja, osvežuje, našteva ali preklicuje te poverilnice. Pridobitev žetona je zato predpogoj, izveden prek človeškega skrbniškega portala, in ne druga končna točka te reference.

Žetona nikoli ne shranjujte v nadzor različic, URL-je, poizvedbene nize, piškotke, dnevnike, analitiko ali poročila napak.

Overjanje

Pri vsaki zahtevi pošljite natanko eno glavo v slogu RFC 6750:

Authorization: Bearer evc_ws_<selector>.<secret>

Natančna neprosojna poverilnica je evc_ws_, ki ji sledijo 16-znakovni kanonični izbirnik base64url, . in 43-znakovna kanonična skrivnost base64url. Celotno poverilnico pošljite nespremenjeno; ne kodirajte je ponovno z base64.

API zavrne podvojene glave pooblastil, z vejico združene vrednosti, druge sheme, prazne vrednosti bearer, JWT-je strank in poverilnice, poslane kjer koli drugje kot v tej glavi.

Nepravilno oblikovani, neznani, potekli, preklicani ali drugače neveljavni žetoni prejmejo isti odgovor:

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

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

Storitev ob vsaki zahtevi preveri stanje žetona in trenutne pravice delovnega prostora. Odstranitev pravice lahko zato onemogoči prizadete obsege pred potekom žetona.

Žetoni delovnega prostora so neprosojne poverilnice, ne JWT-ji. Nimajo osvežitvenega žetona in končne točke za osvežitev ni. Časovno omejen žeton preneha overjati ob svojem absolutnem expiresAt; žeton brez poteka velja do preklica. Rotacija pomeni ustvariti nadomestno poverilnico v portalu, jo namestiti odjemalcu in preklicati staro.

Pravila zahtev

• Za zahteve s telesom JSON uporabite Content-Type: application/json.
• Neobvezne vrednosti zahteve X-Request-Id se obrežejo in sprejmejo samo, če vsebujejo 1–128 znakov iz A-Z, a-z, 0-9, ., _, : ali -; sicer strežnik ustvari UUID. Vsak odgovor vrne izbrano vrednost kot X-Request-Id.
• Neobvezni X-Error-Format: envelope pretvori vsak odgovor napake JSON v strukturirano ovojnico, opisano v Pogodbi odgovorov in napak. Vsaka druga vrednost ohrani privzeto združljivo telo.
• ID-ji v parametrih poti so pozitivna cela števila. ID-ji žetonov dostopa, ki jih vrne portal, so desetiški nizi, saj so v zbirki podatkov 64-bitne nepodpisane vrednosti.
• Datumi in časi so nizi RFC 3339 z izrecnim odmikom, na primer 2026-08-13T12:30:00Z.
• Uspešni izbrisi običajno vrnejo 204 No Content.
• Operacije ustvarjanja običajno vrnejo 201 Created.
• Opravilo OCPP, ki je bilo samo uvrščeno v čakalno vrsto, lahko vrne 202 Accepted; tega ne razumite kot potrditev polnilnice, razen če odgovor to izrecno navaja.
• Overjeni odgovori uporabljajo Cache-Control: no-store. Končne točke za QR in izvoz poročil vrnejo binarna telesa z izrecnimi glavami vsebine.
• Dovoljeni izvori brskalnika lahko prek CORS berejo X-Request-Id, Idempotency-Replayed, Retry-After in Content-Disposition. To odjemalcem omogoča povezovanje zahtev, zaznavanje idempotentnih ponovitev, upoštevanje časa ponovnega poskusa in ohranjanje imen datotek, ki jih izbere strežnik.

Idempotentnost

Vse skrbniške zahteve POST, PUT, PATCH in DELETE morajo vsebovati eno glavo Idempotency-Key. Ključi vsebujejo 1–255 vidnih znakov in so omejeni na žeton, metodo in pot.

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

Ponovna uporaba dokončanega ključa z istima URL in telesom ponovi shranjeni odgovor in doda:

Idempotency-Replayed: true

Ponovna uporaba ključa z drugo zahtevo vrne 409 IDEMPOTENCY_CONFLICT. Zahteva, ki se še obdeluje, vrne 409 IDEMPOTENT_REQUEST_PROCESSING z Retry-After: 5.

Dokončani odgovori in končni izidi se hranijo za ponavljanje ali uskladitev sedem dni po zadnji posodobitvi. Po tem obdobju je lahko isti ključ obravnavan kot nov ukaz, zato morajo odjemalci uporabljati globalno enolične ključe in jih ne smejo namenoma ponovno uporabljati.

Če najem obdelave poteče, se povezava po začetku izvajanja zapre ali operacija vrne strežniško napako, API ne more varno dokazati, ali je nastal zunanji učinek. V sedemdnevnem obdobju hrambe je ključ dokončno nedoločen in vrne 409 IDEMPOTENCY_OUTCOME_UNKNOWN; ne prevzame se znova in se ne izvede samodejno ponovno. Pred ročnim obnovitvenim ukrepom preverite učinke operacije in iste operacije ne pošljite z novim ključem, dokler uskladitev ni končana.

Vse skrbniške končne točke za spremembe, vključno z POST /reports/send, zahtevajo Idempotency-Key.

Omejitve zahtev

Omejitve veljajo tako za posamezen žeton kot za njegov delovni prostor. Privzete vrednosti v repozitoriju so:

Omejena zahteva vrne 429 Too Many Requests in glavo Retry-After. Namestitve lahko te vrednosti preglasijo.

Napake

Napake JSON uporabljajo stabilni code, kadar mora klicatelj razvejiti obdelavo:

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

Napake preverjanja uporabljajo sezname polj:

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

Pogosta stanja so:

Katalog obsegov

Naslednji katalog obsegov se uporablja, ko skrbnik ustvari žeton. Pisalni ali zelo vpliven obseg lahko vključuje ustrezni bralni obseg, bralni obsegi pa nikoli ne dovolijo zapisovanja. Razpoložljivi obsegi so odvisni od skrbnikovih dovoljenj in omogočenih funkcij delovnega prostora.

Sam dostop API je vključen v vsak paket in ga nadzoruje nastavitev adminApiEnabled gostitelja. Zgornje dodatne pravice do funkcij še vedno veljajo; dostop API ne omogoča funkcij zunaj paketa delovnega prostora.

Referenca končnih točk

Spodnje tabele navajajo vseh 87 skrbniških poti delovnega prostora. Če je v celici več obsegov, so zahtevani vsi.

Delovni prostor

Polja delne posodobitve delovnega prostora: name, email, website, addressLine1, addressLine2, postalCode, city, state in countryId. Obvezno je vsaj eno polje. Prazni nizi, ki dovoljujejo null, se normalizirajo v null.

Lokacije in upravljanje moči

Telesa ustvarjanja in delne posodobitve lokacije uporabljajo:

{
  "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 sprejme neobvezna polja poizvedbe street, city, state, country in dvočrkovni countryCode ter glavo zahteve Accept-Language. Skupno iskanje ulice/mesta/zvezne države mora vsebovati vsaj dva znaka. Odgovori vsebujejo samo placeId, displayName, latitude in longitude; poverilnice ponudnika in njegovi posebni metapodatki niso razkriti. Strežnik uporablja skupno vrsto ponudnika z eno zahtevo na sekundo, osemsekundno časovno omejitev, omejen 24-urni predpomnilnik in globalne omejitve zahtev žetonov delovnega prostora.

Upravljanje moči sprejme { "pools": [...] }. Skupina ima id, name, limit, neobvezni meterSources in rekurzivne children. Podrejena polnilnica ima chargepointId in priority. API omejuje drevo in število števcev ter ob zamenjavi nameščenega stanja izvede dvofazno čiščenje OCPP/ponovno preverjanje. Zavrnjena, pretečena ali s sočasno spremembo prehitena sprememba vrne 409 POWER_MANAGEMENT_CONFLICT in ohrani prejšnjo konfiguracijo.

Polnilnice

Parametri poizvedbe dnevnikov polnilnice so cursor, limit (privzeto 50, največ 200), from, to, action, direction in levelId. Parametri sej so page, limit (privzeto 25, največ 100), from, to in customerId (pozitiven ID ali unknown). Zgodovina sestavljenega urnika uporablja cursor, limit (privzeto 20, največ 50) in neobvezni connectorId.

Poročila

Filtri podatkov in izvoza poročil so from, to, siteId, chargerId, userId, anonymous in active. from/to privzeto zajemata zadnjih 90 dni in ne smeta preseči 90 dni. userId ni mogoče združiti z anonymous=true.

• Straničenje podatkov: neprosojni cursor, privzeto limit=50, največ 100.
• Meritve: obvezni transactionLogId, neprosojni cursor, privzeto limit=500, največ 1.000.
• Izvoz: format=csv|pdf, privzeto csv, trda omejitev 2.000 vrstic.
• Odgovori izvoza uporabljajo Content-Disposition: attachment, Cache-Control: private, no-store in X-Content-Type-Options: nosniff.

Telo urnika:

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

sendDay je 1–28 in sendTime se razlaga v UTC. Razporejevalnik nadoknadi zamujeno načrtovano minuto v trenutnem mesecu dostave. Neuspele priprave pred predajo se ponovijo po 5 in 10 minutah, prekinjeno rezervacijo building je mogoče znova prevzeti po 30 minutah, samodejna dostava pa se ustavi po treh poskusih. Razporejevalnik shrani indeterminate tik pred predajo SMTP; tako indeterminate kot starejše stanje sending sta končna, saj bi samodejna ponovitev lahko poslala podvojeno prilogo. Upravljavci morajo te izide ročno uskladiti pred spremembo stanja urnika. Vsak cikel izbere največ deset urnikov, po 45-sekundnem proračunu preneha začenjati delo in uporablja omejene časovne omejitve SMTP. Opravilo je privzeto onemogočeno in ga je treba izrecno omogočiti po preverjanju SMTP in zmogljivosti. Urnik API je v lasti delovnega prostora in ne uporablja identitete človeka, ki je ustvaril žeton.

Tarife

Telo tarife vsebuje name, natanko eno od currencyId, currencyCode ali currency, neobvezni biddingZoneId in tax. Telo dodelitve je:

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

Pri ustvarjanju dodelitve se tarifa uporabi za vse fizične priključke, če je connectorId izpuščen ali izrecno nastavljen na 0. Posodobitev dodelitve cilja eno shranjeno dodelitev in zato zahteva izrecni pozitivni fizični connectorId; 0 je zavrnjen.

Komponenta vsebuje typeId, seasonId, price, neobvezni priority in neobvezne meje veljavnosti po mesecu, dnevu v tednu in uri.

Profili polnjenja

Polja metapodatkov profila so label, locationId, stackLevel, purposeId, kindId, neobvezni recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId in neobvezni minChargingRate. Obdobje urnika vsebuje startPeriod, limit in neobvezni numberOfPhases. Telo dodelitve vsebuje profileId in connectorId (privzeto 0).

Izbrisi profilov in zamenjava upravljanja moči lahko čakajo na potrditev polnilnice. Zavrnitev, časovna omejitev ali sočasna sprememba stanja vrne spor in ohrani konfiguracijo zbirke podatkov, namesto da bi se pretvarjalo, da je bila polnilnica počiščena.

Uporabniki, povabila, RFID, dostop in omejitve

Straničenje vozil in uporabnikov status=members uporablja pozitivni številčni cursor. Strani povabil uporabljajo neprosojni kazalec i2.*, medtem ko status=all po prvi strani uporablja neprosojni sestavljeni kazalec a2.* (številčni kazalec ostane veljaven samo za nadaljevanje starega toka članov). Iskanje uporabnikov se pošlje v glavi zahteve X-Admin-User-Search, da e-poštni naslovi ne pridejo v URL-je ali dnevnike dostopa. limit je privzeto 50 in omejeno na 100; seznam uporabnikov podpira status=all|members|invitations. Vse vrnjene kazalce obravnavajte kot neprosojne in jih vrnite nespremenjene.

Neposredno ustvarjanje uporabnika ne ustvari gesla, prijavne identitete ali seje. Samo pripne že registrirano stranko. Za neznan e-poštni naslov uporabite končno točko povabila. Zaščitenega sistemskega uporabnika Tagless prek teh poti ni mogoče spreminjati.

Primeri

V lupini nastavite vrednosti, ne da bi izpisali žeton:

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

Seznam lokacij:

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

Varno ustvarite lokacijo:

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"

Prenesite poročilo CSV za izrecno obdobje 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"

Namerne izključitve

API žetonov delovnega prostora ne razkriva operacij, ki zahtevajo človeško identiteto ali širša pooblastila. Te vključujejo:

• ustvarjanje, razkrivanje, rotacija ali preklic žetonov z drugim žetonom;
• prijava, ponastavitev gesla, seje, delegiranje človeških vlog ali pravic ter spremembe lastništva delovnega prostora;
• ustvarjanje/izbris delovnega prostora in članstvo v obračunskem računu;
• nastavitve plačil, vključitev Stripe, paketi, računi in obračunavanje gostitelja;
• podporne operacije na ravni gostitelja in spletni kavlji ponudnikov;
• obvestila ljudem, preusmeritve navigacije, sredstva znamke in razvojne/testne poti.