Munkaterület-adminisztrációs API

A Munkaterület-adminisztrációs API szerverek közötti integrációknak teszi lehetővé egy EVCharge-munkaterület kezelését. Ez a dokumentáció munkaterület-adminisztrátoroknak és külső API-integrátoroknak szól. Visszavonható, munkaterülethez kötött hozzáférési tokeneket és részletes hatóköröket használ; ügyfél-bejelentkezési tokeneket és böngészős munkameneteket nem fogad el.

Ez a könyvtár a(z) app-api által megvalósított /v2/admin API hiteles fejlesztői referenciája. Nem dokumentálja az ügyfél-/mobilos útvonalakat vagy az adminisztrációs portál saját HTTP-útvonalait.

• A Végpontkérések és válaszok mind a 87 regisztrált végpontot, a hatóköröket, paramétereket, kéréstörzseket és sikertörzseket felsorolja.
• A Sémák és példák az újrafelhasználható kérés-/választípusokat és reprezentatív JSON-adattörzseket határozza meg.
• A Válasz- és hibaszerződés minden közös és végpontspecifikus sikertelen törzset meghatároz.

Alap-URL és erőforráshatár

Minden útvonal a telepített app-api eredethez viszonyított:

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

A munkaterület-azonosító nem adható meg az URL-ben, a lekérdezési karakterláncban vagy a kéréstörzsben. Minden hozzáférési token pontosan egy munkaterülethez kötött, az API pedig a(z) cpoId értéket a hitelesített token identitásából származtatja. Ha egy beágyazott helyszín, töltő, felhasználó, tarifa, profil, hozzárendelés vagy tranzakció nem ehhez a munkaterülethez tartozik, az API ugyanazt a felderítést megakadályozó 404 RESOURCE_NOT_FOUND választ adja.

Hozzáférési token beszerzése

Emberi munkaterület-adminisztrátor hoz létre tokeneket a Munkaterület beállításai között, az API-hozzáférés résznél. A tokenkezelés szándékosan nem érhető el munkaterület-tokenekkel.

• Az API-hozzáférés minden csomagban, a Free csomagban is benne van. Az adminisztrátornak munkaterület-szerkesztési jogosultsággal kell rendelkeznie.
• A munkaterület gazdájának a(z) adminApiEnabled beállítással kell engedélyeznie az adminisztrációs API-t; különben az érvényes token felderítést megakadályozó 404 választ kap a(z) app-api rétegtől.
• Az adminisztrátor csak a saját aktuális jogosultságai és a munkaterület csomagjogosultságai által engedélyezett hatóköröket adhatja meg.
• Az új tokenek lehetnek lejárat nélküliek (a Munkaterület beállításai alapértéke), vagy az adminisztrátor 1–365 egész napos élettartamot választhat; a szerver véges abszolút lejáratot számol. A lejárat nélküli token visszavonásig érvényes.
• Egy munkaterületen legfeljebb 50 aktív token lehet.
• A hitelesítő adat egyszer jelenik meg olvasható szövegként. Azonnal tárolja titokkezelőben.
• A név, a hatókörök és a lejárat nem módosíthatók. Cseréhez hozzon létre új tokent, telepítse, ellenőrizze, majd vonja vissza a régit.
• A visszavonás azonnali; a visszavont sorok megváltoztathatatlan, kitakart munkaterületi előzményként láthatók maradnak, és nincs Bearer-token-introspekciós vagy végleges törlési végpont.

A(z) app-api nem rendelkezik ezeket a hitelesítő adatokat kiadó, frissítő, listázó vagy visszavonó végponttal. A token beszerzése ezért az emberi adminisztrációs portálon teljesítendő előfeltétel, nem e referencia másik végpontja.

Soha ne tegye a tokent verziókezelőbe, URL-be, lekérdezési karakterláncba, sütibe, naplóba, analitikába vagy hibajelentésbe.

Hitelesítés

Minden kérésben pontosan egy RFC 6750 szerinti fejlécet küldjön:

Authorization: Bearer evc_ws_<selector>.<secret>

A pontos átlátszatlan hitelesítő adat evc_ws_, majd egy 16 karakteres kanonikus base64url-választó, ., végül egy 43 karakteres kanonikus base64url-titok. A teljes hitelesítő adatot változtatás nélkül küldje; ne kódolja újra base64 formátumba.

Az API elutasítja az ismételt hitelesítési fejléceket, vesszővel összekapcsolt értékeket, más sémákat, üres bearer értékeket, ügyfél-JWT-ket és a fejlécen kívül bárhol máshol megadott hitelesítő adatokat.

