API tal-Amministrazzjoni tal-Ispazju tax-Xogħol

L-API tal-Amministrazzjoni tal-Ispazju tax-Xogħol iħalli integrazzjonijiet server-to-server jamministraw spazju tax-xogħol EVCharge wieħed. Din id-dokumentazzjoni hija għall-amministraturi tal-ispazji tax-xogħol u integraturi esterni tal-API. Tuża tokens tal-aċċess revokabbli marbuta mal-ispazju tax-xogħol u ambiti dettaljati; tokens tal-login tal-klijenti u sessjonijiet tal-browser ma jiġux aċċettati.

Dan id-direttorju huwa r-referenza kanonika għall-iżviluppaturi għall-API /v2/admin implimentat minn app-api. Ma jiddokumentax rotot tal-klijenti/mobbli jew ir-rotot HTTP tal-portal amministrattiv innifsu.

• Talbiet u risponsi tal-endpoints jelenka s-87 endpoint reġistrat, l-ambiti, il-parametri, il-bodies tat-talbiet u l-bodies tas-suċċess kollha.
• Skemi u eżempji jiddefinixxi t-tipi tat-talbiet/risponsi li jistgħu jerġgħu jintużaw u payloads JSON rappreżentattivi.
• Kuntratt tar-risponsi u l-iżbalji jiddefinixxi kull body mhux ta' suċċess kondiviża u speċifika għall-endpoint.

URL bażi u konfini tar-riżorsi

Ir-rotot kollha huma relattivi għall-origin implimentata app-api:

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

L-ID tal-ispazju tax-xogħol mhuwiex aċċettat fil-URL, fil-query string jew fil-body tat-talba. Kull token tal-aċċess huwa marbut ma' eżattament spazju tax-xogħol wieħed, u l-API jidderiva cpoId mill-prinċipal tat-token awtentikat. Jekk sit, ċarġer, utent, tariffa, profil, assenjazzjoni jew tranżazzjoni nested ma jappartjenix għal dak l-ispazju tax-xogħol, l-API jirritorna l-istess rispons 404 RESOURCE_NOT_FOUND li ma jiżvelax ir-riżorsi.

Kif tikseb token tal-aċċess

Amministratur uman tal-ispazju tax-xogħol joħloq tokens fis-Settings tal-Ispazju tax-Xogħol taħt Aċċess API. Il-ġestjoni tat-tokens intenzjonalment mhix disponibbli għat-tokens tal-ispazju tax-xogħol.

• L-aċċess API huwa inkluż f'kull pjan, inkluż Free. L-amministratur irid ikollu permess biex jeditja l-ispazju tax-xogħol.
• Il-host tal-ispazju tax-xogħol irid jattiva l-API tal-Amministrazzjoni permezz ta' adminApiEnabled; inkella token validu jirċievi 404 li ma jiżvelax ir-riżorsi minn app-api.
• L-amministratur jista' jagħti biss ambiti permessi mill-permessi attwali tiegħu stess u mid-drittijiet tal-ispazju tax-xogħol.
• Tokens ġodda jistgħu ma jiskadux (il-valur predefinit tas-Settings tal-Ispazju tax-Xogħol) jew jużaw ħajja f'jiem sħaħ magħżula mill-amministratur minn 1 sa 365 jum; is-server jikkalkula skadenzi assoluti finiti. Tokens li ma jiskadux jibqgħu validi sakemm jiġu revokati.
• Spazju tax-xogħol jista' jkollu massimu ta' 50 token attiv.
• Il-kredenzjal f'test ċar jintwera darba. Aħżnu immedjatament f'maniġer tas-sigrieti.
• L-isem, l-ambiti u l-iskadenza ma jistgħux jinbidlu. Biex iddawwar il-kredenzjali, oħloq sostitut, implimentah, ivverifikah u rrevoka t-token il-qadim.
• Ir-revoka hija immedjata; ringieli revokati jibqgħu viżibbli bħala storja tal-ispazju tax-xogħol immutabbli b'data sensittiva moħbija, u m'hemmx endpoint għall-introspezzjoni ta' token bearer jew tħassir permanenti.

