API administracyjne obszaru roboczego

API administracyjne obszaru roboczego pozwala integracjom serwer–serwer administrować jednym obszarem roboczym EVCharge. Ta dokumentacja jest przeznaczona dla administratorów obszarów roboczych i zewnętrznych integratorów API. Wykorzystuje odwoływalne tokeny dostępu powiązane z obszarem roboczym i szczegółowe zakresy uprawnień; tokeny logowania klientów i sesje przeglądarki nie są przyjmowane.

Ten katalog jest kanoniczną dokumentacją dla programistów API /v2/admin zaimplementowanego przez app-api. Nie opisuje ścieżek klientów/aplikacji mobilnej ani własnych ścieżek HTTP portalu administracyjnego.

• Żądania i odpowiedzi punktów końcowych wymieniają wszystkie 87 zarejestrowanych punktów końcowych, zakresy uprawnień, parametry, treści żądań i treści pomyślnych odpowiedzi.
• Schematy i przykłady definiują wielokrotnie używane typy żądań i odpowiedzi oraz reprezentatywne treści JSON.
• Kontrakt odpowiedzi i błędów definiuje wszystkie wspólne i specyficzne treści odpowiedzi niepowodzenia.

Bazowy URL i granica zasobów

Wszystkie ścieżki są względne wobec adresu źródłowego wdrożonej usługi app-api:

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

Identyfikator obszaru roboczego nie jest przyjmowany w URL, ciągu zapytania ani treści żądania. Każdy token dostępu jest związany z dokładnie jednym obszarem roboczym, a API wyznacza cpoId z uwierzytelnionej tożsamości tokena. Jeśli zagnieżdżona lokalizacja, ładowarka, użytkownik, taryfa, profil, przypisanie lub transakcja nie należy do tego obszaru, API zwraca tę samą odpowiedź 404 RESOURCE_NOT_FOUND, która nie ujawnia istnienia zasobu.

Uzyskiwanie tokena dostępu

Administrator obszaru roboczego tworzy tokeny w Ustawieniach obszaru roboczego, w sekcji Dostęp do API. Zarządzanie tokenami celowo nie jest udostępniane tokenom obszaru roboczego.

• Dostęp do API jest zawarty w każdym planie, także Free. Administrator musi mieć uprawnienie do edycji obszaru roboczego.
• Dostawca obszaru roboczego musi włączyć API administracyjne przez adminApiEnabled; w przeciwnym razie prawidłowy token otrzyma z app-api odpowiedź 404, która nie ujawnia istnienia zasobu.
• Administrator może nadać tylko zakresy dozwolone przez jego własne bieżące uprawnienia i prawa obszaru roboczego do funkcji.
• Nowe tokeny mogą być bezterminowe (domyślne ustawienie w Ustawieniach obszaru roboczego) lub mieć wybrany przez administratora okres ważności od 1 do 365 pełnych dni; serwer oblicza skończony bezwzględny termin wygaśnięcia. Tokeny bezterminowe pozostają ważne do cofnięcia.
• Obszar roboczy może mieć najwyżej 50 aktywnych tokenów.
• Dane uwierzytelniające w jawnym tekście są pokazywane tylko raz. Natychmiast zapisz je w menedżerze sekretów.
• Nazwa, zakresy uprawnień i termin ważności są niezmienne. Aby przeprowadzić rotację, utwórz zamiennik, wdroż go, zweryfikuj i cofnij stary token.
• Cofnięcie jest natychmiastowe; cofnięte rekordy pozostają widoczne jako niezmienna historia obszaru roboczego z ukrytymi danymi wrażliwymi. Nie ma punktu końcowego introspekcji tokena Bearer ani trwałego usuwania.

app-api nie ma punktu końcowego wydającego, odświeżającego, wyświetlającego lub cofającego te dane uwierzytelniające. Uzyskanie tokena jest więc warunkiem wstępnym realizowanym przez człowieka w portalu administracyjnym, a nie innym punktem końcowym w tej dokumentacji.

Nigdy nie umieszczaj tokena w systemie kontroli wersji, adresach URL, ciągach zapytań, plikach cookie, dziennikach, analityce ani raportach błędów.

Uwierzytelnianie

W każdym żądaniu wyślij dokładnie jeden nagłówek w stylu RFC 6750:

Authorization: Bearer evc_ws_<selector>.<secret>

Dokładne nieprzezroczyste dane uwierzytelniające składają się z evc_ws_, po którym następuje 16-znakowy kanoniczny selektor base64url, . i 43-znakowy kanoniczny sekret base64url. Wyślij kompletne dane bez zmian; nie koduj ich ponownie w base64.

