Darbo srities administravimo API

Darbo srities administravimo API leidžia serverių tarpusavio integracijoms administruoti vieną „EVCharge“ darbo sritį. Ši dokumentacija skirta darbo sričių administratoriams ir išorinių API integracijų kūrėjams. Naudojami atšaukiami, su darbo sritimi susieti prieigos raktai ir detalios prieigos sritys; klientų prisijungimo raktai ir naršyklės seansai nepriimami.

Šis katalogas yra pagrindinis /v2/admin API, kurį įgyvendina app-api, kūrėjų žinynas. Jis neaprašo klientų / mobiliųjų maršrutų ar paties administravimo portalo HTTP maršrutų.

• Galinių taškų užklausos ir atsakymai išvardija visus 87 registruotus galinius taškus, prieigos sritis, parametrus, užklausų turinį ir sėkmingų atsakymų turinį.
• Schemos ir pavyzdžiai apibrėžia pakartotinai naudojamus užklausų / atsakymų tipus ir tipišką JSON turinį.
• Atsakymų ir klaidų sutartis apibrėžia visą bendrą ir konkrečiam galiniam taškui būdingą nesėkmės turinį.

Bazinis URL ir išteklių riba

Visi maršrutai yra santykiniai įdiegtos app-api paslaugos pradžios adreso atžvilgiu:

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

Darbo srities ID nepriimamas URL, užklausos eilutėje ar užklausos turinyje. Kiekvienas prieigos raktas susietas tik su viena darbo sritimi, o API nustato cpoId iš autentifikuoto rakto tapatybės. Jei įdėtoji vieta, įkroviklis, naudotojas, tarifas, profilis, priskyrimas ar operacija nepriklauso tai darbo sričiai, API grąžina tą patį ištekliaus egzistavimo neatskleidžiantį 404 RESOURCE_NOT_FOUND atsakymą.

Prieigos rakto gavimas

Darbo srities administratorius kuria prieigos raktus Darbo srities nustatymų skiltyje „API prieiga“. Prieigos raktų valdymas sąmoningai neprieinamas naudojant darbo srities prieigos raktus.

• API prieiga įtraukta į visus planus, įskaitant „Free“. Administratorius turi turėti teisę redaguoti darbo sritį.
• Darbo srities paslaugos teikėjas turi įjungti administravimo API per adminApiEnabled; kitu atveju galiojantis prieigos raktas gauna ištekliaus egzistavimo neatskleidžiantį 404 iš app-api.
• Administratorius gali suteikti tik tas prieigos sritis, kurias leidžia jo dabartinės teisės ir darbo srities suteiktos funkcijų teisės.
• Nauji prieigos raktai gali neturėti galiojimo pabaigos (numatyta Darbo srities nustatymuose) arba gali galioti administratoriaus pasirinktą sveiką dienų skaičių nuo 1 iki 365; baigtinį absoliutų galiojimo pabaigos laiką apskaičiuoja serveris. Raktai be galiojimo pabaigos galioja, kol atšaukiami.
• Darbo srityje gali būti daugiausia 50 aktyvių prieigos raktų.
• Prisijungimo duomenys atviru tekstu rodomi tik vieną kartą. Iškart išsaugokite juos slaptų duomenų valdymo sistemoje.
• Pavadinimas, prieigos sritys ir galiojimo pabaiga nekeičiami. Rotacijai sukurkite pakaitinį raktą, įdiekite jį, patikrinkite ir atšaukite senąjį.
• Atšaukimas įsigalioja iškart; atšaukti įrašai lieka matomi kaip nekintama darbo srities istorija su paslėptais jautriais duomenimis. Nėra „Bearer“ prieigos rakto introspekcijos arba galutinio ištrynimo galinio taško.

app-api neturi galinio taško, kuris išduotų, atnaujintų, išvardytų arba atšauktų šiuos prisijungimo duomenis. Todėl prieigos rakto gavimas yra išankstinis veiksmas, atliekamas žmogaus administravimo portale, o ne kitas šio žinyno galinis taškas.

