API Riaracháin Spáis Oibre

Ligeann API Riaracháin Spáis Oibre do chomhtháthuithe freastalaí le freastalaí spás oibre EVCharge amháin a riar. Tá an doiciméadú seo do riarthóirí spáis oibre agus do chomhtháthaitheoirí seachtracha API. Úsáideann sé comharthaí rochtana inchúlghairthe atá ceangailte le spás oibre agus scóip mhionsonracha; ní ghlactar le comharthaí logála isteach custaiméirí ná seisiúin bhrabhsálaí.

Is í an eolaire seo an tagairt chanónach d'fhorbróirí don API /v2/admin atá curtha i bhfeidhm ag app-api. Ní dhoiciméadaíonn sí bealaí custaiméirí/móibíleacha ná bealaí HTTP na tairsí riaracháin féin.

• Liostaíonn Iarratais agus freagraí críochphointí gach ceann de na 87 críochphointe cláraithe, scóip, paraiméadair, coirp iarratais agus coirp ratha.
• Sainmhíníonn Scéimeanna agus samplaí na cineálacha in-athúsáidte iarratas/freagra agus ábhar samplach JSON.
• Sainmhíníonn Conradh freagraí agus earráidí gach corp neamh-ratha comhroinnte agus sonrach do chríochphointe.

Bun-URL agus teorainn acmhainní

Tá gach bealach coibhneasta le bunús imscartha app-api:

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

Ní ghlactar le hID an spáis oibre san URL, sa teaghrán ceiste ná i gcorp an iarratais. Tá gach comhartha rochtana ceangailte le spás oibre amháin go díreach, agus díorthaíonn an API cpoId ó phríomhaí an chomhartha fíordheimhnithe. Mura mbaineann láithreán, luchtaire, úsáideoir, taraif, próifíl, sannachán nó idirbheart neadaithe leis an spás oibre sin, tugann an API an freagra céanna 404 RESOURCE_NOT_FOUND nach nochtann acmhainní ar ais.

Comhartha rochtana a fháil

Cruthaíonn riarthóir daonna an spáis oibre comharthaí i Socruithe an Spáis Oibre faoi Rochtain API. Níl bainistiú comharthaí ar fáil do chomharthaí spáis oibre d'aon ghnó.

• Tá rochtain API i ngach plean, Free san áireamh. Ní mór cead eagarthóireachta spáis oibre a bheith ag an riarthóir.
• Ní mór d'óstach an spáis oibre an API Riaracháin a chumasú trí adminApiEnabled; murach sin faigheann comhartha bailí 404 nach nochtann acmhainní ó app-api.
• Ní féidir leis an riarthóir ach scóip atá ceadaithe ag a cheadanna reatha féin agus teidlíochtaí an spáis oibre a dheonú.
• Féadfaidh comharthaí nua a bheith gan éag (réamhshocrú Socruithe an Spáis Oibre) nó saolré lá iomlán ó 1 go 365 lá arna roghnú ag riarthóir a úsáid; ríomhann an freastalaí dátaí éaga absalóideacha teoranta. Fanann comharthaí gan éag bailí go dtí go gcúlghairtear iad.
• Is féidir suas le 50 comhartha gníomhach a bheith ag spás oibre.
• Taispeántar an dintiúr gnáth-théacs uair amháin. Stóráil láithreach i mbainisteoir rún é.
• Ní féidir ainm, scóip ná dáta éaga a athrú. Chun rothlú a dhéanamh, cruthaigh ionadaí, imscar é, deimhnigh é agus cúlghair an seanchomhartha.
• Tá cúlghairm láithreach; fanann rónna cúlghairthe le feiceáil mar stair dho-athraithe fholaithe spáis oibre, agus níl críochphointe iniúchta comhartha Bearer ná scriosta bhuain ann.

Níl críochphointe ag app-api a eisíonn, a athnuann, a liostaíonn ná a chúlghaireann na dintiúir seo. Dá bhrí sin, is réamhriachtanas é an comhartha a fháil tríd an tairseach riaracháin dhaonna, seachas críochphointe eile sa tagairt seo.