API odrzuca powielone nagłówki autoryzacji, wartości połączone przecinkami, inne schematy, puste wartości Bearer, tokeny JWT klientów i dane uwierzytelniające przesłane gdziekolwiek poza tym nagłówkiem.

Niepoprawnie sformatowane, nieznane, wygasłe, cofnięte lub w inny sposób nieprawidłowe tokeny otrzymują tę samą odpowiedź:

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

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

Usługa sprawdza status tokena i bieżące uprawnienia obszaru roboczego przy każdym żądaniu. Usunięcie uprawnienia do funkcji może więc wyłączyć powiązane zakresy przed wygaśnięciem tokena.

Tokeny obszaru roboczego są nieprzezroczystymi danymi uwierzytelniającymi, a nie JWT. Nie mają tokena odświeżania i nie istnieje punkt końcowy odświeżania. Token terminowy przestaje uwierzytelniać w bezwzględnym momencie expiresAt; token bezterminowy pozostaje ważny do cofnięcia. Rotacja oznacza utworzenie zastępczych danych w portalu, wdrożenie ich w kliencie i cofnięcie poprzednich.

Konwencje żądań

• Użyj Content-Type: application/json dla żądań z treścią JSON.
• Z opcjonalnych wartości żądania X-Request-Id usuwane są skrajne spacje. Wartości są przyjmowane tylko wtedy, gdy zawierają 1–128 znaków z A-Z, a-z, 0-9, ., _, : lub -; w przeciwnym razie serwer generuje UUID. Każda odpowiedź zwraca wybraną wartość jako X-Request-Id.
• Opcjonalne X-Error-Format: envelope konwertuje każdą odpowiedź błędu JSON do ustrukturyzowanego opakowania opisanego w sekcji Kontrakt odpowiedzi i błędów. Każda inna wartość zachowuje domyślną treść zapewniającą zgodność.
• Identyfikatory w parametrach ścieżki są dodatnimi liczbami całkowitymi. Identyfikatory tokenów dostępu zwracane przez portal są ciągami dziesiętnymi, ponieważ w bazie są 64-bitowymi wartościami bez znaku.
• Wartości daty i czasu to ciągi RFC 3339 z jawnym przesunięciem strefy czasowej, na przykład 2026-08-13T12:30:00Z.
• Pomyślne usunięcia zwykle zwracają 204 No Content.
• Operacje tworzenia zwykle zwracają 201 Created.
• Operacja OCPP, która została jedynie umieszczona w kolejce, może zwrócić 202 Accepted; nie interpretuj tego jako potwierdzenia ładowarki, chyba że odpowiedź wyraźnie tak stanowi.
• Uwierzytelnione odpowiedzi używają Cache-Control: no-store. Punkty końcowe QR i eksportu raportów zwracają treść binarną z jawnymi nagłówkami zawartości.
• Dozwolone źródła przeglądarki mogą odczytywać X-Request-Id, Idempotency-Replayed, Retry-After i Content-Disposition przez CORS. Pozwala to klientom przeglądarkowym korelować żądania, wykrywać powtórzenia idempotentne, przestrzegać czasu kolejnej próby i zachowywać wybrane przez serwer nazwy pobieranych plików.

Idempotencja

Wszystkie żądania administracyjne POST, PUT, PATCH i DELETE muszą zawierać jeden nagłówek Idempotency-Key. Klucze mają 1–255 widocznych znaków, a ich zakres jest powiązany z tokenem, metodą i ścieżką.

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

Ponowne użycie zakończonego klucza z identycznym URL i treścią odtwarza zapisaną odpowiedź i dodaje:

Idempotency-Replayed: true

Ponowne użycie klucza z innym żądaniem zwraca 409 IDEMPOTENCY_CONFLICT. Nadal przetwarzane żądanie zwraca 409 IDEMPOTENT_REQUEST_PROCESSING wraz z Retry-After: 5.

Zakończone odpowiedzi i wyniki końcowe są przechowywane do powtórzenia lub uzgodnienia przez siedem dni od ostatniej aktualizacji. Po tym okresie ten sam klucz może zostać potraktowany jako nowe polecenie, dlatego klienci muszą używać globalnie unikalnych kluczy i nie mogą celowo używać ich ponownie.

Jeśli wygaśnie rezerwacja przetwarzania, połączenie zostanie zamknięte po rozpoczęciu wykonania lub operacja zwróci błąd serwera, API nie może bezpiecznie ustalić, czy wystąpił skutek zewnętrzny. W siedmiodniowym okresie przechowywania klucz pozostaje ostatecznie nieokreślony i zwraca 409 IDEMPOTENCY_OUTCOME_UNKNOWN; nie jest przejmowany ponownie ani automatycznie wykonywany. Zweryfikuj skutki operacji przed ręcznym odzyskiwaniem i nie przesyłaj tej samej operacji z nowym kluczem, dopóki uzgadnianie nie zostanie zakończone.

