API pro správu pracovního prostoru

API pro správu pracovního prostoru umožňuje integracím server–server spravovat jeden pracovní prostor EVCharge. Tato dokumentace je určena správcům pracovních prostorů a externím integrátorům API. Používá odvolatelné přístupové tokeny vázané na pracovní prostor a podrobné rozsahy; zákaznické přihlašovací tokeny ani relace prohlížeče nejsou přijímány.

Tento adresář je autoritativní vývojářskou referencí API /v2/admin implementovaného v app-api. Nepopisuje zákaznické/mobilní trasy ani vlastní HTTP trasy portálu správce.

• Požadavky a odpovědi endpointů uvádějí všech 87 registrovaných endpointů, rozsahy, parametry, těla požadavků a úspěšná těla.
• Schémata a příklady definují opakovaně použitelné typy požadavků/odpovědí a reprezentativní těla JSON.
• Kontrakt odpovědí a chyb definuje každé sdílené a specifické neúspěšné tělo.

Základní URL a hranice zdrojů

Všechny cesty jsou relativní k nasazenému originu app-api:

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

ID pracovního prostoru se nepřijímá v URL, řetězci dotazu ani těle požadavku. Každý přístupový token je vázán právě na jeden pracovní prostor a API odvozuje cpoId z ověřené identity tokenu. Pokud vnořená lokalita, nabíječka, uživatel, tarif, profil, přiřazení nebo transakce do tohoto prostoru nepatří, API vrátí stejnou odpověď 404 RESOURCE_NOT_FOUND, která neumožňuje zjišťovat existenci prostředků.

Získání přístupového tokenu

Tokeny vytváří lidský správce pracovního prostoru v jeho nastavení v části Přístup API. Správa tokenů záměrně není dostupná tokenům pracovního prostoru.

• Přístup API je součástí všech balíčků včetně Free. Správce musí mít oprávnění upravovat pracovní prostor.
• Hostitel pracovního prostoru musí povolit Admin API pomocí adminApiEnabled; jinak platný token obdrží z app-api odpověď 404, která neprozrazuje existenci prostředků.
• Správce může udělit pouze rozsahy povolené jeho aktuálními oprávněními a nároky pracovního prostoru.
• Nové tokeny mohou být bez expirace, což je výchozí v nastavení, nebo mít správcem zvolenou platnost 1–365 celých dní. Server vypočítá absolutní konec platnosti. Neomezené tokeny platí do zrušení.
• Pracovní prostor může mít nejvýše 50 aktivních tokenů.
• Přihlašovací údaj v otevřeném textu se zobrazí jednou. Okamžitě jej uložte do správce tajných údajů.
• Název, rozsahy a platnost jsou neměnné. Pro rotaci vytvořte náhradu, nasaďte ji, ověřte a starý token zrušte.
• Odvolání je okamžité; odvolané řádky zůstávají viditelné jako neměnná historie pracovního prostoru se skrytými citlivými údaji. Neexistuje endpoint pro introspekci bearer tokenů ani trvalé smazání.

app-api nemá endpoint, který tyto přihlašovací údaje vydává, obnovuje, vypisuje nebo odvolává. Získání tokenu je proto předpokladem prováděným v lidském portálu správce, nikoli dalším endpointem této reference.

Token nikdy nedávejte do repozitáře, URL, dotazů, cookies, logů, analytiky nebo chybových hlášení.

Ověření identity

V každém požadavku odešlete právě jednu hlavičku ve stylu RFC 6750:

Authorization: Bearer evc_ws_<selector>.<secret>

Přesný neprůhledný přihlašovací údaj je evc_ws_ následovaný 16znakovým kanonickým selektorem base64url, . a 43znakovým kanonickým tajemstvím base64url. Odešlete celý údaj beze změny; znovu jej nekódujte pomocí base64.

API odmítá duplicitní autorizační hlavičky, hodnoty spojené čárkou, jiná schémata, prázdné bearer hodnoty, zákaznické JWT a přihlašovací údaje předané kdekoli mimo tuto hlavičku.