app-api m'għandux endpoint li joħroġ, iġedded, jelenka jew jirrevoka dawn il-kredenzjali. Għalhekk il-kisba tat-token hija prerekwiżit imwettaq permezz tal-portal amministrattiv uman, mhux endpoint ieħor f'din ir-referenza.

Qatt tpoġġi t-token fil-kontroll tal-verżjonijiet, URLs, query strings, cookies, logs, analiżi jew rapporti tal-iżbalji.

Awtentikazzjoni

Ibgħat eżattament header wieħed fl-istil RFC 6750 ma' kull talba:

Authorization: Bearer evc_ws_<selector>.<secret>

Il-kredenzjal opak eżatt huwa evc_ws_ segwit minn selettur base64url kanoniku ta' 16-il karattru, ., u sigriet base64url kanoniku ta' 43 karattru. Ibgħat il-kredenzjal sħiħ eżatt kif inhu; tikkodifikahx mill-ġdid b'base64.

L-API jirrifjuta headers tal-awtorizzazzjoni duplikati, valuri magħquda b'virgoli, skemi oħra, valuri bearer vojta, JWTs tal-klijenti u kredenzjali pprovduti kullimkien ħlief f'dan il-header.

Tokens malformati, mhux magħrufa, skaduti, revokati jew invalidi b'xi mod ieħor kollha jirċievu l-istess rispons:

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

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

Is-servizz jiċċekkja l-istatus tat-token u d-drittijiet attwali tal-ispazju tax-xogħol ma' kull talba. Għalhekk it-tneħħija ta' dritt tista' tiddiżattiva l-ambiti affettwati qabel jiskadi t-token.

It-tokens tal-ispazju tax-xogħol huma kredenzjali opaki, mhux JWTs. M'għandhomx token ta' tiġdid u m'hemmx endpoint tat-tiġdid. Token finit jieqaf jawtentika fl-expiresAt assolut tiegħu; token li ma jiskadix jibqa' validu sakemm jiġi revokat. Ir-rotazzjoni tfisser li toħloq kredenzjal sostitut fil-portal, timplimentah fil-klijent u tirrevoka l-kredenzjal il-qadim.

Konvenzjonijiet tat-talbiet

• Uża Content-Type: application/json għal talbiet b'body JSON.
• Jitneħħew l-ispazji mit-truf tal-valuri fakultattivi X-Request-Id tat-talba u jiġu aċċettati biss meta jkun fihom 1–128 karattru minn A-Z, a-z, 0-9, ., _, : jew -; inkella s-server jiġġenera UUID. Kull rispons jirritorna l-valur magħżul bħala X-Request-Id.
• X-Error-Format: envelope fakultattiv jikkonverti kull rispons ta' żball JSON fl-envelope strutturat dokumentat f'Kuntratt tar-risponsi u l-iżbalji. Kwalunkwe valur ieħor iżomm il-body tal-kompatibbiltà predefinita.
• L-IDs fil-parametri tal-path huma numri sħaħ pożittivi. L-IDs tat-tokens tal-aċċess irritornati mill-portal huma strings deċimali għax huma valuri tad-database unsigned ta' 64 bit.
• Il-valuri tad-data u l-ħin huma strings RFC 3339 b'offset espliċitu, pereżempju 2026-08-13T12:30:00Z.
• Tħassir li jirnexxi normalment jirritorna 204 No Content.
• L-operazzjonijiet tal-ħolqien normalment jirritornaw 201 Created.
• Xogħol OCPP li jkun tqiegħed biss fil-kju jista' jirritorna 202 Accepted; tinterpretax dan bħala konferma miċ-ċarġer sakemm ir-rispons ma jgħidx hekk espliċitament.
• Ir-risponsi awtentikati jużaw Cache-Control: no-store. L-endpoints QR u tal-esportazzjoni tar-rapporti jirritornaw bodies binarji b'headers espliċiti tal-kontenut.
• L-origins tal-browser permessi jistgħu jaqraw X-Request-Id, Idempotency-Replayed, Retry-After u Content-Disposition permezz ta' CORS. Dan iħalli lill-klijenti tal-browser jikkorrelataw it-talbiet, jidentifikaw ripetizzjonijiet idempotenti, jirrispettaw il-ħinijiet tal-prova mill-ġdid u jżommu l-ismijiet tal-fajls magħżula mis-server għat-tniżżil.

