Työtilan Admin API

Työtilan Admin API antaa palvelinten välisille integraatioille mahdollisuuden hallita yhtä EVCharge-työtilaa. Dokumentaatio on tarkoitettu työtilan ylläpitäjille ja ulkoisille API-integraattoreille. API käyttää peruttavia työtilaan sidottuja käyttötunnuksia ja tarkkarajaisia käyttöalueita; asiakkaiden kirjautumistunnuksia ja selainistuntoja ei hyväksytä.

Tämä hakemisto on toteutuksen app-api tarjoaman /v2/admin-API:n ensisijainen kehittäjäviite. Se ei dokumentoi asiakas-/mobiilireittejä eikä ylläpitoportaalin omia HTTP-reittejä.

• Endpoint-pyynnöt ja -vastaukset luettelee kaikki 87 rekisteröityä endpointia, käyttöalueet, parametrit, pyyntörungot ja onnistumisrungot.
• Skeemat ja esimerkit määrittää uudelleenkäytettävät pyyntö-/vastaustyypit ja edustavat JSON-sisällöt.
• Vastaus- ja virhesopimus määrittää jokaisen yhteisen ja endpoint-kohtaisen epäonnistumisrungon.

Perus-URL ja resurssiraja

Kaikki reitit ovat suhteessa käyttöönotettuun app-api-alkuperään:

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

Työtilan tunnistetta ei hyväksytä URL-osoitteessa, kyselymerkkijonossa tai pyynnön rungossa. Kukin käyttötunnus on sidottu täsmälleen yhteen työtilaan ja API johtaa cpoId-arvon todennetusta tunnuksen identiteetistä. Jos sisäkkäinen kohde, laturi, käyttäjä, tariffi, profiili, määritys tai tapahtuma ei kuulu kyseiseen työtilaan, API palauttaa saman 404 RESOURCE_NOT_FOUND-vastauksen, joka ei paljasta resurssin olemassaoloa.

Käyttötunnuksen hankkiminen

Työtilan ylläpitäjä luo tunnukset työtilan asetusten API-käyttöosiossa. Tunnusten hallintaa ei tarkoituksella tarjota työtilatunnuksille.

• API-käyttö sisältyy jokaiseen tilaukseen, myös Free-tilaukseen. Ylläpitäjällä on oltava työtilan muokkausoikeus.
• Työtilan isännän on otettava Admin API käyttöön asetuksella adminApiEnabled; muuten kelvollinen tunnus saa endpointista app-api resurssien olemassaoloa paljastamattoman 404-vastauksen.
• Ylläpitäjä voi myöntää vain omien nykyisten oikeuksiensa ja työtilan käyttöoikeuksien sallimat käyttöalueet.
• Uudet tunnukset voivat olla vanhenemattomia (työtilan asetusten oletus) tai käyttää ylläpitäjän valitsemaa 1–365 kokonaisen päivän voimassaoloa; palvelin laskee rajalliset absoluuttiset vanhenemisajat. Vanhenemattomat tunnukset pysyvät voimassa perumiseen saakka.
• Työtilalla voi olla enintään 50 aktiivista tunnusta.
• Selväkielinen tunnistetieto näytetään kerran. Tallenna se heti salaisuuksien hallintajärjestelmään.
• Nimi, käyttöalueet ja vanhenemisaika ovat muuttumattomia. Kierrätä luomalla korvaava tunnus, ottamalla se käyttöön, varmistamalla se ja perumalla vanha tunnus.
• Peruminen on välitön; perutut rivit pysyvät näkyvissä muuttumattomana, peitettynä työtilahistoriana. Bearer-tunnuksen introspektio- tai pysyvän poiston endpointia ei ole.

app-api ei sisällä endpointia näiden tunnistetietojen myöntämiseen, uusimiseen, luettelemiseen tai perumiseen. Tunnuksen hankkiminen on siis ihmisen ylläpitoportaalissa tehtävä ennakkovaatimus, ei tämän viitteen toinen endpoint.