Ná cuir an comhartha i rialú leaganacha, URLanna, teaghráin cheiste, fianáin, logaí, anailísíocht ná tuairiscí earráide riamh.

Fíordheimhniú

Seol ceanntásc amháin go díreach de stíl RFC 6750 ar gach iarratas:

Authorization: Bearer evc_ws_<selector>.<secret>

Is é an dintiúr teimhneach cruinn evc_ws_ agus roghnóir canónach base64url 16 charachtar ina dhiaidh, . agus rún canónach base64url 43 charachtar. Seol an dintiúr iomlán focal ar fhocal; ná hionchódaigh in base64 arís é.

Diúltaíonn an API do cheanntásca dúblacha údaraithe, luachanna ceangailte le camóga, scéimeanna eile, luachanna folmha Bearer, JWTanna custaiméirí agus dintiúir a sholáthraítear in áit ar bith seachas an ceanntásc seo.

Faigheann comharthaí míchumtha, anaithnide, imithe in éag, cúlghairthe nó neamhbhailí ar shlí eile an freagra céanna:

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

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

Seiceálann an tseirbhís stádas an chomhartha agus teidlíochtaí reatha an spáis oibre ar gach iarratas. Dá bhrí sin, is féidir le baint teidlíochta scóip lena mbaineann a dhíchumasú sula dtéann an comhartha in éag.

Is dintiúir theimhneacha iad comharthaí spáis oibre, seachas JWTanna. Níl comhartha athnuachana acu agus níl críochphointe athnuachana ann. Stopann comhartha teoranta ag fíordheimhniú ag a expiresAt absalóideach; fanann comhartha gan éag bailí go dtí go gcúlghairtear é. Ciallaíonn rothlú dintiúr ionaid a chruthú sa tairseach, é a imscaradh chuig an gcliant agus an seandintiúr a chúlghairm.

Gnásanna iarratais

• Úsáid Content-Type: application/json d'iarratais le corp JSON.
• Baintear spásanna imeallacha de luachanna roghnacha iarratais X-Request-Id agus ní ghlactar leo ach amháin nuair atá 1–128 carachtar ó A-Z, a-z, 0-9, ., _, : nó - iontu; murach sin gineann an freastalaí UUID. Tugann gach freagra an luach roghnaithe ar ais mar X-Request-Id.
• Tiontaíonn X-Error-Format: envelope roghnach gach freagra earráide JSON go dtí an clúdach struchtúrtha atá doiciméadaithe in Conradh freagraí agus earráidí. Coinníonn aon luach eile an corp comhoiriúnachta réamhshocraithe.
• Is slánuimhreacha dearfacha iad IDanna i bparaiméadair chosáin. Is teaghráin deachúlacha iad IDanna comharthaí rochtana a thugann an tairseach ar ais, mar is luachanna bunachair sonraí 64-giotán gan síniú iad.
• Is teaghráin RFC 3339 le fritháireamh soiléir iad luachanna dáta-ama, mar shampla 2026-08-13T12:30:00Z.
• De ghnáth tugann scriosadh rathúil 204 No Content ar ais.
• De ghnáth, tugann oibríochtaí cruthaithe 201 Created ar ais.
• Féadfaidh obair OCPP nach bhfuil ach curtha sa scuaine 202 Accepted a thabhairt ar ais; ná glac leis gur deimhniú ón luchtaire é sin mura ndeir an freagra go soiléir é.
• Úsáideann freagraí fíordheimhnithe Cache-Control: no-store. Tugann críochphointí QR agus easpórtála tuairiscí coirp dhénártha ar ais le ceanntásca soiléire ábhair.
• Is féidir le bunúis cheadaithe brabhsálaí X-Request-Id, Idempotency-Replayed, Retry-After agus Content-Disposition a léamh trí CORS. Ligeann sé seo do chliaint bhrabhsálaí iarratais a chomhghaolú, athsheinmneacha idempotent a bhrath, amanna athiarrachta a urramú agus ainmneacha comhad íoslódála roghnaithe ag an bhfreastalaí a choinneáil.

