Tööruumi Admin API

Tööruumi Admin API võimaldab serveritevahelistel integratsioonidel hallata üht EVCharge’i tööruumi. Dokumentatsioon on tööruumihalduritele ja välistele API integraatoritele. Kasutatakse tühistatavaid tööruumiga seotud pääsutõendeid ja täpseid pääsuulatusi; kliendi sisselogimistõendeid ega brauseriseansse ei aktsepteerita.

See kataloog on app-api teostatud /v2/admin API kanooniline arendajaviide. See ei dokumenteeri kliendi-/mobiilimarsruute ega haldusportaali enda HTTP marsruute.

• Endpointide päringud ja vastused loetleb kõik 87 registreeritud endpointi, pääsuulatused, parameetrid, päringusisud ja edukad vastusesisud.
• Skeemid ja näited määrab korduvkasutatavad päringu/vastuse tüübid ja esinduslikud JSON-sisud.
• Vastuste ja vigade leping määrab iga ühise ja endpointipõhise ebaeduka sisu.

Baas-URL ja ressursipiir

Kõik marsruudid on suhtelised juurutatud app-api päritolu suhtes:

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

Tööruumi ID-d ei aktsepteerita URL-is, päringustringis ega päringu sisus. Iga pääsutõend on seotud täpselt ühe tööruumiga ning API tuletab cpoId autenditud tõendi identiteedist. Kui pesastatud asukoht, laadija, kasutaja, tariif, profiil, määrang või tehing ei kuulu sellesse tööruumi, tagastab API sama olemasolu mitteavalduva 404 RESOURCE_NOT_FOUND vastuse.

Pääsutõendi hankimine

Tööruumi haldur loob pääsutõendid tööruumi seadete API juurdepääsu jaotises. Pääsutõendite haldamist ei ole tahtlikult tööruumi pääsutõenditele avatud.

• API juurdepääs sisaldub igas paketis, ka paketis Free. Halduril peab olema tööruumi muutmise õigus.
• Tööruumi host peab lubama Admin API adminApiEnabled kaudu; muidu saab kehtiv tõend app-api kaudu olemasolu mitteavalduva 404.
• Haldur saab anda ainult tema praeguste õiguste ja tööruumi õigustega lubatud pääsuulatusi.
• Uued pääsutõendid võivad olla aegumatud (tööruumi seadete vaikevalik) või halduri määratud 1–365 täispäevase elueaga; server arvutab lõpliku absoluutse aegumise. Aegumatud tõendid kehtivad tühistamiseni.
• Tööruumil võib olla kuni 50 aktiivset pääsutõendit.
• Lihttekstiline autentimisandmestik kuvatakse ühe korra. Salvestage see kohe saladuste haldurisse.
• Nimi, pääsuulatused ja aegumine on muutumatud. Vahetamiseks looge asendus, juurutage ja kontrollige seda ning tühistage vana pääsutõend.
• Tühistamine on kohene; tühistatud read jäävad nähtavaks muutumatu, tundlikke andmeid varjava tööruumiajaloona. Bearer-pääsutõendi kontrollimiseks ega jäädavaks kustutamiseks endpointi pole.

app-api ei sisalda endpointi nende autentimisandmete väljastamiseks, uuendamiseks, loetlemiseks ega tühistamiseks. Pääsutõendi hankimine on seega inimese haldusportaalis täidetav eeltingimus, mitte muu selle viite endpoint.

Ärge kunagi pange pääsutõendit lähtekoodihaldusse, URL-idesse, päringustringidesse, küpsistesse, logidesse, analüütikasse ega veaaruannetesse.

Autentimine

Saatke iga päringuga täpselt üks RFC 6750 stiilis päis:

Authorization: Bearer evc_ws_<selector>.<secret>

Täpne läbipaistmatu autentimisandmestik on evc_ws_, millele järgnevad 16-märgiline kanooniline base64url-valija, . ja 43-märgiline kanooniline base64url-saladus. Saatke kogu autentimisandmestik muutmata; ärge kodeerige seda uuesti base64-ga.

API lükkab tagasi korduvad autoriseerimispäised, komaga ühendatud väärtused, muud skeemid, tühjad bearer-väärtused, kliendi JWT-d ning mujale kui sellesse päisesse antud autentimisandmed.

