Darbvietas administrēšanas API

Darbvietas administrēšanas API ļauj serveru savstarpējām integrācijām administrēt vienu EVCharge darbvietu. Šī dokumentācija paredzēta darbvietu administratoriem un ārējiem API integratoriem. Tā izmanto atsaucamus, darbvietai piesaistītus piekļuves marķierus un detalizētus tvērumus; klientu pieteikšanās marķieri un pārlūku sesijas netiek pieņemti.

Šis direktorijs ir kanoniskā izstrādātāju uzziņa /v2/admin API, ko īsteno app-api. Tas nedokumentē klientu/mobilos maršrutus vai administrēšanas portāla paša HTTP maršrutus.

• Galapunktu pieprasījumi un atbildes uzskaita visus 87 reģistrētos galapunktus, tvērumus, parametrus, pieprasījumu saturu un veiksmīgo atbilžu saturu.
• Shēmas un piemēri definē atkārtoti lietojamos pieprasījumu/atbilžu tipus un raksturīgus JSON satura piemērus.
• Atbilžu un kļūdu līgums definē visu kopīgo un galapunktam specifisko neveiksmīgo atbilžu saturu.

Bāzes URL un resursu robeža

Visi maršruti ir relatīvi pret izvietoto app-api izcelsmi:

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

Darbvietas ID netiek pieņemts URL, vaicājuma virknē vai pieprasījuma saturā. Katrs piekļuves marķieris ir piesaistīts tieši vienai darbvietai, un API iegūst cpoId no autentificētā marķiera identitātes. Ja ligzdots objekts, lādētājs, lietotājs, tarifs, profils, piešķīrums vai darījums nepieder šai darbvietai, API atgriež to pašu resursu uzskaitīšanu nepieļaujošo 404 RESOURCE_NOT_FOUND atbildi.

Piekļuves marķiera iegūšana

Darbvietas administrators marķierus izveido Darbvietas iestatījumu sadaļā API piekļuve. Marķieru pārvaldība apzināti nav pieejama ar darbvietas marķieriem.

• API piekļuve ir iekļauta katrā plānā, arī Free. Administratoram jābūt darbvietas rediģēšanas atļaujai.
• Darbvietas saimniekam jāieslēdz administrēšanas API ar adminApiEnabled; pretējā gadījumā derīgs marķieris saņem resursu uzskaitīšanu nepieļaujošu 404 no app-api.
• Administrators var piešķirt tikai tos tvērumus, kurus atļauj viņa pašreizējās atļaujas un darbvietas tiesības.
• Jauni marķieri var būt beztermiņa (Darbvietas iestatījumu noklusējums) vai ar administratora izvēlētu derīgumu veselās dienās no 1 līdz 365; serveris aprēķina galīgu absolūto beigu laiku. Beztermiņa marķieri paliek derīgi līdz atsaukšanai.
• Darbvietā var būt ne vairāk kā 50 aktīvi marķieri.
• Piekļuves dati atklātā tekstā tiek parādīti vienreiz. Nekavējoties saglabājiet tos noslēpumu pārvaldniekā.
• Nosaukums, tvērumi un derīguma termiņš nav maināmi. Lai veiktu nomaiņu, izveidojiet aizstājēju, izvietojiet to, pārbaudiet un atsauciet veco marķieri.
• Atsaukšana ir tūlītēja; atsauktās rindas paliek redzamas kā nemaināma, aizklāta darbvietas vēsture, un nav bearer marķiera introspekcijas vai neatgriezeniskas dzēšanas galapunkta.

app-api nav galapunkta, kas izsniedz, atsvaidzina, uzskaita vai atsauc šos piekļuves datus. Tādēļ marķiera iegūšana ir priekšnosacījums, ko cilvēks izpilda administrēšanas portālā, nevis cits šīs uzziņas galapunkts.

Nekad neievietojiet marķieri versiju kontrolē, URL, vaicājumu virknēs, sīkdatnēs, žurnālos, analītikā vai kļūdu pārskatos.

Autentifikācija

Katrā pieprasījumā nosūtiet tieši vienu RFC 6750 stila galveni:

Authorization: Bearer evc_ws_<selector>.<secret>

Precīzie necaurspīdīgie piekļuves dati ir evc_ws_, kam seko 16 rakstzīmju kanonisks base64url selektors, . un 43 rakstzīmju kanonisks base64url noslēpums. Sūtiet pilnu piekļuves datu vērtību nemainītu; nekodējiet to base64 vēlreiz.

API noraida dublētas autorizācijas galvenes, ar komatiem apvienotas vērtības, citas shēmas, tukšas bearer vērtības, klientu JWT un piekļuves datus, kas norādīti jebkur citur, nevis šajā galvenē.