Idempotency

Ní mór ceanntásc Idempotency-Key amháin a bheith i ngach iarratas riaracháin POST, PUT, PATCH agus DELETE. Tá 1–255 carachtar infheicthe sna heochracha agus baineann a scóip leis an gcomhartha, modh agus cosán.

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

Déanann athúsáid eochrach críochnaithe leis an URL agus corp comhionann an freagra stóráilte a athsheinm agus cuirtear leis:

Idempotency-Replayed: true

Tugann athúsáid eochrach le hiarratas difriúil 409 IDEMPOTENCY_CONFLICT ar ais. Tugann iarratas atá á phróiseáil fós 409 IDEMPOTENT_REQUEST_PROCESSING le Retry-After: 5 ar ais.

Coinnítear freagraí críochnaithe agus torthaí deiridh le haghaidh athsheinm nó réitigh ar feadh seacht lá tar éis a nuashonraithe dheireanaigh. Tar éis na tréimhse coinneála sin, féadfar an eochair chéanna a chóireáil mar ordú nua, mar sin ní mór do chliaint eochracha atá uathúil go domhanda a úsáid agus gan iad a athúsáid d'aon ghnó.

Má théann léas próiseála in éag, má dhúnann an nasc tar éis don fhorghníomhú tosú nó má thugann an oibríocht earráid freastalaí ar ais, ní féidir leis an API a chruthú go sábháilte ar tharla éifeacht sheachtrach. Le linn na tréimhse coinneála seacht lá, tá staid na heochrach éiginnte go críochnaitheach agus tugann sí 409 IDEMPOTENCY_OUTCOME_UNKNOWN ar ais; ní athéilítear í ná ní fhorghníomhaítear í arís go huathoibríoch. Deimhnigh éifeachtaí na hoibríochta sula ndéanann tú aisghabháil de láimh, agus ná cuir an oibríocht chéanna isteach faoi eochair nua go dtí go mbeidh an réiteach sin críochnaithe.

Tá Idempotency-Key de dhíth ar gach críochphointe riaracháin a athraíonn sonraí, POST /reports/send san áireamh.

Teorainneacha ráta

Cuirtear teorainneacha i bhfeidhm ar an gcomhartha aonair agus ar a spás oibre araon. Seo iad na réamhshocruithe atá sa chód:

Tugann iarratas teorannaithe 429 Too Many Requests agus ceanntásc Retry-After ar ais. Is féidir le himscarthaí na luachanna seo a shárú.

Earráidí

Úsáideann earráidí JSON code cobhsaí nuair is gá don ghlaoiteoir brainseáil:

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

Úsáideann earráidí bailíochtaithe eagair réimse:

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

Seo stádais choitianta:

Catalóg scóipeanna

Úsáidtear an chatalóg scóipeanna seo a leanas nuair a chruthaíonn riarthóir comhartha. Féadfaidh scóip scríofa nó ardtionchair an scóip léite chomhfhreagrach a áireamh, ach ní dheonaíonn scóip léite scríobh riamh. Braitheann na scóip atá ar fáil ar cheadanna an riarthóra agus ar ghnéithe cumasaithe an spáis oibre.

Tá rochtain API féin i ngach plean agus rialaíonn socrú adminApiEnabled an óstaigh í. Tá na teidlíochtaí gné breise thuas i bhfeidhm fós; ní thugann rochtain API gnéithe lasmuigh de phlean an spáis oibre.

Tagairt críochphointí

Liostaíonn na táblaí thíos gach ceann de na 87 bealach riaracháin spáis oibre. Tá gach scóip i gcill le scóip iolracha riachtanach.

Spás Oibre

Réimsí paiste spáis oibre: name, email, website, addressLine1, addressLine2, postalCode, city, state agus countryId. Tá réimse amháin ar a laghad riachtanach. Normalaítear teaghráin fholmha incheadaithe mar null go null.

Láithreáin agus bainistiú cumhachta

Úsáideann coirp cruthaithe agus paistí láithreáin:

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