Älä koskaan sijoita tunnusta versionhallintaan, URL-osoitteisiin, kyselymerkkijonoihin, evästeisiin, lokeihin, analytiikkaan tai virheraportteihin.

Todennus

Lähetä jokaisessa pyynnössä täsmälleen yksi RFC 6750 -tyylinen otsake:

Authorization: Bearer evc_ws_<selector>.<secret>

Tarkka läpinäkymätön tunnistetieto on evc_ws_, jota seuraavat 16-merkkinen kanoninen base64url-valitsin, . ja 43-merkkinen kanoninen base64url-salaisuus. Lähetä koko tunnistetieto muuttamattomana; älä base64-koodaa sitä uudelleen.

API hylkää toistuvat valtuutusotsakkeet, pilkulla yhdistetyt arvot, muut skeemat, tyhjät bearer-arvot, asiakkaiden JWT:t ja muualla kuin tässä otsakkeessa toimitetut tunnistetiedot.

Virheelliset, tuntemattomat, vanhentuneet, perutut tai muuten kelpaamattomat tunnukset saavat saman vastauksen:

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

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

Palvelu tarkistaa tunnuksen tilan ja työtilan nykyiset oikeudet jokaisella pyynnöllä. Oikeuden poistaminen voi siksi poistaa kyseiset käyttöalueet käytöstä ennen tunnuksen vanhenemista.

Työtilatunnukset ovat läpinäkymättömiä tunnistetietoja, eivät JWT:itä. Niillä ei ole uusintatunnusta eikä uusintaendpointia ole. Määräaikainen tunnus lakkaa todentamasta absoluuttisena expiresAt-hetkenään; vanhenematon tunnus pysyy voimassa perumiseen asti. Kierrätys tarkoittaa korvaavan tunnistetiedon luomista portaalissa, käyttöönottoa asiakkaalla ja vanhan tunnistetiedon perumista.

Pyyntökäytännöt

• Käytä Content-Type: application/json pyynnöissä, joissa on JSON-runko.
• Valinnaisista X-Request-Id-pyyntöarvoista poistetaan reunavälit, ja ne hyväksytään vain, jos niissä on 1–128 merkkiä joukoista A-Z, a-z, 0-9, ., _, : tai -; muutoin palvelin luo UUID:n. Jokainen vastaus palauttaa valitun arvon muodossa X-Request-Id.
• Valinnainen X-Error-Format: envelope muuntaa jokaisen JSON-virhevastauksen Vastaus- ja virhesopimuksessa dokumentoiduksi rakenteiseksi kääreeksi. Muut arvot säilyttävät oletusarvoisen yhteensopivuusrungon.
• Polkuparametrien tunnisteet ovat positiivisia kokonaislukuja. Portaalin palauttamat käyttötunnusten tunnisteet ovat desimaalimerkkijonoja, koska ne ovat tietokannan etumerkittömiä 64-bittisiä arvoja.
• Päiväys- ja aika-arvot ovat RFC 3339 -merkkijonoja, joissa on nimenomainen aikavyöhykesiirtymä, esimerkiksi 2026-08-13T12:30:00Z.
• Onnistuneet poistot palauttavat yleensä 204 No Content.
• Luontitoiminnot palauttavat tavallisesti 201 Created.
• Vain jonoon lisätty OCPP-työ voi palauttaa 202 Accepted; älä tulkitse sitä laturin vahvistukseksi, ellei vastaus nimenomaisesti niin kerro.
• Todennetut vastaukset käyttävät Cache-Control: no-store. QR- ja raporttivientien endpointit palauttavat binäärirunkoja, joilla on nimenomaiset sisältöotsakkeet.
• Sallitut selainalkuperät voivat lukea X-Request-Id, Idempotency-Replayed, Retry-After ja Content-Disposition CORSin kautta. Näin selainasiakkaat voivat yhdistää pyynnöt, tunnistaa idempotentit toistot, noudattaa uusintayritysten ajoitusta ja säilyttää palvelimen valitsemat lataustiedostojen nimet.