Chybné, neznámé, prošlé, zrušené či jinak neplatné tokeny dostávají stejnou odpověď:

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

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

Služba při každém požadavku ověřuje stav tokenu a aktuální nároky pracovního prostoru. Odebrání nároku tak může vypnout dotčené rozsahy před vypršením tokenu.

Tokeny pracovního prostoru jsou neprůhledné přihlašovací údaje, nikoli JWT. Nemají obnovovací token a neexistuje obnovovací endpoint. Token s omezenou platností přestane ověřovat v absolutním čase expiresAt; token bez vypršení platí do odvolání. Rotace znamená vytvořit náhradní přihlašovací údaj v portálu, nasadit jej klientovi a starý odvolat.

Konvence požadavků

• Pro požadavky s tělem JSON použijte Content-Type: application/json.
• Volitelné hodnoty požadavku X-Request-Id se oříznou a přijmou pouze tehdy, obsahují-li 1–128 znaků z A-Z, a-z, 0-9, ., _, : nebo -; jinak server vygeneruje UUID. Každá odpověď vrací vybranou hodnotu jako X-Request-Id.
• Volitelné X-Error-Format: envelope převádí každou chybovou odpověď JSON na strukturovanou obálku popsanou v Kontraktu odpovědí a chyb. Jakákoli jiná hodnota zachovává výchozí kompatibilní tělo.
• ID v cestách jsou kladná celá čísla. ID přístupových tokenů z portálu jsou desetinné řetězce, protože jde o nezáporné 64bitové hodnoty databáze.
• Datum a čas jsou řetězce RFC 3339 s explicitním posunem, například 2026-08-13T12:30:00Z.
• Úspěšná smazání obvykle vracejí 204 No Content.
• Vytváření obvykle vrací 201 Created.
• Pouze zařazená práce OCPP může vrátit 202 Accepted; nepovažujte to za potvrzení nabíječkou, pokud to odpověď výslovně neříká.
• Ověřené odpovědi používají Cache-Control: no-store. Endpointy QR a exportu vracejí binární těla s explicitními hlavičkami obsahu.
• Povolené originy prohlížeče mohou přes CORS číst X-Request-Id, Idempotency-Replayed, Retry-After a Content-Disposition. Klienti tak propojí požadavky, odhalí idempotentní opakování, dodrží čekání a zachovají názvy souborů zvolené serverem.

Idempotence

Všechny administrační požadavky POST, PUT, PATCH a DELETE musí obsahovat jednu hlavičku Idempotency-Key. Klíče mají 1–255 viditelných znaků a vztahují se k tokenu, metodě a cestě.

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

Opětovné použití dokončeného klíče se stejnou URL a tělem přehraje uloženou odpověď a přidá:

Idempotency-Replayed: true

Opětovné použití klíče s jiným požadavkem vrací 409 IDEMPOTENCY_CONFLICT. Dosud zpracovávaný požadavek vrací 409 IDEMPOTENT_REQUEST_PROCESSING s Retry-After: 5.

Dokončené odpovědi a konečné výsledky se uchovávají pro opakování či odsouhlasení sedm dní od poslední změny. Poté může stejný klíč znamenat nový příkaz. Klienti proto musí používat globálně jedinečné klíče a nesmějí je záměrně recyklovat.

Když vyprší zámek zpracování, spojení skončí po zahájení nebo operace vrátí chybu serveru, API nemůže bezpečně prokázat vnější účinek. Během sedmidenního uchování je klíč konečně neurčitý a vrací 409 IDEMPOTENCY_OUTCOME_UNKNOWN; znovu se nepřebírá ani automaticky nespouští. Před ruční obnovou ověřte účinky a do dokončení odsouhlasení neposílejte stejnou operaci s novým klíčem.

Všechny měnící administrační endpointy včetně POST /reports/send vyžadují Idempotency-Key.