Glacann geochódú láithreáin le réimsí roghnacha ceiste street, city, state, country agus countryCode dhá litir, chomh maith le ceanntásc iarratais Accept-Language. Ní mór dhá charachtar ar a laghad a bheith sa chuardach comhcheangailte sráide/cathrach/stáit. Níl i bhfreagraí ach placeId, displayName, latitude agus longitude; ní nochtar dintiúir soláthraí ná meiteashonraí a bhaineann go sonrach leis. Cuireann an freastalaí scuaine chomhroinnte soláthraí aon iarratas sa soicind, teorainn ama ocht soicind, taisce theoranta 24 uair agus teorainneacha ráta domhanda comharthaí spáis oibre i bhfeidhm.

Glacann bainistiú cumhachta le { "pools": [...] }. Tá id, name, limit, meterSources roghnach agus children athchúrsach i linn. Tá chargepointId agus priority i leanbh luchtaire. Cuireann an API teorainneacha le líon na nóid sa chrann agus leis na méadair agus déanann sé glanadh/athbhailíochtú OCPP dhá chéim nuair a athsholáthraítear staid suiteáilte. Tugann athrú diúltaithe, imithe thar am nó a raibh coimhlint chomhthráthach ann 409 POWER_MANAGEMENT_CONFLICT ar ais agus coinnítear an chumraíocht roimhe sin.

Luchtairí

Is iad paraiméadair cheiste logaí luchtaire cursor, limit (réamhshocrú 50, uasmhéid 200), from, to, action, direction agus levelId. Is iad paraiméadair seisiún page, limit (réamhshocrú 25, uasmhéid 100), from, to agus customerId (ID dearfach nó unknown). Úsáideann stair sceidil ilchodaigh cursor, limit (réamhshocrú 20, uasmhéid 50) agus connectorId roghnach.

Tuairiscí

Is iad scagairí sonraí tuairisce agus easpórtála from, to, siteId, chargerId, userId, anonymous agus active. Tá from/to réamhshocraithe don tréimhse 90 lá is déanaí agus ní féidir leo níos mó ná 90 lá a chlúdach. Ní féidir userId a chomhcheangal le anonymous=true.

• Leathanachú sonraí: cursor teimhneach, réamhshocrú limit=50, uasmhéid 100.
• Tomhais: transactionLogId riachtanach, cursor teimhneach, réamhshocrú limit=500, uasmhéid 1,000.
• Easpórtáil: format=csv|pdf, réamhshocrú csv, teorainn chrua 2,000 ró.
• Úsáideann freagraí easpórtála Content-Disposition: attachment, Cache-Control: private, no-store agus X-Content-Type-Options: nosniff.

Corp sceidil:

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

Tá sendDay idir 1 agus 28 agus léirmhínítear sendTime in UTC. Déanann an sceidealóir cúiteamh as nóiméad sceidealaithe caillte le linn na míosa seachadta reatha. Déantar iarrachtaí eile ar thógálacha ar theip orthu roimh aistriú tar éis 5 agus 10 nóiméad, is féidir éileamh building a briseadh a athéileamh tar éis 30 nóiméad, agus stopann seachadadh uathoibríoch tar éis trí iarracht. Buanann an sceidealóir indeterminate díreach roimh aistriú chuig SMTP; tá indeterminate agus an stádas oidhreachta sending deiridh araon, mar d'fhéadfadh athiarracht uathoibríoch ar cheachtar acu iatán dúblach a sheoladh. Ní mór d'oibreoirí na torthaí sin a réiteach de láimh sula n-athraíonn siad staid an sceidil. Roghnaíonn gach tic deich sceideal ar a mhéad, stopann sé ag tosú oibre tar éis buiséad 45 soicind agus úsáideann sé teorainneacha ama teoranta SMTP. Tá an jab díchumasaithe de réir réamhshocraithe agus ní mór é a chumasú go sainráite tar éis SMTP agus acmhainn a bhailíochtú. Is leis an spás oibre an sceideal API seachas aitheantas an duine a chruthaigh an comhartha a úsáid.