Idempotenza

It-talbiet amministrattivi kollha POST, PUT, PATCH u DELETE iridu jinkludu header wieħed Idempotency-Key. Iċ-ċwievet fihom 1–255 karattru viżibbli u huma marbuta mat-token, il-metodu u l-path.

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

L-użu mill-ġdid ta' ċavetta kompluta bl-istess URL u body jirrepeti r-rispons maħżun u jżid:

Idempotency-Replayed: true

L-użu mill-ġdid ta' ċavetta b'talba differenti jirritorna 409 IDEMPOTENCY_CONFLICT. Talba li għadha qed tiġi pproċessata tirritorna 409 IDEMPOTENT_REQUEST_PROCESSING b'Retry-After: 5.

Ir-risponsi kompluti u l-eżiti finali jinżammu għal ripetizzjoni jew rikonċiljazzjoni għal sebat ijiem wara l-aħħar aġġornament tagħhom. Wara dak il-perjodu, l-istess ċavetta tista' titqies bħala kmand ġdid, għalhekk il-klijenti jridu jużaw ċwievet uniċi globalment u ma għandhomx jerġgħu jużawhom intenzjonalment.

Jekk jiskadi lease tal-ipproċessar, il-konnessjoni tingħalaq wara li tibda l-eżekuzzjoni jew l-operazzjoni tirritorna żball tas-server, l-API ma jistax jipprova b'mod sigur jekk seħħx effett estern. Matul il-perjodu ta' żamma ta' sebat ijiem, iċ-ċavetta tibqa' fi stat finalment indeterminat u tirritorna 409 IDEMPOTENCY_OUTCOME_UNKNOWN; ma terġax tintalab jew tiġi eżegwita awtomatikament. Ivverifika l-effetti tal-operazzjoni qabel tieħu azzjoni manwali ta' rkupru, u tissottomettix l-istess operazzjoni b'ċavetta ġdida sakemm titlesta dik ir-rikonċiljazzjoni.

L-endpoints amministrattivi kollha li jbiddlu d-data, inkluż POST /reports/send, jeħtieġu Idempotency-Key.

Limiti tar-rata

Il-limiti japplikaw kemm għat-token individwali kif ukoll għall-ispazju tax-xogħol tiegħu. Il-valuri predefiniti fil-kodiċi huma:

Talba limitata tirritorna 429 Too Many Requests u header Retry-After. L-implimentazzjonijiet jistgħu jibdlu dawn il-valuri.

Żbalji

L-iżbalji JSON jużaw code stabbli fejn min jagħmel is-sejħa jeħtieġ jiddistingwi l-każijiet:

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

L-iżbalji tal-validazzjoni jużaw arrays tal-oqsma:

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

L-istatus komuni huma:

Katalogu tal-ambiti

Il-katalogu tal-ambiti li ġej jintuża meta amministratur joħloq token. Ambitu tal-kitba jew b'impatt għoli jista' jinkludi l-ambitu korrispondenti tal-qari, iżda ambiti tal-qari qatt ma jagħtu kitba. L-ambiti disponibbli jiddependu fuq il-permessi tal-amministratur u l-funzjonijiet attivati tal-ispazju tax-xogħol.

L-aċċess API nnifsu huwa inkluż f'kull pjan u huwa kkontrollat mis-setting adminApiEnabled tal-host. Id-drittijiet addizzjonali għall-funzjonijiet ta' hawn fuq xorta japplikaw; l-aċċess API ma jagħtix funzjonijiet barra mill-pjan tal-ispazju tax-xogħol.

Referenza tal-endpoints

It-tabelli hawn taħt jelenkaw is-87 rotta amministrattiva tal-ispazju tax-xogħol. Ambiti multipli f'ċellola huma kollha meħtieġa.

Spazju tax-Xogħol

Oqsma tal-patch tal-ispazju tax-xogħol: name, email, website, addressLine1, addressLine2, postalCode, city, state u countryId. Mill-inqas qasam wieħed huwa meħtieġ. Strings vojta li jistgħu jkunu null jiġu normalizzati għal null.