Wszystkie administracyjne punkty końcowe zmieniające dane, w tym POST /reports/send, wymagają Idempotency-Key.

Limity częstotliwości żądań

Limity obowiązują zarówno pojedynczy token, jak i jego obszar roboczy. Domyślne wartości zapisane w repozytorium:

Żądanie objęte limitem zwraca 429 Too Many Requests i nagłówek Retry-After. Wdrożenia mogą nadpisywać te wartości.

Błędy

Błędy JSON używają stabilnego code, gdy wywołujący musi wybrać dalszą ścieżkę działania:

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

Błędy walidacji używają tablic pól:

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

Typowe statusy:

Katalog zakresów uprawnień

Poniższy katalog zakresów uprawnień jest używany, gdy administrator tworzy token. Zakres zapisu lub działań o dużym wpływie może implikować odpowiadający mu zakres odczytu, ale zakresy odczytu nigdy nie przyznają prawa zapisu. Dostępne zakresy zależą od uprawnień administratora i funkcji włączonych w obszarze roboczym.

Sam dostęp do API jest zawarty w każdym planie i kontrolowany przez ustawienie adminApiEnabled dostawcy. Dodatkowe uprawnienia do funkcji opisane powyżej nadal obowiązują; dostęp do API nie przyznaje funkcji spoza planu obszaru roboczego.

Dokumentacja punktów końcowych

Poniższe tabele wymieniają wszystkie 87 ścieżek administracyjnych obszaru roboczego. Jeśli w komórce jest wiele zakresów uprawnień, wymagane są wszystkie.

Obszar roboczy

Pola częściowej aktualizacji obszaru roboczego: name, email, website, addressLine1, addressLine2, postalCode, city, state i countryId. Wymagane jest co najmniej jedno pole. Puste ciągi dopuszczające null są normalizowane do null.

Lokalizacje i zarządzanie mocą

Treści tworzenia i częściowej aktualizacji lokalizacji używają:

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

Geokodowanie lokalizacji przyjmuje opcjonalne pola zapytania street, city, state, country i dwuliterowe countryCode oraz nagłówek żądania Accept-Language. Łączne wyszukiwanie ulicy/miasta/regionu musi zawierać co najmniej dwa znaki. Odpowiedzi zawierają tylko placeId, displayName, latitude i longitude; dane uwierzytelniające dostawcy i metadane specyficzne dla dostawcy nie są ujawniane. Serwer stosuje wspólną kolejkę dostawcy z jednym żądaniem na sekundę, limit czasu ośmiu sekund, ograniczoną 24-godzinną pamięć podręczną i globalne limity częstotliwości tokenów obszaru roboczego.

Zarządzanie mocą przyjmuje { "pools": [...] }. Grupa ma id, name, limit, opcjonalne meterSources i rekurencyjne children. Ładowarka podrzędna ma chargepointId i priority. API ogranicza rozmiar drzewa i liczbę liczników oraz przeprowadza dwuetapowe czyszczenie OCPP i ponowną walidację podczas zastępowania zainstalowanego stanu. Odrzucenie zmiany, przekroczenie czasu lub konflikt współbieżnych zmian zwraca 409 POWER_MANAGEMENT_CONFLICT, zachowując poprzednią konfigurację.

Ładowarki

Parametry zapytania dzienników ładowarki to cursor, limit (domyślnie 50, maksymalnie 200), from, to, action, direction i levelId. Parametry sesji to page, limit (domyślnie 25, maksymalnie 100), from, to i customerId (dodatni identyfikator lub unknown). Historia harmonogramu zbiorczego używa cursor, limit (domyślnie 20, maksymalnie 50) i opcjonalnego connectorId.

Raporty

Filtry danych raportu i eksportu to from, to, siteId, chargerId, userId, anonymous i active. from/to domyślnie obejmują ostatnie 90 dni i nie mogą obejmować więcej niż 90 dni. userId nie można łączyć z anonymous=true.

• Stronicowanie danych: nieprzezroczysty cursor, domyślnie limit=50, maksymalnie 100.
• Pomiary: wymagane transactionLogId, nieprzezroczysty cursor, domyślnie limit=500, maksymalnie 1000.
• Eksport: format=csv|pdf, domyślnie csv, nieprzekraczalny limit 2000 wierszy.
• Odpowiedzi eksportu używają Content-Disposition: attachment, Cache-Control: private, no-store i X-Content-Type-Options: nosniff.

Treść harmonogramu:

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