Niekada nedėkite prieigos rakto į versijų valdymo sistemą, URL, užklausų eilutes, slapukus, žurnalus, analizę ar klaidų ataskaitas.

Autentifikavimas

Kiekvienoje užklausoje siųskite tiksliai vieną RFC 6750 stiliaus antraštę:

Authorization: Bearer evc_ws_<selector>.<secret>

Tikslūs nepermatomi prisijungimo duomenys yra evc_ws_, po kurio eina 16 simbolių kanoninis base64url parinkiklis, . ir 43 simbolių kanoninė base64url paslaptis. Siųskite visus prisijungimo duomenis nepakeistus; nekoduokite jų base64 dar kartą.

API atmeta pasikartojančias autorizavimo antraštes, kableliais sujungtas reikšmes, kitas schemas, tuščias „Bearer“ reikšmes, klientų JWT ir prisijungimo duomenis, pateiktus bet kur kitur nei šioje antraštėje.

Netaisyklingi, nežinomi, pasibaigusio galiojimo, atšaukti ar kitaip netinkami prieigos raktai gauna tą patį atsakymą:

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

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

Paslauga tikrina prieigos rakto būseną ir esamas darbo srities teises kiekvienoje užklausoje. Todėl pašalinus teisę paveiktos prieigos sritys gali būti išjungtos dar nepasibaigus rakto galiojimui.

Darbo srities prieigos raktai yra nepermatomi prisijungimo duomenys, o ne JWT. Jie neturi atnaujinimo rakto, ir nėra atnaujinimo galinio taško. Riboto galiojimo raktas nustoja autentifikuoti absoliučiu expiresAt laiku; neriboto galiojimo raktas galioja iki atšaukimo. Rotacija reiškia pakaitinių prisijungimo duomenų sukūrimą portale, jų įdiegimą kliente ir senųjų atšaukimą.

Užklausų taisyklės

• Užklausoms su JSON turiniu naudokite Content-Type: application/json.
• Iš neprivalomų X-Request-Id užklausos reikšmių pašalinami kraštiniai tarpai. Jos priimamos tik jei jose yra 1–128 simboliai iš A-Z, a-z, 0-9, ., _, : arba -; kitu atveju serveris sugeneruoja UUID. Kiekviename atsakyme pasirinkta reikšmė grąžinama kaip X-Request-Id.
• Neprivalomas X-Error-Format: envelope paverčia kiekvieną JSON klaidos atsakymą struktūrizuotu apvalkalu, dokumentuotu Atsakymų ir klaidų sutartyje. Bet kuri kita reikšmė išlaiko numatytąjį suderinamumo turinį.
• ID kelio parametruose yra teigiami sveikieji skaičiai. Portalo grąžinami prieigos raktų ID yra dešimtainės eilutės, nes duomenų bazėje jie yra 64 bitų reikšmės be ženklo.
• Datos ir laiko reikšmės yra RFC 3339 eilutės su aiškiu laiko poslinkiu, pavyzdžiui, 2026-08-13T12:30:00Z.
• Sėkmingos trynimo operacijos paprastai grąžina 204 No Content.
• Kūrimo operacijos paprastai grąžina 201 Created.
• Tik į eilę įtraukta OCPP operacija gali grąžinti 202 Accepted; nelaikykite to įkroviklio patvirtinimu, nebent atsakyme tai aiškiai nurodyta.
• Autentifikuoti atsakymai naudoja Cache-Control: no-store. QR ir ataskaitų eksporto galiniai taškai grąžina dvejetainį turinį su aiškiomis turinio antraštėmis.
• Leidžiamos naršyklės kilmės per CORS gali skaityti X-Request-Id, Idempotency-Replayed, Retry-After ir Content-Disposition. Tai leidžia naršyklės klientams susieti užklausas, aptikti idempotentinius pakartojimus, laikytis pakartojimo laiko ir išlaikyti serverio pasirinktus atsisiuntimo failų pavadinimus.