Nepareizi formatēti, nezināmi, beigušies, atsaukti vai citādi nederīgi marķieri saņem vienādu atbildi:

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

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

Pakalpojums katrā pieprasījumā pārbauda marķiera statusu un darbvietas pašreizējās tiesības. Tādēļ tiesību noņemšana var atspējot ietekmētos tvērumus pirms marķiera termiņa beigām.

Darbvietu marķieri ir necaurspīdīgi piekļuves dati, nevis JWT. Tiem nav atsvaidzināšanas marķiera un nav atsvaidzināšanas galapunkta. Ierobežots marķieris pārstāj autentificēt absolūtajā expiresAt; beztermiņa marķieris paliek derīgs līdz atsaukšanai. Nomaiņa nozīmē aizstājošu piekļuves datu izveidi portālā, izvietošanu klientā un veco datu atsaukšanu.

Pieprasījumu konvencijas

• Pieprasījumiem ar JSON saturu izmantojiet Content-Type: application/json.
• Neobligāto X-Request-Id pieprasījumu vērtību sākuma un beigu atstarpes tiek noņemtas, un vērtības pieņem tikai tad, ja tās satur 1–128 rakstzīmes no A-Z, a-z, 0-9, ., _, : vai -; citādi serveris ģenerē UUID. Katra atbilde atgriež izvēlēto vērtību kā X-Request-Id.
• Neobligāts X-Error-Format: envelope pārvērš katru JSON kļūdas atbildi strukturētajā ietvarā, kas dokumentēts Atbilžu un kļūdu līgumā. Jebkura cita vērtība saglabā noklusējuma saderības saturu.
• Ceļa parametru ID ir pozitīvi veseli skaitļi. Portāla atgrieztie piekļuves marķieru ID ir decimālas virknes, jo tās ir 64 bitu bez zīmes datubāzes vērtības.
• Datuma un laika vērtības ir RFC 3339 virknes ar skaidri norādītu nobīdi, piemēram, 2026-08-13T12:30:00Z.
• Veiksmīga dzēšana parasti atgriež 204 No Content.
• Izveides darbības parasti atgriež 201 Created.
• Tikai rindā ievietots OCPP uzdevums var atgriezt 202 Accepted; neuzskatiet to par lādētāja apstiprinājumu, ja vien atbilde to skaidri nenorāda.
• Autentificētas atbildes izmanto Cache-Control: no-store. QR un pārskatu eksporta galapunkti atgriež bināru saturu ar skaidrām satura galvenēm.
• Atļautās pārlūka izcelsmes ar CORS var nolasīt X-Request-Id, Idempotency-Replayed, Retry-After un Content-Disposition. Tas ļauj pārlūka klientiem sasaistīt pieprasījumus, atpazīt idempotentus atkārtojumus, ievērot atkārtoto mēģinājumu laikus un saglabāt servera izvēlētos lejupielādes failu nosaukumus.

Idempotence

Visiem POST, PUT, PATCH un DELETE administrēšanas pieprasījumiem jāsatur viena Idempotency-Key galvene. Atslēgas satur 1–255 redzamas rakstzīmes un ir saistītas ar marķieri, metodi un ceļu.

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

Atkārtoti izmantojot pabeigtu atslēgu ar identisku URL un saturu, tiek atkārtota saglabātā atbilde un pievienots:

Idempotency-Replayed: true

Atkārtoti izmantojot atslēgu ar citu pieprasījumu, tiek atgriezts 409 IDEMPOTENCY_CONFLICT. Pieprasījums, kas vēl tiek apstrādāts, atgriež 409 IDEMPOTENT_REQUEST_PROCESSING ar Retry-After: 5.

Pabeigtas atbildes un galīgie rezultāti atkārtošanai vai saskaņošanai tiek saglabāti septiņas dienas pēc pēdējās atjaunināšanas. Pēc šī termiņa tā pati atslēga var tikt uzskatīta par jaunu komandu, tādēļ klientiem jāizmanto globāli unikālas atslēgas un tās nedrīkst apzināti izmantot atkārtoti.

Ja apstrādes rezervācija beidzas, savienojums tiek aizvērts pēc izpildes sākuma vai darbība atgriež servera kļūdu, API nevar droši pierādīt, vai notikusi ārēja ietekme. Septiņu dienu glabāšanas laikā atslēga ir galīgi nenoteiktā stāvoklī un atgriež 409 IDEMPOTENCY_OUTCOME_UNKNOWN; tā netiek atgūta vai automātiski izpildīta vēlreiz. Pirms manuālas atkopšanas pārbaudiet darbības sekas un neiesniedziet to pašu darbību ar jaunu atslēgu, kamēr saskaņošana nav pabeigta.