A hibás formátumú, ismeretlen, lejárt, visszavont vagy más okból érvénytelen tokenek ugyanazt a választ kapják:

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

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

A szolgáltatás minden kérésnél ellenőrzi a token állapotát és a munkaterület aktuális csomagjogosultságait. Ezért egy jogosultság eltávolítása a token lejárta előtt letilthatja az érintett hatóköröket.

A munkaterület-tokenek átlátszatlan hitelesítő adatok, nem JWT-k. Nincs frissítési tokenjük és nincs frissítési végpont. A véges token az abszolút expiresAt időpontban már nem hitelesít; a lejárat nélküli token visszavonásig érvényes. A csere új hitelesítő adat létrehozását jelenti a portálon, majd annak kliensre telepítését és a régi visszavonását.

Kérési konvenciók

• JSON-törzsű kérésekhez használjon Content-Type: application/json fejlécet.
• Az opcionális X-Request-Id kérésértékek szélső szóközeit eltávolítja a rendszer, és csak 1–128, a(z) A-Z, a-z, 0-9, ., _, : vagy - készletbe tartozó karakter esetén fogadja el őket; máskülönben a szerver UUID-t generál. Minden válasz a(z) X-Request-Id fejlécben adja vissza a kiválasztott értéket.
• Az opcionális X-Error-Format: envelope minden JSON-hibaválaszt a Válasz- és hibaszerződésben dokumentált strukturált burkolóvá alakít. Bármely más érték megtartja az alapértelmezett kompatibilitási törzset.
• Az útvonalparaméterekben szereplő azonosítók pozitív egészek. A portál által visszaadott hozzáférésitoken-azonosítók decimális karakterláncok, mert előjel nélküli 64 bites adatbázisértékek.
• A dátum-idő értékek egyértelmű eltolást tartalmazó RFC 3339 karakterláncok, például 2026-08-13T12:30:00Z.
• A sikeres törlések általában 204 No Content választ adnak.
• A létrehozási műveletek általában 201 Created választ adnak.
• A csak várólistára helyezett OCPP-munka 202 Accepted választ adhat; ezt ne tekintse a töltő visszaigazolásának, kivéve ha a válasz ezt kifejezetten jelzi.
• A hitelesített válaszok Cache-Control: no-store értéket használnak. A QR- és jelentésexport-végpontok bináris törzset adnak egyértelmű tartalomfejlécekkel.
• Az engedélyezett böngészőeredetek CORS-on keresztül olvashatják a(z) X-Request-Id, Idempotency-Replayed, Retry-After és Content-Disposition fejléceket. Ez lehetővé teszi a böngészős klienseknek a kérések összekapcsolását, az idempotens újrajátszások felismerését, az újrapróbálkozási időzítés betartását és a szerver által választott letöltési fájlnevek megtartását.

Idempotencia

Minden POST, PUT, PATCH és DELETE adminisztrációs kérésnek tartalmaznia kell egy Idempotency-Key fejlécet. A kulcsok 1–255 látható karakterből állnak, és a tokenhez, metódushoz és elérési úthoz kötöttek.

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

Egy befejezett kulcs azonos URL-lel és törzzsel történő újrafelhasználása újrajátssza a tárolt választ, és hozzáadja:

Idempotency-Replayed: true

Egy kulcs eltérő kéréssel való újrafelhasználása 409 IDEMPOTENCY_CONFLICT választ ad. A még feldolgozás alatt álló kérés 409 IDEMPOTENT_REQUEST_PROCESSING választ ad Retry-After: 5 értékkel.

A befejezett válaszokat és végleges eredményeket az utolsó frissítésük után hét napig őrizzük meg újrajátszáshoz vagy egyeztetéshez. Ezután ugyanaz a kulcs új parancsként kezelhető, ezért a klienseknek globálisan egyedi kulcsokat kell használniuk, és tilos azokat szándékosan újra felhasználni.

Ha lejár a feldolgozási foglalás, a kapcsolat a végrehajtás kezdete után megszakad, vagy a művelet szerverhibát ad, az API nem tudja biztonságosan megállapítani, történt-e külső hatás. A hétnapos megőrzési időszak alatt a kulcs véglegesen bizonytalan állapotú, és 409 IDEMPOTENCY_OUTCOME_UNKNOWN választ ad; nem vehető újra használatba, és nem hajtódik végre automatikusan. Kézi helyreállítás előtt ellenőrizze a művelet hatásait, és az egyeztetés befejezéséig ne küldje el ugyanazt a műveletet új kulccsal.