Siti u ġestjoni tal-qawwa

Il-bodies tal-ħolqien u l-patches tas-siti jużaw:

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

Il-ġeokodifikazzjoni tas-siti taċċetta oqsma tal-query fakultattivi street, city, state, country u countryCode b'żewġ ittri flimkien mal-header tat-talba Accept-Language. It-tfittxija magħquda tat-triq/belt/stat irid ikun fiha mill-inqas żewġ karattri. Ir-risponsi fihom biss placeId, displayName, latitude u longitude; il-kredenzjali tal-fornitur u metadata speċifika għall-fornitur ma jintwerewx. Is-server japplika l-kju kondiviż tal-fornitur ta' talba waħda kull sekonda, timeout ta' tmien sekondi, cache limitata ta' 24 siegħa u limiti globali tar-rata tat-tokens tal-ispazju tax-xogħol.

Il-ġestjoni tal-qawwa taċċetta { "pools": [...] }. Pool għandu id, name, limit, meterSources fakultattiv u children rikorsiv. Element child ta' ċarġer għandu chargepointId u priority. L-API tillimita d-daqs tas-siġra u n-numru tal-miters u twettaq tneħħija/validazzjoni mill-ġdid OCPP f'żewġ fażijiet meta tissostitwixxi stat installat. Bidla rrifjutata, li tiskadi jew b'kunflitt konkorrenti tirritorna 409 POWER_MANAGEMENT_CONFLICT filwaqt li żżomm il-konfigurazzjoni preċedenti.

Ċarġers

Il-parametri tal-query tal-logs taċ-ċarġer huma cursor, limit (predefinit 50, massimu 200), from, to, action, direction u levelId. Il-parametri tas-sessjonijiet huma page, limit (predefinit 25, massimu 100), from, to u customerId (ID pożittiv jew unknown). L-istorja tal-iskeda komposta tuża cursor, limit (predefinit 20, massimu 50) u connectorId fakultattiv.

Rapporti

Il-filtri tad-data tar-rapport u tal-esportazzjoni huma from, to, siteId, chargerId, userId, anonymous u active. from/to huma predefiniti għall-aħħar perjodu ta' 90 jum u ma jistgħux ikopru aktar minn 90 jum. userId ma jistax jingħaqad ma' anonymous=true.

• Paġinazzjoni tad-data: cursor opak, limit=50 predefinit, massimu 100.
• Kejl: transactionLogId meħtieġ, cursor opak, limit=500 predefinit, massimu 1,000.
• Esportazzjoni: format=csv|pdf, csv predefinit, limitu assolut ta' 2,000 ringiela.
• Ir-risponsi tal-esportazzjoni jużaw Content-Disposition: attachment, Cache-Control: private, no-store u X-Content-Type-Options: nosniff.

Body tal-iskeda:

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

sendDay huwa 1–28 u sendTime jiġi interpretat f'UTC. L-iskedatur jirkupra minuta skedata mitlufa matul ix-xahar attwali tat-twassil. Builds li jfallu qabel il-konsenja jerġgħu jippruvaw wara 5 u 10 minuti, claim building interrott jista' jerġa' jittieħed wara 30 minuta, u t-twassil awtomatiku jieqaf wara tliet tentattivi. L-iskedatur jaħżen indeterminate immedjatament qabel il-konsenja lil SMTP; kemm indeterminate kif ukoll l-istatus antik sending huma finali għax prova awtomatika oħra ta' xi wieħed minnhom tista' tibgħat attachment duplikat. L-operaturi jridu jirrikonċiljaw dawk l-eżiti manwalment qabel ibiddlu l-istat tal-iskeda. Kull tick jagħżel massimu ta' għaxar skedi, jieqaf jibda xogħol wara baġit ta' 45 sekonda u juża timeouts SMTP limitati. Il-job huwa diżattivat b'mod predefinit u jrid jiġi attivat espliċitament wara validazzjoni SMTP u tal-kapaċità. L-iskeda tal-API tappartjeni lill-ispazju tax-xogħol minflok tuża l-identità tal-bniedem li ħoloq it-token.

