Administrátorské API pracovného priestoru

Administrátorské API pracovného priestoru umožňuje integráciám medzi servermi spravovať jeden pracovný priestor EVCharge. Táto dokumentácia je pre správcov pracovných priestorov a externých integrátorov API. Používa odvolateľné prístupové tokeny viazané na pracovný priestor a podrobné rozsahy oprávnení; prihlasovacie tokeny zákazníkov a relácie prehliadača sa neprijímajú.

Tento adresár je kanonickou vývojárskou referenciou API /v2/admin implementovaného v app-api. Nedokumentuje zákaznícke/mobilné trasy ani vlastné HTTP trasy administrátorského portálu.

• Požiadavky a odpovede koncových bodov uvádzajú všetkých 87 registrovaných koncových bodov, rozsahy, parametre, telá požiadaviek a telá úspešných odpovedí.
• Schémy a príklady definujú opakovane použiteľné typy požiadaviek/odpovedí a reprezentatívne telá JSON.
• Kontrakt odpovedí a chýb definuje každé spoločné a špecifické telo neúspešnej odpovede.

Základná URL a hranica zdrojov

Všetky trasy sú relatívne k pôvodu nasadenej služby app-api:

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

ID pracovného priestoru sa neprijíma v URL, reťazci dopytu ani tele požiadavky. Každý prístupový token je viazaný presne na jeden pracovný priestor a API odvodzuje cpoId z autentifikovanej identity tokenu. Ak vnorená lokalita, nabíjačka, používateľ, tarifa, profil, priradenie alebo transakcia nepatrí do tohto pracovného priestoru, API vráti rovnakú odpoveď 404 RESOURCE_NOT_FOUND, ktorá neodhaľuje existenciu zdrojov.

Získanie prístupového tokenu

Správca pracovného priestoru vytvára tokeny v Nastaveniach pracovného priestoru v časti Prístup k API. Správa tokenov zámerne nie je dostupná tokenom pracovného priestoru.

• Prístup k API je súčasťou každého programu vrátane Free. Správca musí mať oprávnenie upravovať pracovný priestor.
• Poskytovateľ pracovného priestoru musí zapnúť administrátorské API cez adminApiEnabled; inak platný token dostane od app-api odpoveď 404, ktorá neodhaľuje existenciu zdrojov.
• Správca môže prideliť iba rozsahy povolené jeho vlastnými aktuálnymi oprávneniami a nárokmi pracovného priestoru.
• Nové tokeny môžu byť bez expirácie (predvolené nastavenie v Nastaveniach pracovného priestoru) alebo môžu mať správcom zvolenú životnosť 1 až 365 celých dní; konečný absolútny čas expirácie vypočíta server. Tokeny bez expirácie zostávajú platné až do odvolania.
• Pracovný priestor môže mať najviac 50 aktívnych tokenov.
• Prihlasovací údaj v otvorenom texte sa zobrazí iba raz. Okamžite ho uložte do správcu tajomstiev.
• Názov, rozsahy a expirácia sú nemenné. Pri rotácii vytvorte náhradu, nasaďte ju, overte ju a odvolajte starý token.
• Odvolanie je okamžité; odvolané záznamy zostávajú viditeľné ako nemenná história pracovného priestoru so skrytými citlivými údajmi. Neexistuje koncový bod na introspekciu tokenu Bearer ani na trvalé odstránenie.

app-api nemá koncový bod, ktorý vydáva, obnovuje, vypisuje alebo odvoláva tieto prihlasovacie údaje. Získanie tokenu je preto predpoklad vykonaný človekom cez administrátorský portál, nie iný koncový bod v tejto referencii.

Nikdy nevkladajte token do správy verzií, URL, reťazcov dopytu, súborov cookie, denníkov, analytiky ani chybových hlásení.

Autentifikácia

V každej požiadavke odošlite presne jednu hlavičku v štýle RFC 6750:

Authorization: Bearer evc_ws_<selector>.<secret>

Presný nepriehľadný prihlasovací údaj tvorí evc_ws_, za ktorým nasleduje 16-znakový kanonický selektor base64url, . a 43-znakové kanonické tajomstvo base64url. Pošlite celý údaj bez zmeny; nekódujte ho znova do base64.

API odmieta duplicitné autorizačné hlavičky, hodnoty spojené čiarkami, iné schémy, prázdne hodnoty Bearer, zákaznícke JWT a prihlasovacie údaje zadané kdekoľvek mimo tejto hlavičky.

