Admin API на работното пространство

Admin API на работното пространство позволява на интеграции сървър–сървър да управляват едно EVCharge работно пространство. Документацията е за администратори на работни пространства и външни API интегратори. Използва отнемаеми токени за достъп, обвързани с работно пространство, и подробни обхвати; клиентски токени за вход и сесии на браузъра не се приемат.

Тази директория е каноничният справочник за разработчици за API /v2/admin, реализиран от app-api. Не документира клиентски/мобилни маршрути или собствените HTTP маршрути на административния портал.

• Заявки и отговори на крайните точки изброява всички 87 регистрирани крайни точки, обхвати, параметри, тела на заявки и успешни тела.
• Схеми и примери определя преизползваемите типове заявки/отговори и представителни JSON тела.
• Договор за отговори и грешки определя всяко общо и специфично неуспешно тяло.

Базов URL и граници на ресурсите

Всички маршрути са относителни спрямо внедрения произход app-api:

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

ID на работното пространство не се приема в URL, параметрите на заявката или тялото. Всеки токен за достъп е обвързан с точно едно работно пространство и API извежда cpoId от удостоверената идентичност на токена. Ако вложен обект, станция, потребител, тарифа, профил, присвояване или транзакция не принадлежи на това пространство, API връща същия отговор 404 RESOURCE_NOT_FOUND, който не разкрива съществуването на ресурси.

Получаване на токен за достъп

Администратор на работното пространство създава токени в настройките му, в раздел API достъп. Управлението на токени умишлено не е достъпно чрез токени на работното пространство.

• API достъпът е включен във всеки план, включително Free. Администраторът трябва да има право за редактиране на работното пространство.
• Хостът на работното пространство трябва да включи Admin API чрез adminApiEnabled; иначе валиден токен получава от app-api отговор 404, който не разкрива съществуването на ресурси.
• Администраторът може да дава само обхвати, разрешени от собствените му текущи права и правата на работното пространство.
• Новите токени могат да са без срок (по подразбиране в настройките на работното пространство) или с избрана от администратора валидност от 1 до 365 цели дни; сървърът изчислява крайните абсолютни срокове. Токените без срок остават валидни до отнемане.
• Работното пространство може да има най-много 50 активни токена.
• Идентификационните данни в открит вид се показват веднъж. Незабавно ги запазете в мениджър за тайни.
• Името, обхватите и срокът са неизменни. За ротация създайте заместител, внедрете го, проверете го и отнемете стария токен.
• Отнемането е незабавно; отнетите редове остават видими като неизменна история на работното пространство със скрити чувствителни данни. Няма крайна точка за проверка на bearer токен или окончателно изтриване.

app-api няма крайна точка за издаване, обновяване, изброяване или отнемане на тези идентификационни данни. Затова получаването на токен е предварително условие, изпълнявано чрез административния портал от човек, а не друга крайна точка в този справочник.

Никога не поставяйте токена в хранилището за код, URL, параметри на заявки, бисквитки, логове, анализи или отчети за грешки.

Удостоверяване

Изпращайте точно една заглавка в стил RFC 6750 с всяка заявка:

Authorization: Bearer evc_ws_<selector>.<secret>

Точният непрозрачен идентификационен низ е evc_ws_, следван от 16-знаков каноничен base64url селектор, . и 43-знакова канонична base64url тайна. Изпратете целия низ без промяна; не го кодирайте повторно с base64.

API отхвърля дублирани заглавки за оторизация, стойности, свързани със запетая, други схеми, празни bearer стойности, клиентски JWT и данни за достъп, подадени извън тази заглавка.

Неправилно оформени, непознати, изтекли, отнети или иначе невалидни токени получават един и същ отговор:

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

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

Услугата проверява състоянието на токена и текущите права на работното пространство при всяка заявка. Затова отнемането на право може да изключи засегнатите обхвати, преди токенът да изтече.

Токените на работно пространство са непрозрачни идентификационни данни, а не JWT. Нямат токен за обновяване и няма крайна точка за обновяване. Токен със срок престава да удостоверява в абсолютния си момент expiresAt; токен без срок остава валиден до отнемане. Ротацията означава създаване на заместител в портала, внедряване при клиента и отнемане на стария.

Конвенции за заявки