Vigase vorminguga, tundmatud, aegunud, tühistatud või muul viisil vigased pääsutõendid saavad sama vastuse:

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

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

Teenus kontrollib igal päringul pääsutõendi olekut ja tööruumi praegusi õigusi. Õiguse eemaldamine võib seetõttu keelata seotud ulatused enne pääsutõendi aegumist.

Tööruumi pääsutõendid on läbipaistmatud autentimisandmed, mitte JWT-d. Neil pole värskendustõendit ega värskendusendpointi. Tähtajaline tõend lõpetab autentimise absoluutsel expiresAt; aegumatu kehtib tühistamiseni. Vahetamine tähendab portaalis asenduse loomist, kliendile juurutamist ja vana tõendi tühistamist.

Päringukokkulepped

• JSON-sisuga päringute jaoks kasutage Content-Type: application/json.
• Valikuliste X-Request-Id päringuväärtuste ääretühikud eemaldatakse ja väärtused aktsepteeritakse ainult siis, kui need sisaldavad 1–128 märki hulgast A-Z, a-z, 0-9, ., _, : või -; muidu loob server UUID. Iga vastus tagastab valitud väärtuse kui X-Request-Id.
• Valikuline X-Error-Format: envelope teisendab iga JSON-veavastuse jaotises Vastuste ja vigade leping kirjeldatud struktureeritud ümbriseks. Muu väärtus säilitab vaikimisi ühilduvussisu.
• Teeparameetrite ID-d on positiivsed täisarvud. Portaali tagastatud pääsutõendite ID-d on kümnendstringid, sest need on andmebaasis märgita 64-bitised väärtused.
• Kuupäeva-kellaaja väärtused on RFC 3339 stringid koos selge nihkega, näiteks 2026-08-13T12:30:00Z.
• Edukad kustutamised tagastavad tavaliselt 204 No Content.
• Loomistoimingud tagastavad tavaliselt 201 Created.
• Ainult järjekorda pandud OCPP töö võib tagastada 202 Accepted; ärge pidage seda laadija kinnituseks, kui vastus seda selgelt ei ütle.
• Autenditud vastused kasutavad Cache-Control: no-store. QR-i ja aruandeekspordi endpointid tagastavad kahendsisu koos selgesõnaliste sisupäistega.
• Lubatud brauseripäritolud saavad CORS-i kaudu lugeda X-Request-Id, Idempotency-Replayed, Retry-After ja Content-Disposition. See võimaldab päringuid seostada, tuvastada idempotentseid kordusi, järgida korduskatse aega ja säilitada serveri valitud allalaadimisfailide nimesid.

Idempotentsus

Kõik halduse POST, PUT, PATCH ja DELETE päringud peavad sisaldama üht Idempotency-Key päist. Võtmed sisaldavad 1–255 nähtavat märki ning on piiratud pääsutõendi, meetodi ja teega.

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

Lõpetatud võtme korduv kasutus sama URL-i ja sisuga kordab salvestatud vastust ning lisab:

Idempotency-Replayed: true

Võtme korduskasutus teise päringuga tagastab 409 IDEMPOTENCY_CONFLICT. Veel töödeldav päring tagastab 409 IDEMPOTENT_REQUEST_PROCESSING koos Retry-After: 5.

Lõpetatud vastuseid ja lõpptulemusi säilitatakse korduseks või kooskõlastuseks seitse päeva viimasest uuendusest. Pärast säilitusaega võib sama võtit käsitleda uue käsuna, seega peavad kliendid kasutama globaalselt unikaalseid võtmeid ega tohi neid tahtlikult taaskasutada.

Kui töötlusliising aegub, ühendus suletakse pärast täitmise algust või toiming tagastab serverivea, ei saa API ohutult tõestada, kas väline mõju tekkis. Seitsmepäevase säilitusaja jooksul on võtme tulemus lõplikult määramatu ja tagastab 409 IDEMPOTENCY_OUTCOME_UNKNOWN; seda ei võeta uuesti üle ega täideta automaatselt. Kontrollige toimingu mõju enne käsitsi taastamist ning ärge saatke sama toimingut uue võtmega enne kooskõlastuse lõppu.

Kõik muutvad haldusendpointid, sealhulgas POST /reports/send, nõuavad Idempotency-Key.

Päringupiirangud