Idempotenssi

Kaikissa ylläpidon POST-, PUT-, PATCH- ja DELETE-pyynnöissä on oltava yksi Idempotency-Key-otsake. Avaimissa on 1–255 näkyvää merkkiä ja ne rajataan tunnukseen, metodiin ja polkuun.

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

Valmiin avaimen uudelleenkäyttö samalla URL-osoitteella ja rungolla toistaa tallennetun vastauksen ja lisää:

Idempotency-Replayed: true

Avaimen uudelleenkäyttö eri pyynnöllä palauttaa 409 IDEMPOTENCY_CONFLICT. Vielä käsiteltävä pyyntö palauttaa 409 IDEMPOTENT_REQUEST_PROCESSING ja Retry-After: 5.

Valmiit vastaukset ja lopulliset tulokset säilytetään toistoa tai täsmäytystä varten seitsemän päivää niiden viimeisimmästä päivityksestä. Tämän jälkeen sama avain voidaan käsitellä uutena komentona, joten asiakkaiden on käytettävä globaalisti yksilöllisiä avaimia eikä niitä saa tarkoituksella kierrättää.

Jos käsittelyvaraus vanhenee, yhteys sulkeutuu suorituksen alettua tai toiminto palauttaa palvelinvirheen, API ei voi turvallisesti todistaa, syntyikö ulkoinen vaikutus. Seitsemän päivän säilytysaikana avaimen tulos jää lopullisesti epäselväksi ja palauttaa 409 IDEMPOTENCY_OUTCOME_UNKNOWN; sitä ei oteta uudelleen käsittelyyn eikä suoriteta automaattisesti uudelleen. Varmista toiminnon vaikutukset ennen manuaalista palautustoimea äläkä lähetä samaa toimintoa uudella avaimella ennen täsmäytyksen valmistumista.

Kaikki muutoksia tekevät ylläpitoendpointit, myös POST /reports/send, edellyttävät Idempotency-Key.

Pyyntörajoitukset

Rajoja sovelletaan sekä yksittäiseen tunnukseen että sen työtilaan. Versionhallintaan tallennetut oletukset ovat:

Rajoitettu pyyntö palauttaa 429 Too Many Requests ja Retry-After-otsakkeen. Käyttöönotot voivat ohittaa nämä arvot.

Virheet

JSON-virheet käyttävät vakaata code-arvoa, kun kutsujan on haarautettava käsittelyä:

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

Validointivirheet käyttävät kenttätaulukoita:

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

Yleisiä tiloja ovat:

Käyttöalueluettelo

Seuraavaa käyttöalueluetteloa käytetään ylläpitäjän luodessa tunnuksen. Kirjoitus- tai suuren vaikutuksen käyttöalue voi sisältää vastaavan lukualueen, mutta lukualueet eivät koskaan anna kirjoitusoikeutta. Saatavilla olevat alueet riippuvat ylläpitäjän oikeuksista ja työtilan käytössä olevista toiminnoista.

Itse API-käyttö sisältyy jokaiseen tilaukseen ja sitä ohjaa isännän adminApiEnabled-asetus. Edellä mainitut lisätoimintojen oikeudet ovat silti voimassa; API-käyttö ei anna työtilan tilaukseen kuulumattomia toimintoja.

Endpoint-viite

Alla olevat taulukot luettelevat kaikki 87 työtilan ylläpitoreittiä. Solun useat käyttöalueet vaaditaan kaikki.

Työtila

Työtilan osapäivityskentät: name, email, website, addressLine1, addressLine2, postalCode, city, state ja countryId. Vähintään yksi kenttä vaaditaan. Tyhjät null-arvon sallivat merkkijonot normalisoidaan arvoon null.

