Заявки и отговори на крайните точки на Admin API на работното пространство

Това е справочникът за заявки/отговори на всяка крайна точка /v2/admin. Удостоверяването, идемпотентността, лимитите на заявки, създаването на токени и значението на обхватите са описани в Admin API на работното пространство. Преизползваемите типове на ниво поле и примерите са в Схеми и примери. Четете всеки ред за крайна точка заедно с Договор за отговори и грешки, който изброява всички възможни общи и специфични неуспешни тела.

Общ договор

Всеки път започва с внедрения произход app-api. Работното пространство се извлича единствено от удостоверения токен; клиентите не трябва да изпращат cpoId. Всички документирани стойности :...Id в пътищата на ресурси са положителни десетични цели числа. Всяка заявка изисква точно една:

Authorization: Bearer <workspace-access-token>

Заявките, показани с JSON тяло, изискват Content-Type: application/json. Всички промени изискват Idempotency-Key (POST, PUT, PATCH и DELETE), включително POST /v2/admin/reports/send; освен ако редът не посочва друго, типът на съдържание при успех е application/json, JSON датите са низове RFC 3339, а числата са JSON числа.

Всяка заявка може да включва X-Request-Id и X-Error-Format: envelope; вижте Договор за отговори и грешки. Тези заглавки не променят схемите за успех.

Използвана по-долу нотация:

• none означава липса на тяло на заявката. DELETE, който документира JSON тяло, все пак го изисква.
• ? означава незадължително свойство или параметър на заявка.
• T | null означава, че свойството присъства и допуска null.
• 204 empty означава липса на тяло на отговора.
• CursorPage<T> означава { items: T[], nextCursor: number|string|null }, освен когато редът изрично посочва обект page или pagination.
• Всички липсващи вложени ресурси, включително идентификатори от друго работно пространство, използват 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, освен ако функцията не документира по-конкретен конфликт.

Общи схеми на заявки

Входни данни за работни пространства и обекти

WorkspacePatch = {
  name?: string(1..100), email?: email|null, website?: string|null,
  addressLine1?: string|null, addressLine2?: string|null,
  postalCode?: string|null, city?: string|null, state?: string|null,
  countryId?: positive integer
} // at least one property

SiteInput = {
  name: string(1..255), description?: string|null = null,
  addressLine1?: string|null = null, addressLine2?: string|null = null,
  postalCode?: string|null = null, city?: string|null = null, state?: string|null = null,
  countryId: positive integer, timezoneId: positive integer,
  latitude?: number[-90,90]|null = null, longitude?: number[-180,180]|null = null
}

Входни данни за управление на мощността

PowerConfigurationInput = { pools: PowerPoolInput[0..200] }
PowerPoolInput = {
  id?: positive integer|null, name?: string(0..255),
  limit: integer[0,100000000], meterSources?: ExternalMeterInput[0..16],
  children?: (PowerPoolInput | ChargerPoolChild)[0..1000]
}
ChargerPoolChild = { chargepointId: positive integer, priority?: integer[-1000000,1000000] }
ExternalMeterInput = {
  id?: positive integer|null, sourceId?: positive integer|null,
  provider?: "perific", name?: string(0..255), externalId: string(1..80),
  measurementMode?: "available_headroom"|"external_non_ev_load_only"|"total_site_load_including_ev",
  valueMode?: "perific_relative"|"perific_direct"|"perific_meter",
  reserveA?: integer[0,100000], offlineSafeA?: integer[0,100000],
  ttlSeconds?: integer[30,86400], enabled?: boolean
}

Входни данни за станции

ChargerCreate = { name: string(1..40), identifier: string(1..40), password?: string(0..40) = "", siteId: positive integer }
ChargerPatch = {
  name?: string(1..40), siteId?: positive integer, invertedRfid?: boolean,
  smartMode?: integer[0,3], automationDisabled?: boolean
} // at least one
ConnectorPatch = {
  connectorFormatId: positive integer, connectorTypeId: positive integer,
  powerTypeId: positive integer, maxVoltage: integer[1,10000],
  maxAmperage: integer[1,10000], maxElectricPower: integer[1,100000000]
}

Входни данни за отчети

ReportFilters = {
  from?: RFC3339, to?: RFC3339, siteId?: positive integer,
  chargerId?: positive integer, userId?: positive integer,
  anonymous?: true|false|1|0, active?: true|false|1|0
}
ReportScheduleInput = {
  enabled: boolean, recipientEmail: email(max 255; may be empty only when disabled), format: "csv"|"pdf",
  sendDay: integer[1,28], sendTime: UTC "HH:mm"
}