• Използвайте Content-Type: application/json за заявки с JSON тяло.
• Незадължителните стойности X-Request-Id на заявката се изчистват от крайни интервали и се приемат само ако съдържат 1–128 знака от A-Z, a-z, 0-9, ., _, : или -; иначе сървърът генерира UUID. Всеки отговор връща избраната стойност като X-Request-Id.
• Незадължителното X-Error-Format: envelope преобразува всеки JSON отговор за грешка в структурираната обвивка, описана в Договор за отговори и грешки. Всяка друга стойност запазва стандартното съвместимо тяло.
• ID в параметрите на пътя са положителни цели числа. ID на токени за достъп, върнати от портала, са десетични низове, защото са 64-битови беззнакови стойности в базата данни.
• Стойностите за дата и час са низове по RFC 3339 с изрично часово отместване, например 2026-08-13T12:30:00Z.
• Успешните изтривания обикновено връщат 204 No Content.
• Операциите за създаване обикновено връщат 201 Created.
• OCPP операция, която само е поставена на опашка, може да върне 202 Accepted; не го приемайте за потвърждение от станцията, освен ако отговорът изрично го казва.
• Удостоверените отговори използват Cache-Control: no-store. Крайните точки за QR и експорт на отчети връщат двоични тела с изрични заглавки за съдържанието.
• Разрешените произходи на браузъра могат да четат X-Request-Id, Idempotency-Replayed, Retry-After и Content-Disposition чрез CORS. Това позволява на браузърните клиенти да свързват заявки, да откриват идемпотентни повторения, да спазват времето за повторен опит и да запазват избраните от сървъра имена на файлове за изтегляне.

Идемпотентност

Всички административни заявки POST, PUT, PATCH и DELETE трябва да включват една заглавка Idempotency-Key. Ключовете съдържат 1–255 видими знака и важат за съответните токен, метод и път.

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

Повторното използване на завършен ключ със същите URL и тяло възпроизвежда запазения отговор и добавя:

Idempotency-Replayed: true

Повторното използване на ключ с различна заявка връща 409 IDEMPOTENCY_CONFLICT. Заявка, която още се обработва, връща 409 IDEMPOTENT_REQUEST_PROCESSING с Retry-After: 5.

Завършените отговори и крайните резултати се пазят за повторение или съгласуване седем дни след последната им актуализация. След този срок същият ключ може да се третира като нова команда, затова клиентите трябва да използват глобално уникални ключове и да не ги използват умишлено повторно.

Ако наемът за обработка изтече, връзката се затвори след началото на изпълнението или операцията върне сървърна грешка, API не може надеждно да установи дали е настъпил външен ефект. През седемдневния срок на съхранение ключът е окончателно с неопределен резултат и връща 409 IDEMPOTENCY_OUTCOME_UNKNOWN; той не се поема отново и не се изпълнява автоматично повторно. Проверете ефектите на операцията преди ръчно възстановяване и не изпращайте същата операция с нов ключ, докато съгласуването не приключи.

Всички административни крайни точки за промени, включително POST /reports/send, изискват Idempotency-Key.

Лимити на заявки

Лимитите се прилагат както към отделния токен, така и към работното му пространство. Зададените стойности по подразбиране са:

Ограничена заявка връща 429 Too Many Requests и заглавка Retry-After. При внедряване тези стойности могат да бъдат променени.

Грешки

JSON грешките използват стабилен code, когато клиентът трябва да разграничава случаи:

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

Грешките при валидация използват масиви за полета:

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

Чести състояния са:

Каталог на обхватите

Следващият каталог на обхвати се използва, когато администратор създава токен. Обхват за запис или с висок ефект може да включва съответния обхват за четене, но обхватите за четене никога не дават запис. Наличните обхвати зависят от правата на администратора и включените функции на работното пространство.

Самият API достъп е включен във всеки план и се управлява чрез настройката adminApiEnabled на хоста. Допълнителните права за функции по-горе продължават да важат; API достъпът не предоставя функции извън плана на работното пространство.

Справочник за крайни точки

Таблиците по-долу изброяват всичките 87 маршрута за администриране на работно пространство. Всички обхвати в една клетка са задължителни.

Работно пространство

Полета за частична промяна на работното пространство: name, email, website, addressLine1, addressLine2, postalCode, city, state и countryId. Необходимо е поне едно поле. Празните низове, допускащи null, се нормализират до null.

Обекти и управление на мощността

Телата за създаване и частична промяна на обект използват:

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

Геокодирането на обекти приема незадължителните полета street, city, state, country и двубуквено countryCode, както и заглавката Accept-Language. Комбинираното търсене улица/град/област трябва да съдържа поне два знака. Отговорите съдържат само placeId, displayName, latitude и longitude; данните за достъп и специфичните метаданни на доставчика не се разкриват. Сървърът прилага споделена опашка с една заявка в секунда към доставчика, осемсекундно изчакване, ограничен 24-часов кеш и глобални лимити на токените на работни пространства.

Управлението на мощността приема { "pools": [...] }. Групата има id, name, limit, незадължително meterSources и рекурсивно children. Подчинена станция има chargepointId и priority. API ограничава дървото и броя електромери и извършва двуфазно OCPP изчистване/повторна проверка при замяна на инсталираното състояние. Отказана промяна, изтекло време или конфликт от паралелна промяна връща 409 POWER_MANAGEMENT_CONFLICT, запазвайки предишната конфигурация.

Зарядни станции