Kohteet ja tehonhallinta

Kohteen luonti- ja osapäivitysrungot käyttävät:

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

Kohteen geokoodaus hyväksyy valinnaiset street-, city-, state-, country- ja kaksikirjaimiset countryCode-kyselykentät sekä Accept-Language-pyyntöotsakkeen. Yhdistetyn katu-/kaupunki-/osavaltiohaun on sisällettävä vähintään kaksi merkkiä. Vastaukset sisältävät vain placeId, displayName, latitude ja longitude; palveluntarjoajan tunnistetietoja tai tarjoajakohtaisia metatietoja ei paljasteta. Palvelin käyttää yhteistä yhden pyynnön sekuntijonoa tarjoajalle, kahdeksan sekunnin aikakatkaisua, rajattua 24 tunnin välimuistia ja globaaleja työtilatunnusten pyyntörajoja.

Tehonhallinta hyväksyy { "pools": [...] }. Ryhmällä on id, name, limit, valinnainen meterSources ja rekursiivinen children. Alilaturilla on chargepointId ja priority. API rajoittaa puun ja mittarien määrää ja tekee kaksivaiheisen OCPP-tyhjennyksen/uudelleenvalidoinnin korvatessaan asennetun tilan. Hylätty, aikakatkaistu tai samanaikaisuuskilpailuun joutunut muutos palauttaa 409 POWER_MANAGEMENT_CONFLICT säilyttäen aiemman määrityksen.

Laturit

Laturilokien kyselyparametrit ovat cursor, limit (oletus 50, enintään 200), from, to, action, direction ja levelId. Lataustapahtumien parametrit ovat page, limit (oletus 25, enintään 100), from, to ja customerId (positiivinen tunniste tai unknown). Yhdistelmäaikataulun historia käyttää cursor, limit (oletus 20, enintään 50) sekä valinnaista connectorId.

Raportit

Raporttitietojen ja viennin suodattimet ovat from, to, siteId, chargerId, userId, anonymous ja active. from/to ovat oletuksena viimeisin 90 päivän jakso, eivätkä ne saa kattaa yli 90 päivää. userId ei voi yhdistää arvoon anonymous=true.

• Tietojen sivutus: läpinäkymätön cursor, oletus limit=50, enintään 100.
• Mittaukset: pakollinen transactionLogId, läpinäkymätön cursor, oletus limit=500, enintään 1 000.
• Vienti: format=csv|pdf, oletus csv, ehdoton raja 2 000 riviä.
• Vientivastaukset käyttävät Content-Disposition: attachment, Cache-Control: private, no-store ja X-Content-Type-Options: nosniff.

Ajastuksen runko:

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

sendDay on 1–28 ja sendTime tulkitaan UTC-ajassa. Ajastin korvaa väliin jääneen ajastetun minuutin kuluvan toimituskuukauden aikana. Ennen luovutusta epäonnistuneet muodostukset yrittävät uudelleen 5 ja 10 minuutin kuluttua, keskeytynyt building-varaus voidaan ottaa uudelleen 30 minuutin jälkeen ja automaattinen toimitus päättyy kolmeen yritykseen. Ajastin tallentaa indeterminate juuri ennen SMTP-luovutusta; sekä indeterminate että vanha sending-tila ovat lopullisia, sillä kumman tahansa automaattinen uusinta voisi lähettää liitteen kahdesti. Operaattorien on täsmäytettävä nämä tulokset käsin ennen ajastustilan muuttamista. Jokainen kierros valitsee enintään kymmenen ajastusta, lopettaa töiden käynnistämisen 45 sekunnin aikabudjetin jälkeen ja käyttää rajattuja SMTP-aikakatkaisuja. Työ on oletuksena poissa käytöstä ja on otettava nimenomaisesti käyttöön SMTP:n ja kapasiteetin validoinnin jälkeen. API-ajastuksen omistaa työtila eikä se lainaa tunnuksen luoneen ihmisen identiteettiä.