Периодите на отчетите трябва да отговарят на from < to и не могат да надвишават 90 дни. Ако липсват, се използват последните 90 дни. userId и anonymous=true са взаимно изключващи се. Планираните експорти наваксват пропусната UTC минута и използват ограничени повторения (изчакване 5/10 минути, 30-минутен наем за блокирала обработка, три опита).

Входни данни за тарифи

TariffInput = {
  name: string(1..64),
  exactly one of currencyId: positive integer, currencyCode: 3 letters, currency: 3 letters,
  biddingZoneId?: positive integer|null, tax?: finite number
}
TariffComponentInput = {
  typeId: positive integer, seasonId: positive integer, priority?: finite number,
  price: finite number, validFromMonth?: finite number, validToMonth?: finite number,
  validFromWeekDay?: finite number, validToWeekDay?: finite number,
  validFromHour?: finite number, validToHour?: finite number
}
TariffAssignmentCreateInput = { tariffId: positive integer, connectorId?: nonnegative integer }
TariffAssignmentUpdateInput = { tariffId: positive integer, connectorId: positive integer }

Входни данни за профили за зареждане

ChargingProfileInput = {
  label: string(1..40), locationId: positive integer, stackLevel: nonnegative number,
  purposeId: positive integer, kindId: positive integer,
  recurrencyKindId?: positive integer|null, validFrom?: RFC3339|null,
  validTo?: RFC3339|null, startSchedule?: RFC3339|null,
  rateUnitId: positive integer, minChargingRate?: nonnegative number|null
}
ChargingProfileCreate = ChargingProfileInput & { schedule?: SchedulePeriod[0..256] }
SchedulePeriod = { startPeriod: nonnegative number, limit: nonnegative number, numberOfPhases?: positive integer|null }
ChargingScheduleInput = { rateUnitId: positive integer, periods: SchedulePeriod[1..256] }
ProfileAssignmentInput = { profileId: positive integer, connectorId?: nonnegative integer }

Входни данни за потребители

UserCreate = { email: email(max 255), name: string(1..255) }
InvitationInput = {
  email: email, name?: string|null, rfid?: string|null,
  allChargers?: boolean, chargerIds?: unique positive integer[0..500]
} // chargerIds must be non-empty unless allChargers=true
AccessInput = { allChargers?: boolean, chargerIds?: unique positive integer[0..500] }
LimitCreate = { limitTypeId: positive integer, energyValue?: nonnegative integer = 0, timeValue?: nonnegative integer = 0 }
LimitPatch = { limitTypeId?: positive integer, energyValue?: nonnegative integer, timeValue?: nonnegative integer }

При създаване на лимит поне едно от energyValue или timeValue трябва да е над нула. Имейлите се изчистват от крайни интервали и се преобразуват в малки букви. RFID UID се приемат само при запис и се маскират в отговорите за четене.

Обобщение на DTO за отговори

Таблиците с крайни точки показват всяка обвивка на отговор на най-горно ниво. Това са основните преизползваеми DTO в тези обвивки:

Справочните обекти се връщат от маршрутите за списък/детайли, за да могат клиентите да открият валидни ID. Третирайте непознатите добавени полета като съвместими с бъдещи версии и разграничавайте само по документирани стабилни полета и кодове за грешка.

Крайни точки за работни пространства

Крайни точки за обекти и управление на мощността

Крайни точки за станции

Крайни точки за отчети

Крайни точки за тарифи

TariffAssignment съдържа id, chargerId, connectorId, безопасно обобщение на тарифа/валута, createdAt и updatedAt.

Крайни точки за профили за зареждане

ProfileAssignment съдържа ID на присвояването, ID на станция/конектор и безопасно обобщение на профила. OCPP резултатите разкриват стабилна информация за заявката/състоянието и никога данни за достъп.

Крайни точки за потребители, RFID, достъп, лимити и локални потребители

Системният потребител Tagless е защитен от тези операции. Неуспешните имейл покани връщат безопасно състояние на доставяне, без да разкриват SMTP подробности; клиентите могат да опитат пак, когато emailRetryReady е true.

Двоични отговори

Две групи крайни точки не връщат JSON при успех:

Грешките от двоичните крайни точки все пак са JSON.