Nesprávne formátované, neznáme, expirované, odvolané alebo inak neplatné tokeny dostanú rovnakú odpoveď:

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

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

Služba pri každej požiadavke kontroluje stav tokenu a aktuálne nároky pracovného priestoru. Odobratie nároku tak môže vypnúť dotknuté rozsahy ešte pred expiráciou tokenu.

Tokeny pracovného priestoru sú nepriehľadné prihlasovacie údaje, nie JWT. Nemajú obnovovací token ani koncový bod obnovenia. Token s konečnou platnosťou prestane autentifikovať v absolútnom čase expiresAt; token bez expirácie zostáva platný do odvolania. Rotácia znamená vytvorenie náhradného údaja v portáli, jeho nasadenie do klienta a odvolanie starého údaja.

Konvencie požiadaviek

• Pre požiadavky s telom JSON použite Content-Type: application/json.
• Z voliteľných hodnôt požiadavky X-Request-Id sa odstránia okrajové medzery a prijmú sa iba vtedy, ak obsahujú 1–128 znakov z A-Z, a-z, 0-9, ., _, : alebo -; inak server vygeneruje UUID. Každá odpoveď vráti zvolenú hodnotu ako X-Request-Id.
• Voliteľné X-Error-Format: envelope prevedie každú chybovú odpoveď JSON na štruktúrovanú obálku zdokumentovanú v časti Kontrakt odpovedí a chýb. Každá iná hodnota zachová predvolené telo pre kompatibilitu.
• ID v parametroch cesty sú kladné celé čísla. ID prístupových tokenov vrátené portálom sú desiatkové reťazce, pretože v databáze ide o 64-bitové hodnoty bez znamienka.
• Hodnoty dátumu a času sú reťazce RFC 3339 s výslovným časovým posunom, napríklad 2026-08-13T12:30:00Z.
• Úspešné odstránenia zvyčajne vracajú 204 No Content.
• Operácie vytvorenia zvyčajne vracajú 201 Created.
• Operácia OCPP, ktorá bola iba zaradená do frontu, môže vrátiť 202 Accepted; nepovažujte to za potvrdenie od nabíjačky, pokiaľ to odpoveď výslovne neuvádza.
• Autentifikované odpovede používajú Cache-Control: no-store. Koncové body QR a exportu výkazov vracajú binárne telá s výslovnými hlavičkami obsahu.
• Povolené pôvody prehliadača môžu cez CORS čítať X-Request-Id, Idempotency-Replayed, Retry-After a Content-Disposition. Klienti v prehliadači tak môžu spájať požiadavky, rozpoznávať idempotentné opakovania, dodržiavať čas ďalšieho pokusu a zachovať názvy sťahovaných súborov zvolené serverom.

Idempotencia

Všetky administrátorské požiadavky POST, PUT, PATCH a DELETE musia obsahovať jednu hlavičku Idempotency-Key. Kľúče majú 1–255 viditeľných znakov a ich rozsah je viazaný na token, metódu a cestu.

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

Opätovné použitie dokončeného kľúča s rovnakou URL a telom zopakuje uloženú odpoveď a pridá:

Idempotency-Replayed: true

Opätovné použitie kľúča s inou požiadavkou vráti 409 IDEMPOTENCY_CONFLICT. Stále spracúvaná požiadavka vráti 409 IDEMPOTENT_REQUEST_PROCESSING s Retry-After: 5.

Dokončené odpovede a konečné výsledky sa uchovávajú na opakovanie alebo zosúladenie sedem dní od poslednej aktualizácie. Po tejto lehote sa rovnaký kľúč môže považovať za nový príkaz, preto klienti musia používať globálne jedinečné kľúče a nesmú ich zámerne opätovne používať.

Ak vyprší rezervácia spracovania, spojenie sa uzavrie po začatí vykonávania alebo operácia vráti chybu servera, API nedokáže bezpečne dokázať, či nastal externý účinok. Počas sedemdňového uchovávania je kľúč definitívne neurčitý a vracia 409 IDEMPOTENCY_OUTCOME_UNKNOWN; neprevezme sa znova ani sa automaticky znovu nevykoná. Pred ručným obnovením overte účinky operácie a neodosielajte rovnakú operáciu s novým kľúčom, kým sa zosúladenie nedokončí.

Všetky administrátorské koncové body meniace údaje vrátane POST /reports/send vyžadujú Idempotency-Key.