Minden adatot módosító adminisztrációs végpont, beleértve a(z) POST /reports/send végpontot is, Idempotency-Key fejlécet igényel.

Sebességkorlátok

A korlátok az egyedi tokenre és annak munkaterületére is vonatkoznak. A kódban rögzített alapértékek:

A korlátozott kérés 429 Too Many Requests választ és Retry-After fejlécet kap. A telepítések felülírhatják ezeket az értékeket.

Hibák

A JSON-hibák stabil code értéket használnak, ha a hívónak programból különbséget kell tennie az esetek között:

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

Az érvényesítési hibák mezőtömböket használnak:

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

Gyakori állapotok:

Hatókörkatalógus

Az alábbi hatókörkatalógust használja a rendszer, amikor az adminisztrátor tokent hoz létre. Egy írási vagy nagy hatású hatókör magában foglalhatja a megfelelő olvasási hatókört, de az olvasási hatókörök soha nem engednek írást. Az elérhető hatókörök az adminisztrátor jogosultságaitól és a munkaterület engedélyezett funkcióitól függnek.

Maga az API-hozzáférés minden csomagban benne van, és a gazda adminApiEnabled beállítása szabályozza. A fenti kiegészítő funkciójogosultságok továbbra is érvényesek; az API-hozzáférés nem ad a munkaterület csomagján kívüli funkciókat.

Végpontreferencia

Az alábbi táblázatok mind a 87 munkaterület-adminisztrációs útvonalat felsorolják. Ha egy cellában több hatókör szerepel, mind kötelező.

Munkaterület

Munkaterület-részfrissítési mezők: name, email, website, addressLine1, addressLine2, postalCode, city, state és countryId. Legalább egy mező kötelező. A null értéket is megengedő üres karakterláncok null értékre normalizálódnak.

Helyszínek és teljesítménykezelés

A helyszínlétrehozási és részfrissítési törzsek ezt használják:

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

A helyszín-geokódolás opcionális street, city, state, country és kétbetűs countryCode lekérdezési mezőket, valamint Accept-Language kérésfejlécet fogad. Az összesített utca-/város-/államkeresésnek legalább két karaktert kell tartalmaznia. A válaszok csak placeId, displayName, latitude és longitude mezőt tartalmaznak; a szolgáltatói hitelesítő adatok és szolgáltatóspecifikus metaadatok nem jelennek meg. A szerver a közös, másodpercenként egy kéréses szolgáltatói várólistát, nyolc másodperces időkorlátot, korlátozott 24 órás gyorsítótárat és globális munkaterület-token-sebességkorlátokat alkalmazza.

A teljesítménykezelés { "pools": [...] } bemenetet fogad. Egy csoport id, name, limit, opcionális meterSources és rekurzív children mezőt tartalmaz. A töltő típusú gyermek chargepointId és priority mezőt tartalmaz. Az API korlátozza a fa és a mérők számát, és a telepített állapot cseréjekor kétfázisú OCPP-törlést/újraérvényesítést végez. Az elutasított, időtúllépéses vagy párhuzamos módosítással ütköző változtatás 409 POWER_MANAGEMENT_CONFLICT választ ad, miközben megtartja az előző konfigurációt.

Töltők

A töltőnapló lekérdezési paraméterei: cursor, limit (alapérték 50, maximum 200), from, to, action, direction és levelId. A töltési paraméterek: page, limit (alapérték 25, maximum 100), from, to és customerId (pozitív azonosító vagy unknown). Az összesített ütemezés előzményei cursor, limit (alapérték 20, maximum 50) és opcionális connectorId értéket használnak.

Jelentések

A jelentésadat- és exportszűrők: from, to, siteId, chargerId, userId, anonymous és active. A(z) from/to alapértelmezése a legutóbbi 90 nap, és nem foghat át 90 napnál többet. A(z) userId nem kombinálható a(z) anonymous=true értékkel.

• Adatlapozás: átlátszatlan cursor, alapérték limit=50, maximum 100.
• Mérések: kötelező transactionLogId, átlátszatlan cursor, alapérték limit=500, maximum 1 000.
• Export: format=csv|pdf, alapérték csv, szigorú korlát 2 000 sor.
• Az exportválaszok Content-Disposition: attachment, Cache-Control: private, no-store és X-Content-Type-Options: nosniff értéket használnak.

Ütemezési törzs:

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