Tariffi

Body ta' tariffa fih name, eżattament wieħed minn currencyId, currencyCode jew currency, biddingZoneId fakultattiv u tax. Body ta' assenjazzjoni huwa:

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

Meta tinħoloq assenjazzjoni, it-tariffa tapplika għall-konnetturi fiżiċi kollha jekk connectorId jitħalla barra jew il-valur tiegħu jiġi ssettjat espliċitament għal 0. L-aġġornamenti tal-assenjazzjonijiet jimmiraw assenjazzjoni waħda maħżuna u għalhekk jeħtieġu connectorId fiżiku pożittiv espliċitu; 0 jiġi rrifjutat.

Komponent fih typeId, seasonId, il-qasam fakultattiv priority, il-qasam meħtieġ price u limiti fakultattivi tal-validità skont ix-xahar, il-jum tal-ġimgħa u s-siegħa.

Profili tal-iċċarġjar

L-oqsma tal-metadata tal-profil huma label, locationId, stackLevel, purposeId, kindId, recurrencyKindId fakultattiv, validFrom, validTo, startSchedule, rateUnitId u minChargingRate fakultattiv. Perjodu tal-iskeda fih startPeriod, limit u numberOfPhases fakultattiv. Body ta' assenjazzjoni fiha profileId u connectorId (predefinit 0).

It-tħassir ta' profili u s-sostituzzjoni tal-ġestjoni tal-qawwa jistgħu jistennew konferma miċ-ċarġer. Rifjut, timeout jew bidla konkorrenti tal-istat jirritornaw kunflitt u jżommu l-konfigurazzjoni tad-database minflok jippretendu li ċ-ċarġer ġie kklerjat.

Utenti, stediniet, RFID, aċċess u limiti

Il-paġinazzjoni tal-vetturi u l-paġinazzjoni tal-utenti status=members jużaw cursor numeriku pożittiv. Paġni tal-istediniet jużaw cursor opak i2.*, filwaqt li status=all juża cursor kompost opak a2.* wara l-ewwel paġna (cursor numeriku jibqa' validu biss bħala kontinwazzjoni tal-fluss tal-membri antik). It-tfittxija tal-utenti tiġi pprovduta fil-header tat-talba X-Admin-User-Search sabiex indirizzi tal-email ma jitqiegħdux f'URLs jew logs tal-aċċess. limit huwa predefinit għal 50 u limitat għal 100; il-lista tal-utenti tappoġġja status=all|members|invitations. Qis il-cursors kollha rritornati bħala opaki u rritornahom mingħajr tibdil.

Il-ħolqien dirett ta' utent ma joħloqx password, identità tal-login jew sessjoni. Jorbot biss klijent diġà reġistrat. Uża l-endpoint tal-istedina għal email mhux magħrufa. L-utent tas-sistema Tagless protett ma jistax jinbidel permezz ta' dawn ir-rotot.

Eżempji

Issettja valuri fis-shell tiegħek mingħajr ma tipprintja t-token:

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

Elenka s-siti:

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

Oħloq sit b'mod sigur:

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"

Niżżel rapport CSV għal firxa UTC espliċita:

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"

Esklużjonijiet intenzjonati

L-API tat-tokens tal-ispazju tax-xogħol ma jesponix operazzjonijiet li jeħtieġu prinċipal uman jew awtorità usa'. Dawn jinkludu:

• ħolqien, żvelar, rotazzjoni jew revoka ta' tokens b'token ieħor;
• login, reset tal-password, sessjonijiet, delegazzjoni ta' rwoli jew privileġġi umani u bidliet fis-sjieda tal-ispazju tax-xogħol;
• ħolqien/tħassir tal-ispazju tax-xogħol u sħubija fil-kont tal-fatturazzjoni;
• settings tal-pagamenti, attivazzjoni Stripe, pjanijiet, fatturi u fatturazzjoni tal-host;
• operazzjonijiet ta' appoġġ fil-livell tal-host kollu u webhooks tal-fornitur;
• notifiki għall-bnedmin, redirects tan-navigazzjoni, assi tal-marka u rotot tal-iżvilupp/test.