Idempotentiškumas

Visose POST, PUT, PATCH ir DELETE administravimo užklausose turi būti viena Idempotency-Key antraštė. Raktuose yra 1–255 matomi simboliai, o jų sritis susieta su prieigos raktu, metodu ir keliu.

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

Pakartotinai panaudojus užbaigtą raktą su tuo pačiu URL ir turiniu pakartojamas išsaugotas atsakymas ir pridedama:

Idempotency-Replayed: true

Pakartotinai panaudojus raktą kitai užklausai grąžinamas 409 IDEMPOTENCY_CONFLICT. Dar apdorojama užklausa grąžina 409 IDEMPOTENT_REQUEST_PROCESSING su Retry-After: 5.

Užbaigti atsakymai ir galutiniai rezultatai saugomi pakartojimui arba suderinimui septynias dienas po paskutinio atnaujinimo. Pasibaigus šiam laikotarpiui tas pats raktas gali būti laikomas nauja komanda, todėl klientai privalo naudoti globaliai unikalius raktus ir negali sąmoningai jų naudoti iš naujo.

Jei baigiasi apdorojimo rezervacijos laikas, ryšys nutrūksta pradėjus vykdymą arba operacija grąžina serverio klaidą, API negali saugiai nustatyti, ar įvyko išorinis poveikis. Septynių dienų saugojimo laikotarpiu rakto būsena lieka galutinai neapibrėžta ir grąžina 409 IDEMPOTENCY_OUTCOME_UNKNOWN; jis neperimamas ir operacija automatiškai nebevykdoma. Prieš imdamiesi rankinio atkūrimo patikrinkite operacijos poveikį ir neteikite tos pačios operacijos su nauju raktu, kol suderinimas neužbaigtas.

Visiems duomenis keičiantiems administravimo galiniams taškams, įskaitant POST /reports/send, reikia Idempotency-Key.

Užklausų dažnio ribos

Ribos taikomos ir atskiram prieigos raktui, ir jo darbo sričiai. Saugykloje nustatytos numatytosios reikšmės:

Pasiekus ribą užklausa grąžina 429 Too Many Requests ir antraštę Retry-After. Diegimo aplinkoje šias reikšmes galima pakeisti.

Klaidos

JSON klaidos naudoja stabilų code, kai kviečiančiajai programai reikia pasirinkti tolesnę eigą:

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

Tikrinimo klaidos naudoja laukų masyvus:

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

Įprastos būsenos:

Prieigos sričių katalogas

Toliau pateiktas prieigos sričių katalogas naudojamas administratoriui kuriant prieigos raktą. Rašymo arba didelio poveikio sritis gali numanyti atitinkamą skaitymo sritį, tačiau skaitymo sritys niekada nesuteikia rašymo. Prieinamos sritys priklauso nuo administratoriaus teisių ir darbo srities įjungtų funkcijų.

Pati API prieiga įtraukta į visus planus ir valdoma paslaugos teikėjo nustatymu adminApiEnabled. Papildomos pirmiau nurodytos teisės į funkcijas vis tiek taikomos; API prieiga nesuteikia funkcijų, kurių nėra darbo srities plane.

Galinių taškų žinynas

Toliau pateiktose lentelėse išvardyti visi 87 darbo srities administravimo maršrutai. Jei langelyje yra kelios prieigos sritys, būtinos visos.

Darbo sritis

Darbo srities dalinio atnaujinimo laukai: name, email, website, addressLine1, addressLine2, postalCode, city, state ir countryId. Būtinas bent vienas laukas. Tuščios eilutės, kurioms leidžiama null, normalizuojamos į null.

Vietos ir galios valdymas