Tariffit

Tariffin runko sisältää name, täsmälleen yhden arvoista currencyId, currencyCode tai currency, valinnaisen biddingZoneId sekä tax. Määrityksen runko on:

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

Määritystä luotaessa tariffia sovelletaan kaikkiin fyysisiin liittimiin, jos connectorId jätetään pois tai sen arvoksi asetetaan nimenomaisesti 0. Määrityspäivitykset kohdistuvat yhteen tallennettuun määritykseen, joten niissä vaaditaan nimenomainen positiivinen fyysinen connectorId; 0 hylätään.

Komponentti sisältää typeId, seasonId, price, valinnaisen priority sekä valinnaiset voimassaolorajat kuukaudelle, viikonpäivälle ja tunnille.

Latausprofiilit

Profiilin metatietokentät ovat label, locationId, stackLevel, purposeId, kindId, valinnaiset recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId ja valinnainen minChargingRate. Ajastusjakso sisältää startPeriod, limit ja valinnaisen numberOfPhases. Määrityksen runko sisältää profileId ja connectorId (oletus 0).

Profiilien poisto ja tehonhallinnan korvaaminen voivat odottaa laturin kuittausta. Hylkäys, aikakatkaisu tai samanaikainen tilamuutos palauttaa ristiriidan ja säilyttää tietokantamäärityksen sen sijaan, että laturin väitettäisiin tyhjentyneen.

Käyttäjät, kutsut, RFID, käyttöoikeudet ja rajat

Ajoneuvosivutus ja status=members-käyttäjäsivutus käyttävät positiivista numeerista cursor-arvoa. Kutsusivut käyttävät läpinäkymätöntä i2.*-kursoria, kun taas status=all käyttää ensimmäisen sivun jälkeen läpinäkymätöntä a2.*-yhdistelmäkursoria (numeerinen kursori kelpaa vain vanhan jäsenvirran jatkona). Käyttäjähaku toimitetaan X-Admin-User-Search-pyyntöotsakkeessa, jotta sähköpostiosoitteet eivät päädy URL-osoitteisiin tai käyttölokeihin. limit on oletuksena 50 ja enintään 100; käyttäjäluettelo tukee status=all|members|invitations. Käsittele kaikkia palautettuja kursoreita läpinäkymättöminä ja palauta ne muuttamattomina.

Suora käyttäjän luonti ei luo salasanaa, kirjautumisidentiteettiä tai istuntoa. Se liittää vain jo rekisteröidyn asiakkaan. Käytä kutsuendpointia tuntemattomalle sähköpostille. Suojattua Tagless-järjestelmäkäyttäjää ei voi muokata näiden reittien kautta.

Esimerkit

Aseta arvot komentotulkissa tulostamatta tunnusta:

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

Kohteiden luettelo:

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

Luo kohde turvallisesti:

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"

Lataa CSV-raportti nimenomaiselta UTC-ajanjaksolta:

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"

Tarkoitukselliset rajaukset

Työtilatunnus-API ei tarjoa toimintoja, jotka edellyttävät ihmisidentiteettiä tai laajempaa toimivaltaa. Näihin kuuluvat:

• tunnusten luonti, paljastus, kierrätys tai peruminen toisella tunnuksella;
• kirjautuminen, salasanan palautus, istunnot, ihmisroolien tai -oikeuksien delegointi ja työtilan omistusmuutokset;
• työtilan luonti/poisto ja laskutustilin jäsenyys;
• maksuasetukset, Stripen käyttöönotto, tilaukset, laskut ja isännän laskutus;
• isännän laajuiset tukitoiminnot ja tarjoajien webhookit;
• ihmisten ilmoitukset, navigoinnin uudelleenohjaukset, brändiresurssit ja kehitys-/testireitit.