Limity požadavků

Limity platí pro token i jeho prostor. Výchozí hodnoty v repozitáři jsou:

Požadavek omezený limitem vrací 429 Too Many Requests a hlavičku Retry-After. Nasazení mohou tyto hodnoty změnit.

Chyby

Chyby JSON používají stabilní code, podle něhož se má volající větvit:

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

Chyby ověření používají pole polí:

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

Běžné stavy jsou:

Katalog rozsahů

Následující katalog rozsahů se používá při vytváření tokenu správcem. Rozsah zápisu nebo s vysokým dopadem může zahrnovat odpovídající rozsah čtení, ale rozsahy čtení nikdy neudělují zápis. Dostupné rozsahy závisí na oprávněních správce a zapnutých funkcích pracovního prostoru.

Samotný přístup API je v každém balíčku a řídí ho nastavení hostitele adminApiEnabled. Dodatečné funkční nároky výše stále platí; API neuděluje funkce mimo balíček pracovního prostoru.

Reference endpointů

Níže uvedené tabulky uvádějí všech 87 tras pro správu pracovního prostoru. Více rozsahů v buňce znamená, že jsou vyžadovány všechny.

Pracovní prostor

Pole dílčí úpravy pracovního prostoru: name, email, website, addressLine1, addressLine2, postalCode, city, state a countryId. Je vyžadováno alespoň jedno pole. Prázdné řetězce umožňující null se normalizují na null.

Lokality a řízení výkonu

Těla pro vytvoření a dílčí úpravu 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ódování lokalit přijímá volitelná pole dotazu street, city, state, country a dvoupísmenné countryCode a hlavičku požadavku Accept-Language. Hledání kombinující ulici/město/stát musí obsahovat alespoň dva znaky. Odpovědi obsahují pouze placeId, displayName, latitude a longitude; přihlašovací údaje poskytovatele ani jeho specifická metadata se nezpřístupňují. Server používá sdílenou frontu poskytovatele s jedním požadavkem za sekundu, osmivteřinový časový limit, omezenou 24hodinovou mezipaměť a globální limity tokenů pracovních prostorů.

Řízení výkonu přijímá { "pools": [...] }. Skupina má id, name, limit, volitelné meterSources a rekurzivní children. Podřízená nabíječka má chargepointId a priority. API omezuje velikost stromu i počet elektroměrů a při nahrazení nainstalovaného stavu provádí dvoufázové vymazání OCPP a opětovné ověření. Odmítnutá změna, vypršení časového limitu nebo souběžný konflikt vrací 409 POWER_MANAGEMENT_CONFLICT a zachovává předchozí konfiguraci.

Nabíječky

Parametry logů jsou cursor, limit (výchozí 50, maximum 200), from, to, action, direction a levelId. Parametry relací jsou page, limit (výchozí 25, maximum 100), from, to a customerId (kladné ID nebo unknown). Historie složeného rozvrhu používá cursor, limit (výchozí 20, maximum 50) a volitelné connectorId.

Přehledy

Filtry dat přehledu a exportu jsou from, to, siteId, chargerId, userId, anonymous a active. from/to mají výchozí rozsah posledních 90 dní a nesmějí pokrýt více než 90 dní. userId nelze kombinovat s anonymous=true.

• Stránkování dat: neprůhledné cursor, výchozí limit=50, maximum 100.
• Měření: povinné transactionLogId, neprůhledné cursor, výchozí limit=500, maximum 1 000.
• Export: format=csv|pdf, výchozí csv, pevný limit 2 000 řádků.
• Odpovědi exportu používají Content-Disposition: attachment, Cache-Control: private, no-store a X-Content-Type-Options: nosniff.

Tělo rozvrhu:

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