Vietos kūrimo ir dalinio atnaujinimo turinys naudoja:

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

Vietos geokodavimas priima neprivalomus street, city, state, country ir dviejų raidžių countryCode užklausos laukus bei Accept-Language užklausos antraštę. Bendroje gatvės / miesto / regiono paieškoje turi būti bent du simboliai. Atsakymuose yra tik placeId, displayName, latitude ir longitude; paslaugos teikėjo prisijungimo duomenys ir jam būdingi metaduomenys neatskleidžiami. Serveris taiko bendrą vienos užklausos per sekundę paslaugos teikėjo eilę, aštuonių sekundžių laukimo ribą, ribotą 24 valandų podėlį ir bendras darbo srities prieigos raktų užklausų dažnio ribas.

Galios valdymas priima { "pools": [...] }. Grupę sudaro id, name, limit, neprivalomas meterSources ir rekursinis children. Antrinis įkroviklis turi chargepointId ir priority. API riboja medžio ir skaitiklių skaičių bei keisdamas įdiegtą būseną atlieka dviejų etapų OCPP išvalymą ir pakartotinę patikrą. Atmestas pakeitimas, pasibaigęs laukimo laikas arba lygiagrečių operacijų lenktynių paveiktas pakeitimas grąžina 409 POWER_MANAGEMENT_CONFLICT, išsaugant ankstesnę konfigūraciją.

Įkrovikliai

Įkroviklio žurnalo užklausos parametrai yra cursor, limit (numatyta 50, daugiausia 200), from, to, action, direction ir levelId. Seansų parametrai yra page, limit (numatyta 25, daugiausia 100), from, to ir customerId (teigiamas ID arba unknown). Sudėtinio tvarkaraščio istorija naudoja cursor, limit (numatyta 20, daugiausia 50) ir neprivalomą connectorId.

Ataskaitos

Ataskaitos duomenų ir eksporto filtrai yra from, to, siteId, chargerId, userId, anonymous ir active. from/to numatytai apima paskutines 90 dienų ir negali apimti daugiau nei 90 dienų. userId negalima derinti su anonymous=true.

• Duomenų puslapiavimas: nepermatomas cursor, numatyta limit=50, daugiausia 100.
• Matavimai: būtinas transactionLogId, nepermatomas cursor, numatyta limit=500, daugiausia 1 000.
• Eksportas: format=csv|pdf, numatyta csv, griežta 2 000 eilučių riba.
• Eksporto atsakymai naudoja Content-Disposition: attachment, Cache-Control: private, no-store ir X-Content-Type-Options: nosniff.

Tvarkaraščio turinys:

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

sendDay yra 1–28, o sendTime interpretuojamas UTC laiku. Planuoklis kompensuoja praleistą suplanuotą minutę per dabartinį pristatymo mėnesį. Nepavykę kūrimo bandymai iki perdavimo kartojami po 5 ir 10 minučių, nutrūkusią building užduoties rezervaciją galima perimti po 30 minučių, o automatinis pristatymas sustabdomas po trijų bandymų. Planuoklis išsaugo indeterminate prieš pat perdavimą SMTP; tiek indeterminate, tiek senasis sending statusas yra galutiniai, nes automatiškai kartojant bet kurį jų galima išsiųsti pakartotinį priedą. Operatoriai turi rankiniu būdu suderinti šiuos rezultatus prieš keisdami tvarkaraščio būseną. Kiekvienas ciklas pasirenka daugiausia dešimt tvarkaraščių, nustoja pradėti naujus darbus po 45 sekundžių laiko limito ir naudoja ribotus SMTP laukimo laikus. Užduotis pagal numatymą išjungta ir turi būti aiškiai įjungta patikrinus SMTP bei pajėgumą. API tvarkaraštis priklauso darbo sričiai, o ne perima prieigos raktą sukūrusio žmogaus tapatybę.

Tarifai