A(z) sendDay értéke 1–28, a(z) sendTime UTC szerint értendő. Az ütemező pótolja az aktuális kézbesítési hónapban elmulasztott ütemezett percet. Az átadás előtti sikertelen előállításokat 5 és 10 perc után újrapróbálja, a megszakadt building foglalás 30 perc után visszavehető, az automatikus kézbesítés pedig három kísérlet után leáll. Az ütemező közvetlenül az SMTP-átadás előtt tárolja a(z) indeterminate állapotot; a(z) indeterminate és a régi sending állapot is végleges, mert bármelyik automatikus újrapróbálása ismételt csatolmányt küldhetne. Az üzemeltetőknek kézzel kell egyeztetniük ezeket az eredményeket az ütemezés állapotának módosítása előtt. Minden futási ütem legfeljebb tíz ütemezést választ ki, 45 másodperc után nem kezd új munkába, és korlátozott SMTP-időtúllépéseket használ. A feladat alapértelmezetten letiltott, és csak az SMTP és kapacitás ellenőrzése után engedélyezhető kifejezetten. Az API-ütemezés a munkaterület tulajdona, nem a tokent létrehozó ember identitását használja.

Tarifák

A tarifatörzs name, a(z) currencyId, currencyCode vagy currency közül pontosan egy, opcionális biddingZoneId és tax mezőt tartalmaz. A hozzárendelési törzs:

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

Hozzárendelés létrehozásakor a tarifa minden fizikai csatlakozóra érvényes, ha a connectorId mező kimarad, vagy az értéke kifejezetten 0-ra van állítva. A hozzárendelés-frissítés egyetlen tárolt hozzárendelést céloz, ezért kifejezett pozitív fizikai connectorId értéket igényel; a 0 érték elutasításra kerül.

Egy összetevő typeId, seasonId, opcionális priority és kötelező price mezőt, valamint opcionális havi, heti napi és óránkénti érvényességi határokat tartalmaz.

Töltési profilok

A profil metaadatmezői: label, locationId, stackLevel, purposeId, kindId, opcionális recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId és opcionális minChargingRate. Egy ütemezési időszak startPeriod, limit és opcionális numberOfPhases mezőt tartalmaz. A hozzárendelési törzs profileId és connectorId (alapérték 0) mezőt tartalmaz.

A profiltörlés és a teljesítménykezelés cseréje várhat a töltő visszaigazolására. Az elutasítás, időtúllépés vagy párhuzamos állapotváltozás ütközést ad, és megtartja az adatbázis-konfigurációt ahelyett, hogy úgy tenne, mintha a töltőről megtörtént volna a törlés.

Felhasználók, meghívások, RFID, hozzáférés és korlátok

A járműlapozás és a(z) status=members felhasználólapozás pozitív numerikus cursor értéket használ. A meghívási oldalak átlátszatlan i2.* kurzort használnak, míg a(z) status=all az első oldal után átlátszatlan összetett a2.* kurzort használ (numerikus kurzor csak régi tagadatfolyam-folytatásként érvényes). A felhasználókeresés a(z) X-Admin-User-Search kérésfejlécben érkezik, így az e-mail-címek nem kerülnek URL-ekbe vagy hozzáférési naplókba. A(z) limit alapértéke 50, maximuma 100; a felhasználólista támogatja a(z) status=all|members|invitations értéket. Minden visszaadott kurzort kezeljen átlátszatlanként, és változtatás nélkül küldjön vissza.

A közvetlen felhasználólétrehozás nem hoz létre jelszót, bejelentkezési identitást vagy munkamenetet. Csak egy már regisztrált ügyfelet kapcsol hozzá. Ismeretlen e-mail-címhez a meghívási végpontot használja. A védett Tagless-rendszerfelhasználó ezeken az útvonalakon nem módosítható.

Példák

Állítsa be az értékeket a parancsértelmezőben a token kiírása nélkül:

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

Helyszínek listázása:

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

Hozzon létre helyszínt biztonságosan:

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"

Töltsön le CSV-jelentést egy kifejezett UTC-tartományra:

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"

Szándékos kizárások

A munkaterület-tokenes API nem tesz elérhetővé emberi identitást vagy szélesebb jogosultságot igénylő műveleteket. Ezek közé tartozik:

• tokenek létrehozása, felfedése, cseréje vagy visszavonása másik tokennel;
• bejelentkezés, jelszó-visszaállítás, munkamenetek, emberi szerep- vagy jogosultságátadás és munkaterület-tulajdonos módosítása;
• munkaterület létrehozása/törlése és számlázásifiók-tagság;
• fizetési beállítások, Stripe-regisztráció, csomagok, számlák és gazdaszintű számlázás;
• gazdaszintű támogatási műveletek és szolgáltatói webhookok;
• emberi értesítések, navigációs átirányítások, márkaelemek és fejlesztési/tesztútvonalak.