sendDay mieści się w zakresie 1–28, a sendTime jest interpretowane w UTC. Harmonogram nadrabia pominiętą zaplanowaną minutę w bieżącym miesiącu dostarczenia. Nieudane przygotowania przed przekazaniem są ponawiane po 5 i 10 minutach, przerwaną rezerwację building można przejąć po 30 minutach, a automatyczna dostawa kończy się po trzech próbach. Harmonogram zapisuje indeterminate bezpośrednio przed przekazaniem do SMTP; zarówno indeterminate, jak i starszy status sending są końcowe, ponieważ automatyczne ponowienie któregokolwiek mogłoby wysłać duplikat załącznika. Operatorzy muszą ręcznie uzgodnić te wyniki przed zmianą stanu harmonogramu. Każdy cykl wybiera maksymalnie dziesięć harmonogramów, przestaje rozpoczynać pracę po wyczerpaniu budżetu 45 sekund i używa ograniczonych limitów czasu SMTP. Zadanie jest domyślnie wyłączone i musi zostać jawnie włączone po weryfikacji SMTP oraz wydajności. Harmonogram API należy do obszaru roboczego, zamiast pożyczać tożsamość osoby, która utworzyła token.

Taryfy

Treść taryfy zawiera name, dokładnie jedno z currencyId, currencyCode lub currency, opcjonalne biddingZoneId oraz tax. Treść przypisania:

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

Przy tworzeniu przypisania taryfa ma zastosowanie do wszystkich fizycznych złączy, jeśli connectorId zostanie pominięte lub jawnie ustawione na 0. Aktualizacja przypisania dotyczy jednego zapisanego przypisania, dlatego wymaga jawnego dodatniego fizycznego connectorId; 0 jest odrzucane.

Składnik zawiera wymagane typeId, seasonId i price; priority oraz granice ważności według miesiąca, dnia tygodnia i godziny są opcjonalne.

Profile ładowania

Pola metadanych profilu to label, locationId, stackLevel, purposeId, kindId, opcjonalne recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId i opcjonalne minChargingRate. Okres harmonogramu zawiera startPeriod, limit i opcjonalne numberOfPhases. Treść przypisania zawiera profileId i connectorId (domyślnie 0).

Usuwanie profili i zastępowanie zarządzania mocą może czekać na potwierdzenie ładowarki. Odrzucenie, przekroczenie czasu lub współbieżna zmiana stanu zwraca konflikt i zachowuje konfigurację w bazie danych, zamiast pozornie uznawać, że ładowarka została wyczyszczona.

Użytkownicy, zaproszenia, RFID, dostęp i limity

Stronicowanie pojazdów i stronicowanie użytkowników status=members używa dodatniego liczbowego cursor. Strony zaproszeń używają nieprzezroczystego kursora i2.*, a status=all po pierwszej stronie używa nieprzezroczystego kursora złożonego a2.* (kursor liczbowy pozostaje prawidłowy tylko jako kontynuacja starszego strumienia członków). Wyszukiwanie użytkowników jest przesyłane w nagłówku żądania X-Admin-User-Search, aby adresy e-mail nie trafiały do URL ani dzienników dostępu. limit domyślnie wynosi 50 i jest ograniczone do 100; lista użytkowników obsługuje status=all|members|invitations. Wszystkie zwrócone kursory traktuj jako nieprzezroczyste i odsyłaj bez zmian.

Bezpośrednie utworzenie użytkownika nie tworzy hasła, tożsamości logowania ani sesji. Jedynie dołącza już zarejestrowanego klienta. Dla nieznanego adresu e-mail użyj punktu końcowego zaproszeń. Chronionego użytkownika systemowego Tagless nie można zmieniać za pomocą tych ścieżek.

Przykłady

Ustaw wartości w swojej powłoce bez wypisywania tokena:

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

Wyświetl lokalizacje:

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

Bezpiecznie utwórz lokalizację:

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"

Pobierz raport CSV dla jawnie określonego zakresu 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"

Celowo wyłączone możliwości

API tokenów obszaru roboczego nie udostępnia operacji wymagających tożsamości człowieka lub szerszych uprawnień. Obejmują one:

• tworzenie, ujawnianie, rotację lub cofanie tokenów za pomocą innego tokena;
• logowanie, reset hasła, sesje, delegowanie ludzkich ról lub przywilejów i zmiany własności obszaru roboczego;
• tworzenie/usuwanie obszarów roboczych i członkostwo w koncie rozliczeniowym;
• ustawienia płatności, wdrożenie Stripe, plany, faktury i rozliczenia dostawcy;
• operacje pomocy obejmujące całego dostawcę i webhooki usługodawców;
• powiadomienia do ludzi, przekierowania nawigacji, materiały marki i ścieżki programistyczne/testowe.