Piirangud kehtivad nii üksikule pääsutõendile kui ka selle tööruumile. Repositooriumi vaikeväärtused on:

Piiratud päring tagastab 429 Too Many Requests ja päise Retry-After. Juurutustes võib need väärtused üle määrata.

Vead

JSON-vead kasutavad stabiilset code, kui klient vajab harunemist:

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

Valideerimisvead kasutavad väljamassiive:

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

Levinud olekud on:

Pääsuulatuste kataloog

Järgmist pääsuulatuste kataloogi kasutatakse halduri pääsutõendi loomisel. Kirjutamise või suure mõjuga ulatus võib hõlmata vastavat lugemisulatust, kuid lugemisulatus ei anna kunagi kirjutamisõigust. Saadaolevad ulatused sõltuvad halduri õigustest ja tööruumi lubatud funktsioonidest.

API juurdepääs ise sisaldub igas paketis ja seda juhib hosti adminApiEnabled seade. Ülaltoodud lisafunktsioonide õigused kehtivad endiselt; API juurdepääs ei anna tööruumi paketist välja jäävaid funktsioone.

Endpointide viide

Allolevad tabelid loetlevad kõik 87 tööruumihalduse marsruuti. Ühes lahtris olevad mitu pääsuulatust on kõik kohustuslikud.

Tööruum

Tööruumi osalise muutmise väljad: name, email, website, addressLine1, addressLine2, postalCode, city, state ja countryId. Vähemalt üks väli on kohustuslik. Tühjad nulli lubavad stringid normaliseeritakse väärtuseks null.

Asukohad ja võimsushaldus

Asukoha loomise ja osalise muutmise sisud kasutavad:

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

Asukoha geokodeerimine võtab valikulised street, city, state, country ja kahetähelise countryCode päringuvälja ning Accept-Language päise. Tänava/linna/osariigi otsing peab kokku sisaldama vähemalt kaht märki. Vastused sisaldavad ainult placeId, displayName, latitude ja longitude; teenusepakkuja autentimisandmeid ega erimetaandmeid ei avaldata. Server rakendab teenusepakkuja ühist ühe päringu sekundis järjekorda, kaheksasekundilist ajalõppu, piiratud 24 tunni vahemälu ning globaalseid tööruumi pääsutõendi päringupiiranguid.

Võimsushaldus aktsepteerib { "pools": [...] }. Rühmal on id, name, limit, valikuline meterSources ja rekursiivsed children. Alamlaadijal on chargepointId ja priority. API piirab puu ja arvestite arvu ning teeb paigaldatud oleku asendamisel kaheetapilise OCPP tühjendamise/kordusvalideerimise. Tagasilükatud, aegunud või võidujooksuga muutus tagastab 409 POWER_MANAGEMENT_CONFLICT, säilitades eelmise seadistuse.

Laadijad

Laadija logide päringuparameetrid on cursor, limit (vaikimisi 50, maksimaalselt 200), from, to, action, direction ja levelId. Seansiparameetrid on page, limit (vaikimisi 25, maksimaalselt 100), from, to ja customerId (positiivne ID või unknown). Koondajakava ajalugu kasutab cursor, limit (vaikimisi 20, maksimaalselt 50) ja valikulist connectorId.

Aruanded

Aruandeandmete ja ekspordi filtrid on from, to, siteId, chargerId, userId, anonymous ja active. from/to kasutavad vaikimisi viimast 90 päeva ega tohi ületada 90 päeva. userId ei saa kombineerida väärtusega anonymous=true.

• Andmete lehekülgedeks jaotamine: läbipaistmatu cursor, vaikimisi limit=50, maksimaalselt 100.
• Mõõtmised: kohustuslik transactionLogId, läbipaistmatu cursor, vaikimisi limit=500, maksimaalselt 1000.
• Eksport: format=csv|pdf, vaikimisi csv, range piir 2000 rida.
• Ekspordivastused kasutavad Content-Disposition: attachment, Cache-Control: private, no-store ja X-Content-Type-Options: nosniff.

Ajakava sisu:

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