Limity frekvencie požiadaviek

Limity sa uplatňujú na jednotlivý token aj na jeho pracovný priestor. Predvolené hodnoty uložené v repozitári sú:

Požiadavka, ktorá dosiahla limit, vráti 429 Too Many Requests a hlavičku Retry-After. Jednotlivé nasadenia môžu tieto hodnoty zmeniť.

Chyby

Chyby JSON používajú stabilné code, keď sa volajúci musí rozhodnúť o ďalšom postupe:

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

Validačné chyby používajú polia záznamov:

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

Bežné stavy:

Katalóg rozsahov oprávnení

Nasledujúci katalóg rozsahov sa používa pri vytváraní tokenu správcom. Rozsah zápisu alebo operácií s veľkým dosahom môže zahŕňať zodpovedajúci rozsah čítania, ale rozsahy čítania nikdy neudeľujú zápis. Dostupné rozsahy závisia od oprávnení správcu a povolených funkcií pracovného priestoru.

Samotný prístup k API je súčasťou každého programu a riadi ho nastavenie adminApiEnabled poskytovateľa. Dodatočné nároky na funkcie uvedené vyššie stále platia; prístup k API nesprístupňuje funkcie mimo programu pracovného priestoru.

Referenčný prehľad koncových bodov

Tabuľky nižšie uvádzajú všetkých 87 administrátorských trás pracovného priestoru. Ak bunka obsahuje viac rozsahov, vyžadujú sa všetky.

Pracovný priestor

Polia čiastočnej aktualizácie pracovného priestoru: name, email, website, addressLine1, addressLine2, postalCode, city, state a countryId. Vyžaduje sa aspoň jedno pole. Prázdne reťazce, ktoré môžu byť null, sa normalizujú na null.

Lokality a riadenie výkonu

Telá vytvorenia a čiastočnej aktualizácie lokality používajú:

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

Geokódovanie lokality prijíma voliteľné polia dopytu street, city, state, country a dvojpísmenové countryCode spolu s hlavičkou požiadavky Accept-Language. Kombinované vyhľadávanie ulice/mesta/regiónu musí obsahovať aspoň dva znaky. Odpovede obsahujú iba placeId, displayName, latitude a longitude; prihlasovacie údaje poskytovateľa ani jeho špecifické metadáta sa nezverejňujú. Server používa spoločný front poskytovateľa s jednou požiadavkou za sekundu, osemsekundový časový limit, ohraničenú 24-hodinovú vyrovnávaciu pamäť a globálne limity frekvencie tokenov pracovného priestoru.

Riadenie výkonu prijíma { "pools": [...] }. Skupina má id, name, limit, voliteľné meterSources a rekurzívne children. Podradená nabíjačka má chargepointId a priority. API obmedzuje veľkosť stromu a počet meradiel a pri nahrádzaní nainštalovaného stavu vykonáva dvojfázové vymazanie OCPP a opätovné overenie. Odmietnutá zmena, uplynutie času alebo súbeh zmien vrátia 409 POWER_MANAGEMENT_CONFLICT, pričom sa zachová predchádzajúca konfigurácia.

Nabíjačky

Parametre dopytu pre denníky nabíjačky sú cursor, limit (predvolene 50, najviac 200), from, to, action, direction a levelId. Parametre relácií sú page, limit (predvolene 25, najviac 100), from, to a customerId (kladné ID alebo unknown). História zloženého harmonogramu používa cursor, limit (predvolene 20, najviac 50) a voliteľné connectorId.

Výkazy

Filtre údajov výkazov a exportu sú from, to, siteId, chargerId, userId, anonymous a active. from/to predvolene pokrývajú posledných 90 dní a nesmú presiahnuť 90 dní. userId nemožno kombinovať s anonymous=true.

• Stránkovanie údajov: nepriehľadný cursor, predvolene limit=50, najviac 100.
• Merania: povinné transactionLogId, nepriehľadný cursor, predvolene limit=500, najviac 1 000.
• Export: format=csv|pdf, predvolene csv, pevný limit 2 000 riadkov.
• Odpovede exportu používajú Content-Disposition: attachment, Cache-Control: private, no-store a X-Content-Type-Options: nosniff.

Telo harmonogramu:

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