Taraifí

Tá name, ceann amháin go díreach de currencyId, currencyCode nó currency, biddingZoneId roghnach agus tax i gcorp taraife. Seo corp sannacháin:

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

Agus sannachán á chruthú, cuirtear an taraif i bhfeidhm ar gach nascóir fisiciúil má fhágtar connectorId ar lár nó má shocraítear a luach go sainráite mar 0. Díríonn nuashonruithe sannacháin ar shannachán buanaithe amháin agus dá bhrí sin tá connectorId fisiciúil dearfach sonraithe de dhíth; diúltaítear do 0.

Tá typeId, seasonId, an réimse roghnach priority, an réimse riachtanach price agus teorainneacha bailíochta roghnacha míosa, lae seachtaine agus uaire i gcomhpháirt.

Próifílí luchtaithe

Is iad réimsí meiteashonraí próifíle label, locationId, stackLevel, purposeId, kindId, recurrencyKindId roghnach, validFrom, validTo, startSchedule, rateUnitId agus minChargingRate roghnach. Tá startPeriod, limit agus numberOfPhases roghnach i dtréimhse sceidil. Tá profileId agus connectorId (réamhshocrú 0) i gcorp sannacháin.

Féadfaidh scriosadh próifílí agus athsholáthar bainistithe cumhachta fanacht ar admháil ón luchtaire. Tugann diúltú, teorainn ama nó athrú comhthráthach staide coinbhleacht ar ais agus coinnítear cumraíocht an bhunachair sonraí seachas ligean air gur glanadh an luchtaire.

Úsáideoirí, cuirí, RFID, rochtain agus teorainneacha

Úsáideann leathanachú feithiclí agus leathanachú úsáideora status=members cursor uimhriúil dearfach. Úsáideann leathanaigh cuirí cúrsóir teimhneach i2.*, agus úsáideann status=all cúrsóir ilchodach teimhneach a2.* tar éis an chéad leathanaigh (ní fhanann cúrsóir uimhriúil bailí ach mar leanúint srutha ball oidhreachta). Soláthraítear cuardach úsáideora sa cheanntásc iarratais X-Admin-User-Search ionas nach gcuirtear seoltaí ríomhphoist in URLanna ná logaí rochtana. Tá limit réamhshocraithe go 50 agus teoranta go 100; tacaíonn liostú úsáideoirí le status=all|members|invitations. Caith le gach cúrsóir a thugtar ar ais mar theimhneach agus tabhair ar ais gan athrú iad.

Ní chruthaíonn cruthú díreach úsáideora pasfhocal, aitheantas logála isteach ná seisiún. Ní cheanglaíonn sé ach custaiméir atá cláraithe cheana. Úsáid an críochphointe cuireadh do ríomhphost anaithnid. Ní féidir an t-úsáideoir córais cosanta Tagless a athrú trí na bealaí seo.

Samplaí

Socraigh luachanna i do bhlaosc gan an comhartha a phriontáil:

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

Liostaigh láithreáin:

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

Cruthaigh láithreán go sábháilte:

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"

Íoslódáil tuairisc CSV do raon UTC sonraithe:

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"

Eisiaimh d'aon ghnó

Ní nochtann API comharthaí spáis oibre oibríochtaí a éilíonn príomhaí daonna nó údarás níos leithne. Áirítear leo:

• comharthaí a chruthú, a nochtadh, a rothlú nó a chúlghairm le comhartha eile;
• logáil isteach, athshocrú pasfhocail, seisiúin, tarmligean róil nó pribhléide daonna agus athruithe úinéireachta spáis oibre;
• cruthú/scriosadh spáis oibre agus ballraíocht cuntais billeála;
• socruithe íocaíochta, clárú Stripe, pleananna, sonraisc agus billeáil óstaigh;
• oibríochtaí tacaíochta ar fud an óstaigh agus webhooks soláthraí;
• fógraí daonna, atreoruithe nascleanúna, sócmhainní brandála agus bealaí forbartha/tástála.