sendDay on 1–28 ja sendTime tõlgendatakse UTC-s. Ajastaja teeb vahele jäänud ajastatud minuti tasa jooksva tarnekuu jooksul. Enne üleandmist nurjunud koosted kordavad 5 ja 10 minuti pärast, katkenud building hõive on 30 minuti järel uuesti ülevõetav ja automaatne saatmine peatub pärast kolme katset. Ajastaja salvestab indeterminate vahetult enne SMTP üleandmist; nii indeterminate kui vana sending olek on lõplikud, sest automaatne kordamine võib saata topeltmanuse. Operaatorid peavad tulemused käsitsi kooskõlastama enne ajakava oleku muutmist. Iga tsükkel valib kuni kümme ajakava, lõpetab uute tööde alustamise pärast 45-sekundilist ajavaru ning kasutab piiratud SMTP ajalõppe. Töö on vaikimisi keelatud ja tuleb pärast SMTP ning mahu valideerimist selgesõnaliselt lubada. API ajakava kuulub tööruumile, mitte ei kasuta pääsutõendi loonud inimese identiteeti.

Tariifid

Tariifi sisu sisaldab name, täpselt üht väärtust currencyId, currencyCode või currency, valikulist biddingZoneId ja tax. Määramise sisu on:

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

Määrangu loomisel rakendatakse tariifi kõigile füüsilistele pistikutele, kui connectorId jäetakse välja või määratakse selgesõnaliselt väärtuseks 0. Määrangu uuendused sihivad üht salvestatud määrangut ja nõuavad seetõttu selgesõnalist positiivset füüsilist connectorId; 0 lükatakse tagasi.

Komponent sisaldab typeId, seasonId, price, valikulist priority ning valikulisi kehtivuspiire kuu, nädalapäeva ja tunni järgi.

Laadimisprofiilid

Profiili metaandmeväljad on label, locationId, stackLevel, purposeId, kindId, valikulised recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId ja valikuline minChargingRate. Ajakava periood sisaldab startPeriod, limit ja valikulist numberOfPhases. Määrangu sisu sisaldab profileId ja connectorId (vaikimisi 0).

Profiili kustutamine ja võimsushalduse asendamine võivad oodata laadija kinnitust. Keeldumine, ajalõpp või samaaegne olekumuutus tagastab konflikti ja säilitab andmebaasi seadistuse, selle asemel et väita laadija tühjendamist.

Kasutajad, kutsed, RFID, juurdepääs ja piirangud

Sõidukite ja status=members kasutajate lehekülgedeks jaotamine kasutab positiivset arvulist cursor. Kutsete lehed kasutavad läbipaistmatut i2.* kursorit, samas status=all kasutab pärast esimest lehte läbipaistmatut a2.* liitkursorit (arvuline kursor kehtib ainult vana liikmevoo jätkuna). Kasutajaotsing antakse X-Admin-User-Search päises, et e-posti aadressid ei satuks URL-idesse ega juurdepääsulogidesse. limit on vaikimisi 50 ja maksimaalselt 100; kasutajaloend toetab status=all|members|invitations. Käsitlege kõiki tagastatud kursoreid läbipaistmatutena ja tagastage need muutmata.

Otsene kasutaja loomine ei loo parooli, sisselogimisidentiteeti ega seanssi. See seob vaid juba registreeritud kliendi. Tundmatu e-posti korral kasutage kutseendpointi. Kaitstud Taglessi süsteemikasutajat ei saa nende marsruutidega muuta.

Näited

Määrake väärtused käsukestas ilma pääsutõendit väljastamata:

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

Asukohtade loend:

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

Looge asukoht ohutult:

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"

Laadige alla CSV-aruanne selgesõnalise UTC-vahemiku kohta:

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"

Teadlikud välistused

Tööruumi pääsutõendi API ei avalda toiminguid, mis vajavad inimese identiteeti või laiemaid volitusi. Need hõlmavad:

• pääsutõendite loomine, avaldamine, vahetamine või tühistamine teise pääsutõendiga;
• sisselogimine, parooli lähtestamine, seansid, inimrollide või õiguste delegeerimine ja tööruumi omandi muutmine;
• tööruumi loomine/kustutamine ja arvelduskonto liikmelisus;
• makseseaded, Stripe’i kasutuselevõtt, paketid, arved ja hosti arveldus;
• hostiülesed tugitoimingud ja teenusepakkujate veebikonksud;
• inimeste teavitused, navigeerimise ümbersuunamised, brändifailid ja arendus-/testimarsruudid.