Параметрите за логовете на станцията са cursor, limit (по подразбиране 50, максимум 200), from, to, action, direction и levelId. Параметрите за сесии са page, limit (по подразбиране 25, максимум 100), from, to и customerId (положителен ID или unknown). Историята на съставните графици използва cursor, limit (по подразбиране 20, максимум 50) и незадължителен connectorId.

Отчети

Филтрите за данни и експорт на отчети са from, to, siteId, chargerId, userId, anonymous и active. from/to по подразбиране са последният 90-дневен период и не могат да обхващат повече от 90 дни. userId не може да се комбинира с anonymous=true.

• Страниране на данни: непрозрачен cursor, по подразбиране limit=50, максимум 100.
• Измервания: задължителен transactionLogId, непрозрачен cursor, по подразбиране limit=500, максимум 1000.
• Експорт: format=csv|pdf, по подразбиране csv, твърд лимит 2000 реда.
• Отговорите за експорт използват Content-Disposition: attachment, Cache-Control: private, no-store и X-Content-Type-Options: nosniff.

Тяло на графика:

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

sendDay е 1–28, а sendTime се тълкува по UTC. Планировчикът наваксва пропусната планирана минута в текущия месец на доставка. Неуспешни изграждания преди предаване се опитват отново след 5 и 10 минути, прекъснато заявяване building може да се поеме след 30 минути, а автоматичната доставка спира след три опита. Планировчикът запазва indeterminate непосредствено преди предаване на SMTP; и indeterminate, и старото състояние sending са крайни, защото автоматичното повторение може да изпрати дублиран прикачен файл. Операторите трябва ръчно да съгласуват тези резултати, преди да променят състоянието на графика. Всеки цикъл избира най-много десет графика, спира да започва работа след 45 секунди и използва ограничени SMTP времена за изчакване. Задачата е изключена по подразбиране и трябва да се включи изрично след проверка на SMTP и капацитета. API графикът е собственост на работното пространство, вместо да използва идентичността на човека, създал токена.

Тарифи

Тялото на тарифа съдържа name, точно едно от currencyId, currencyCode или currency, незадължително biddingZoneId и tax. Тялото за присвояване е:

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

При създаване на присвояване тарифата се прилага към всички физически конектори, ако connectorId е пропуснато или изрично зададено на 0. Актуализациите засягат едно запазено присвояване и затова изискват изричен положителен физически connectorId; 0 се отхвърля.

Компонентът съдържа typeId, seasonId, price, незадължително priority и незадължителни граници на валидност по месец, ден от седмицата и час.

Профили за зареждане

Полетата с метаданни на профила са label, locationId, stackLevel, purposeId, kindId, незадължителни recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId и незадължително minChargingRate. Период в графика съдържа startPeriod, limit и незадължително numberOfPhases. Тялото за присвояване съдържа profileId и connectorId (по подразбиране 0).

Изтриването на профили и замяната на управлението на мощността може да изчакват потвърждение от станцията. Отказ, изтекло време или паралелна промяна на състоянието връщат конфликт и запазват конфигурацията в базата, вместо да се твърди погрешно, че станцията е изчистена.

Потребители, покани, RFID, достъп и лимити

Странирането на автомобили и потребители status=members използва положителен числов cursor. Страниците с покани използват непрозрачен курсор i2.*, а status=all използва непрозрачен съставен курсор a2.* след първата страница (числов курсор остава валиден само като продължение на стария поток от членове). Търсенето на потребители се подава в заглавката X-Admin-User-Search, за да не попадат имейли в URL или логове за достъп. limit по подразбиране е 50 и е ограничено до 100; списъкът с потребители поддържа status=all|members|invitations. Третирайте всички върнати курсори като непрозрачни и ги връщайте непроменени.

Директното създаване на потребител не създава парола, идентичност за вход или сесия. То само прикрепя вече регистриран клиент. За непознат имейл използвайте крайната точка за покани. Защитеният системен потребител Tagless не може да се променя чрез тези маршрути.

Примери

Задайте стойности в командната обвивка, без да отпечатвате токена:

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

Изброяване на обекти:

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

Създайте обект безопасно:

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"

Изтеглете CSV отчет за изричен 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"

Умишлени изключения

API с токени на работно пространство не предоставя операции, изискващи човешка идентичност или по-широки правомощия. Те включват:

• създаване, разкриване, ротация или отнемане на токени чрез друг токен;
• вход, възстановяване на парола, сесии, делегиране на човешки роли или привилегии и промени на собствеността на работно пространство;
• създаване/изтриване на работни пространства и членство в разплащателен акаунт;
• настройки за плащане, регистрация в Stripe, планове, фактури и таксуване на хоста;
• операции за поддръжка за целия хост и webhook на доставчици;
• известия за хора, пренасочвания, брандови ресурси и маршрути за разработка/тест.