Visiem administrēšanas galapunktiem, kas maina datus, tostarp POST /reports/send, nepieciešams Idempotency-Key.

Biežuma ierobežojumi

Ierobežojumi tiek piemēroti gan atsevišķam marķierim, gan tā darbvietai. Kodā noteiktās noklusējuma vērtības ir:

Ierobežots pieprasījums atgriež 429 Too Many Requests un Retry-After galveni. Izvietojumos šīs vērtības var pārrakstīt.

Kļūdas

JSON kļūdas izmanto stabilu code, ja izsaucējam jāatšķir gadījumi:

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

Validācijas kļūdas izmanto lauku masīvus:

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

Bieži statusi ir:

Tvērumu katalogs

Tālāk norādītais tvērumu katalogs tiek izmantots, kad administrators izveido marķieri. Rakstīšanas vai augstas ietekmes tvērums var ietvert atbilstošo lasīšanas tvērumu, taču lasīšanas tvērumi nekad nepiešķir rakstīšanu. Pieejamie tvērumi ir atkarīgi no administratora atļaujām un darbvietā ieslēgtajām funkcijām.

Pati API piekļuve ir iekļauta katrā plānā, un to kontrolē saimnieka adminApiEnabled iestatījums. Iepriekš norādītās papildu funkciju tiesības joprojām ir spēkā; API piekļuve nepiešķir funkcijas ārpus darbvietas plāna.

Galapunktu uzziņa

Tālāk norādītās tabulas uzskaita visus 87 darbvietas administrēšanas maršrutus. Ja šūnā ir vairāki tvērumi, nepieciešami visi.

Darbvieta

Darbvietas daļējas atjaunināšanas lauki: name, email, website, addressLine1, addressLine2, postalCode, city, state un countryId. Nepieciešams vismaz viens lauks. Tukšas virknes, kas var būt null, tiek normalizētas uz null.

Objekti un jaudas pārvaldība

Objekta izveides un daļējas atjaunināšanas saturs izmanto:

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

Objektu ģeokodēšana pieņem neobligātus street, city, state, country un divu burtu countryCode vaicājuma laukus, kā arī Accept-Language pieprasījuma galveni. Apvienotajam ielas/pilsētas/reģiona meklējumam jāsatur vismaz divas rakstzīmes. Atbildes satur tikai placeId, displayName, latitude un longitude; pakalpojuma sniedzēja piekļuves dati un tam specifiskie metadati netiek atklāti. Serveris piemēro kopīgo pakalpojuma sniedzēja rindu ar vienu pieprasījumu sekundē, astoņu sekunžu noildzi, ierobežotu 24 stundu kešatmiņu un globālos darbvietu marķieru biežuma ierobežojumus.

Jaudas pārvaldība pieņem { "pools": [...] }. Grupa satur id, name, limit, neobligātu meterSources un rekursīvu children. Lādētāja bērnelements satur chargepointId un priority. API ierobežo koka un skaitītāju apjomu un veic divfāžu OCPP notīrīšanu/atkārtotu validāciju, aizstājot uzstādītu stāvokli. Noraidīta, noildzusi vai ar vienlaicīgu izmaiņu konfliktējoša darbība atgriež 409 POWER_MANAGEMENT_CONFLICT, saglabājot iepriekšējo konfigurāciju.

Lādētāji

Lādētāja žurnāla vaicājuma parametri ir cursor, limit (noklusējums 50, maksimums 200), from, to, action, direction un levelId. Sesiju parametri ir page, limit (noklusējums 25, maksimums 100), from, to un customerId (pozitīvs ID vai unknown). Apvienotā grafika vēsture izmanto cursor, limit (noklusējums 20, maksimums 50) un neobligātu connectorId.

Pārskati

Pārskatu datu un eksporta filtri ir from, to, siteId, chargerId, userId, anonymous un active. from/to noklusējums ir pēdējās 90 dienas, un tie nedrīkst aptvert vairāk par 90 dienām. userId nevar apvienot ar anonymous=true.

• Datu lapošana: necaurspīdīgs cursor, noklusējums limit=50, maksimums 100.
• Mērījumi: obligāts transactionLogId, necaurspīdīgs cursor, noklusējums limit=500, maksimums 1 000.
• Eksports: format=csv|pdf, noklusējums csv, stingrs ierobežojums 2 000 rindu.
• Eksporta atbildes izmanto Content-Disposition: attachment, Cache-Control: private, no-store un X-Content-Type-Options: nosniff.

Grafika saturs:

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