sendDay je 1–28 a sendTime sa interpretuje v UTC. Plánovač dobieha zmeškanú naplánovanú minútu počas aktuálneho mesiaca doručenia. Neúspešné zostavenia pred odovzdaním sa opakujú po 5 a 10 minútach, prerušenú rezerváciu building možno prevziať po 30 minútach a automatické doručovanie sa zastaví po troch pokusoch. Plánovač uloží indeterminate tesne pred odovzdaním SMTP; indeterminate aj starší stav sending sú konečné, pretože automatické opakovanie ktoréhokoľvek z nich by mohlo odoslať duplicitnú prílohu. Prevádzkovatelia musia tieto výsledky ručne zosúladiť pred zmenou stavu harmonogramu. Každý cyklus vyberie najviac desať harmonogramov, po vyčerpaní 45-sekundového rozpočtu prestane začínať novú prácu a používa ohraničené časové limity SMTP. Úloha je predvolene vypnutá a musí sa výslovne zapnúť po overení SMTP a kapacity. Harmonogram API patrí pracovnému priestoru, nie je naviazaný na identitu človeka, ktorý vytvoril token.

Tarify

Telo tarify obsahuje name, presne jedno z currencyId, currencyCode alebo currency, voliteľné biddingZoneId a tax. Telo priradenia:

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

Pri vytváraní priradenia sa tarifa použije pre všetky fyzické konektory, ak je connectorId vynechané alebo výslovne nastavené na 0. Aktualizácie priradenia cielia na jedno uložené priradenie, a preto vyžadujú výslovne uvedené kladné fyzické connectorId; 0 sa odmietne.

Komponent obsahuje povinné typeId, seasonId a price; priority a hranice platnosti podľa mesiaca, dňa v týždni a hodiny sú voliteľné.

Nabíjacie profily

Polia metadát profilu sú label, locationId, stackLevel, purposeId, kindId, voliteľné recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId a voliteľné minChargingRate. Obdobie harmonogramu obsahuje startPeriod, limit a voliteľné numberOfPhases. Telo priradenia obsahuje profileId a connectorId (predvolene 0).

Odstraňovanie profilov a nahradenie riadenia výkonu môže čakať na potvrdenie nabíjačky. Odmietnutie, uplynutie času alebo súbežná zmena stavu vráti konflikt a zachová konfiguráciu databázy namiesto predstierania, že nabíjačka bola vyčistená.

Používatelia, pozvánky, RFID, prístup a limity

Stránkovanie vozidiel a stránkovanie používateľov status=members používa kladné číselné cursor. Stránky pozvánok používajú nepriehľadný kurzor i2.*, zatiaľ čo status=all po prvej stránke používa nepriehľadný zložený kurzor a2.* (číselný kurzor zostáva platný iba ako pokračovanie staršieho toku členov). Vyhľadávanie používateľov sa posiela v hlavičke požiadavky X-Admin-User-Search, aby sa e-mailové adresy neukladali do URL ani denníkov prístupu. limit je predvolene 50 a najviac 100; zoznam používateľov podporuje status=all|members|invitations. Všetky vrátené kurzory považujte za nepriehľadné a vracajte ich nezmenené.

Priame vytvorenie používateľa nevytvára heslo, prihlasovaciu identitu ani reláciu. Iba pripojí už registrovaného zákazníka. Pre neznámy e-mail použite koncový bod pozvánok. Chráneného systémového používateľa Tagless nemožno cez tieto trasy meniť.

Príklady

Nastavte hodnoty vo svojom shelli bez vypísania tokenu:

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

Zobrazte lokality:

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

Bezpečne vytvorte lokalitu:

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"

Stiahnite výkaz CSV pre výslovne určený rozsah UTC:

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"

Zámerne vylúčené možnosti

API tokenov pracovného priestoru nesprístupňuje operácie vyžadujúce ľudskú identitu alebo širšie oprávnenia. Zahŕňajú:

• vytváranie, odhalenie, rotáciu alebo odvolanie tokenov iným tokenom;
• prihlásenie, obnovenie hesla, relácie, delegovanie ľudských rolí alebo oprávnení a zmeny vlastníctva pracovného priestoru;
• vytváranie/odstraňovanie pracovných priestorov a členstvo vo fakturačnom účte;
• nastavenia platieb, registráciu v Stripe, programy, faktúry a fakturáciu poskytovateľa;
• operácie podpory pre celého poskytovateľa a webhooky poskytovateľov;
• oznámenia ľuďom, navigačné presmerovania, značkové materiály a vývojové/testovacie trasy.