Tarifo užklausos turinį sudaro name, tiksliai vienas iš currencyId, currencyCode arba currency, neprivalomas biddingZoneId ir tax. Priskyrimo užklausos turinys:

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

Kuriant priskyrimą, tarifas taikomas visoms fizinėms jungtims, jei connectorId nepateikiamas arba jo reikšmė aiškiai nustatoma į 0. Priskyrimo atnaujinimas skirtas vienam išsaugotam priskyrimui, todėl būtinas aiškiai nurodytas teigiamas fizinės jungties connectorId; 0 atmetamas.

Komponentą sudaro privalomi typeId, seasonId ir price; priority ir galiojimo ribos pagal mėnesį, savaitės dieną bei valandą yra neprivalomi.

Įkrovimo profiliai

Profilio metaduomenų laukai yra label, locationId, stackLevel, purposeId, kindId, neprivalomas recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId ir neprivalomas minChargingRate. Tvarkaraščio laikotarpį sudaro startPeriod, limit ir neprivalomas numberOfPhases. Priskyrimo turinį sudaro profileId ir connectorId (numatyta 0).

Profilių trynimas ir galios valdymo pakeitimas gali laukti įkroviklio patvirtinimo. Atmetus, pasibaigus laikui arba įvykus lygiagrečiam būsenos pakeitimui grąžinamas konfliktas ir išsaugoma duomenų bazės konfigūracija, užuot apsimetus, kad įkroviklis išvalytas.

Naudotojai, kvietimai, RFID, prieiga ir ribos

Automobilių puslapiavimas ir status=members naudotojų puslapiavimas naudoja teigiamą skaitinį cursor. Kvietimų puslapiai naudoja nepermatomą i2.* žymeklį, o status=all po pirmojo puslapio naudoja nepermatomą sudėtinį a2.* žymeklį (skaitinis žymeklis lieka tinkamas tik kaip senosios narių srauto versijos tęsinys). Naudotojų paieška pateikiama X-Admin-User-Search užklausos antraštėje, kad el. pašto adresai nepatektų į URL ar prieigos žurnalus. limit numatyta reikšmė yra 50, daugiausia 100; naudotojų sąrašas palaiko status=all|members|invitations. Visus grąžintus žymeklius laikykite nepermatomais ir grąžinkite nepakeistus.

Tiesioginis naudotojo kūrimas nesukuria slaptažodžio, prisijungimo tapatybės ar seanso. Jis tik prijungia jau registruotą klientą. Nežinomam el. pašto adresui naudokite kvietimų galinį tašką. Apsaugoto „Tagless“ sistemos naudotojo negalima keisti šiais maršrutais.

Pavyzdžiai

Nustatykite reikšmes savo komandų aplinkoje neišvesdami prieigos rakto:

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

Gaukite vietų sąrašą:

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

Saugiai sukurkite vietą:

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"

Atsisiųskite CSV ataskaitą aiškiai nurodytam UTC intervalui:

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"

Sąmoningai neįtrauktos galimybės

Darbo srities prieigos raktų API neteikia operacijų, kurioms būtina žmogaus tapatybė ar platesni įgaliojimai. Tai apima:

• prieigos raktų kūrimą, atskleidimą, rotaciją arba atšaukimą naudojant kitą prieigos raktą;
• prisijungimą, slaptažodžio nustatymą iš naujo, seansus, žmonių vaidmenų ar teisių delegavimą ir darbo srities nuosavybės keitimą;
• darbo srities kūrimą / trynimą ir narystę atsiskaitymo paskyroje;
• mokėjimo nustatymus, „Stripe“ registracijos eigą, planus, sąskaitas faktūras ir paslaugos teikėjo atsiskaitymą;
• viso paslaugos teikėjo pagalbos operacijas ir tiekėjų webhookus;
• pranešimus žmonėms, naršymo peradresavimus, prekės ženklo išteklius ir kūrimo / bandymo maršrutus.