sendDay ir 1–28, un sendTime tiek interpretēts UTC. Plānotājs atgūst pašreizējā piegādes mēnesī izlaistu ieplānoto minūti. Pirms nodošanas neizdevusies izveide tiek atkārtota pēc 5 un 10 minūtēm, pārtrauktu building rezervāciju var atgūt pēc 30 minūtēm, un automātiskā piegāde beidzas pēc trim mēģinājumiem. Plānotājs saglabā indeterminate tieši pirms nodošanas SMTP; gan indeterminate, gan vecais sending statuss ir galīgi, jo jebkura automātiska atkārtošana varētu nosūtīt dublētu pielikumu. Operatoriem šie rezultāti jāsaskaņo manuāli pirms grafika stāvokļa maiņas. Katrā izpildes reizē tiek izvēlēti ne vairāk kā desmit grafiki, pēc 45 sekunžu budžeta netiek sākts jauns darbs, un tiek izmantotas ierobežotas SMTP noildzes. Uzdevums pēc noklusējuma ir atspējots, un tas skaidri jāieslēdz pēc SMTP un jaudas validācijas. API grafiks pieder darbvietai, nevis aizņemas marķieri izveidojušā cilvēka identitāti.

Tarifi

Tarifa saturs ietver name, tieši vienu no currencyId, currencyCode vai currency, neobligātu biddingZoneId un tax. Piešķīruma saturs ir:

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

Veidojot piešķīrumu, tarifs tiek piemērots visām fiziskajām pieslēgvietām, ja connectorId ir izlaists vai tā vērtība ir skaidri norādīta kā 0. Piešķīruma atjaunināšana mērķē uz vienu saglabātu piešķīrumu, tādēļ nepieciešams skaidri norādīts pozitīvs fiziskais connectorId; 0 tiek noraidīts.

Komponents satur typeId, seasonId, neobligātu lauku priority, obligātu lauku price un neobligātas derīguma robežas pēc mēneša, nedēļas dienas un stundas.

Uzlādes profili

Profila metadatu lauki ir label, locationId, stackLevel, purposeId, kindId, neobligāts recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId un neobligāts minChargingRate. Grafika periods satur startPeriod, limit un neobligātu numberOfPhases. Piešķīruma saturs ietver profileId un connectorId (noklusējums 0).

Profilu dzēšana un jaudas pārvaldības aizstāšana var gaidīt lādētāja apstiprinājumu. Noraidījums, noildze vai vienlaicīga stāvokļa maiņa atgriež konfliktu un saglabā datubāzes konfigurāciju, nevis izliekas, ka lādētājs ir notīrīts.

Lietotāji, uzaicinājumi, RFID, piekļuve un ierobežojumi

Transportlīdzekļu lapošana un status=members lietotāju lapošana izmanto pozitīvu skaitlisku cursor. Uzaicinājumu lapas izmanto necaurspīdīgu i2.* kursoru, savukārt status=all pēc pirmās lapas izmanto necaurspīdīgu apvienotu a2.* kursoru (skaitlisks kursors paliek derīgs tikai kā vecās dalībnieku plūsmas turpinājums). Lietotāju meklēšana tiek norādīta X-Admin-User-Search pieprasījuma galvenē, lai e-pasta adreses nenonāktu URL vai piekļuves žurnālos. limit noklusējums ir 50, un tas ir ierobežots līdz 100; lietotāju saraksts atbalsta status=all|members|invitations. Visus atgrieztos kursorus uzskatiet par necaurspīdīgiem un atgrieziet nemainītus.

Tieša lietotāja izveide neizveido paroli, pieteikšanās identitāti vai sesiju. Tā tikai piesaista jau reģistrētu klientu. Nezināmai e-pasta adresei izmantojiet uzaicinājuma galapunktu. Aizsargāto Tagless sistēmas lietotāju šajos maršrutos nevar mainīt.

Piemēri

Iestatiet vērtības komandrindas čaulā, neizdrukājot marķieri:

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

Objektu uzskaitījums:

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

Izveidojiet objektu droši:

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"

Lejupielādējiet CSV pārskatu skaidri norādītam UTC diapazonam:

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"

Apzināti izņēmumi

Darbvietas marķieru API neatklāj darbības, kurām nepieciešama cilvēka identitāte vai plašākas pilnvaras. Tās ietver:

• marķieru izveide, atklāšana, nomaiņa vai atsaukšana ar citu marķieri;
• pieteikšanās, paroles atiestatīšana, sesijas, cilvēku lomu vai privilēģiju deleģēšana un darbvietas īpašnieka maiņa;
• darbvietas izveide/dzēšana un dalība norēķinu kontā;
• maksājumu iestatījumi, Stripe reģistrācija, plāni, rēķini un saimnieka norēķini;
• saimnieka mēroga atbalsta darbības un pakalpojumu sniedzēju tīmekļa aizķeres;
• cilvēkiem paredzēti paziņojumi, navigācijas pāradresācijas, zīmola resursi un izstrādes/testa maršruti.