sendDay je 1–28 a sendTime se interpretuje v UTC. Plánovač dohání zmeškanou plánovanou minutu během aktuálního měsíce doručení. Sestavení, která selžou před předáním, se opakují po 5 a 10 minutách, přerušené zpracování building lze převzít po 30 minutách a automatické doručování končí po třech pokusech. Plánovač uloží indeterminate těsně před předáním SMTP; stav indeterminate i starší sending jsou konečné, protože automatické opakování kteréhokoli by mohlo odeslat duplicitní přílohu. Provozovatelé musí tyto výsledky ručně vyřešit před změnou stavu rozvrhu. Každý cyklus vybere nejvýše deset rozvrhů, po 45sekundovém rozpočtu přestane spouštět práci a používá omezené časové limity SMTP. Úloha je ve výchozím stavu vypnutá a musí být výslovně zapnuta po ověření SMTP a kapacity. Rozvrh API vlastní pracovní prostor a nepoužívá identitu člověka, který vytvořil token.

Tarify

Tělo tarifu obsahuje name, právě jedno z currencyId, currencyCode nebo currency, volitelné biddingZoneId a tax. Tělo přiřazení je:

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

Při vytváření přiřazení se tarif použije pro všechny fyzické konektory, pokud je connectorId vynecháno nebo výslovně nastaveno na 0. Aktualizace mění jedno uložené přiřazení a vyžaduje explicitní kladný fyzický connectorId; 0 je odmítnuto.

Komponenta obsahuje typeId, seasonId, price, volitelné priority a volitelné meze platnosti podle měsíce, dne v týdnu a hodiny.

Nabíjecí profily

Pole metadat profilu jsou label, locationId, stackLevel, purposeId, kindId, volitelné recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId a volitelné minChargingRate. Období rozvrhu obsahuje startPeriod, limit a volitelné numberOfPhases. Tělo přiřazení obsahuje profileId a connectorId (výchozí 0).

Mazání profilů a nahrazení řízení výkonu může čekat na potvrzení nabíječky. Odmítnutí, vypršení časového limitu nebo souběžná změna stavu vrátí konflikt a ponechá konfiguraci v databázi místo předstírání, že byla nabíječka vymazána.

Uživatelé, pozvánky, RFID, přístup a limity

Stránkování vozidel a uživatelů status=members používá kladné číselné cursor. Stránky pozvánek používají neprůhledný kurzor i2.*, zatímco status=all po první stránce používá neprůhledný složený kurzor a2.* (číselný kurzor zůstává platný pouze jako pokračování staršího proudu členů). Hledání uživatelů se předává v hlavičce požadavku X-Admin-User-Search, aby se e-maily neobjevovaly v URL ani přístupových lozích. limit má výchozí hodnotu 50 a maximum 100; seznam uživatelů podporuje status=all|members|invitations. Se všemi vrácenými kurzory zacházejte jako s neprůhlednými a vracejte je beze změny.

Přímé vytvoření uživatele nevytváří heslo, přihlašovací identitu ani relaci. Jen připojí registrovaného zákazníka. Pro neznámý e-mail použijte pozvání. Chráněného systémového uživatele Tagless těmito routami měnit nelze.

Příklady

Nastavte hodnoty v shellu bez vypsání tokenu:

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

Vypište lokality:

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

Vytvořte lokalitu bezpečně:

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"

Stáhněte report CSV pro explicitní období 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áměrně vynechané operace

API tokenů pracovního prostoru nezpřístupňuje operace vyžadující lidskou identitu nebo širší pravomoc. Patří sem:

• vytváření, odhalování, rotace nebo odvolávání tokenů jiným tokenem;
• přihlášení, obnovení hesla, relace, delegování lidských rolí či oprávnění a změny vlastnictví pracovního prostoru;
• vytváření/mazání pracovních prostorů a členství ve fakturačním účtu;
• nastavení plateb, registrace Stripe, tarify služby, faktury a účtování hostitele;
• operace podpory pro celého hostitele a webhooky poskytovatelů;
• oznámení lidem, přesměrování navigace, podklady značky a vývojové/testovací trasy.