Talbiet u risponsi tal-endpoints tal-API tal-Amministrazzjoni tal-Ispazju tax-Xogħol

Din hija r-referenza tat-talbiet/risponsi għal kull endpoint /v2/admin. L-awtentikazzjoni, l-idempotenza, il-limiti tar-rata, il-ħolqien tat-tokens u s-semantika tal-ambiti huma dokumentati f'API tal-Amministrazzjoni tal-Ispazju tax-Xogħol. Tipi u eżempji fil-livell tal-qasam li jistgħu jerġgħu jintużaw jinsabu f'Skemi u eżempji. Aqra kull ringiela tal-endpoint flimkien ma' Kuntratt tar-risponsi u l-iżbalji, li jelenka l-bodies kollha possibbli tar-risponsi mhux ta' suċċess kondiviżi u speċifiċi għall-endpoint.

Kuntratt komuni

Kull path jibda bl-origin implimentata app-api. L-ispazju tax-xogħol jiġi derivat esklussivament mit-token awtentikat; il-klijenti ma għandhomx jibagħtu cpoId. Il-valuri kollha dokumentati tal-path tar-riżorsi :...Id huma numri sħaħ deċimali pożittivi. Kull talba teħtieġ eżattament wieħed:

Authorization: Bearer <workspace-access-token>

Talbiet murija b'body JSON jeħtieġu Content-Type: application/json. Il-mutazzjonijiet kollha jeħtieġu Idempotency-Key (POST, PUT, PATCH u DELETE), inkluż POST /v2/admin/reports/send; sakemm ringiela ma tgħidx mod ieħor, it-tip ta' kontenut tas-suċċess huwa application/json, id-dati JSON huma strings RFC 3339 u n-numri huma numri JSON.

Kull talba tista' tinkludi X-Request-Id u X-Error-Format: envelope; ara Kuntratt tar-risponsi u l-iżbalji. Dawn il-headers ma jbiddlux l-iskemi tas-suċċess.

Notazzjoni użata hawn taħt:

• none ifisser ebda body tat-talba. DELETE li jiddokumenta body JSON xorta jeħtieġ dik il-body.
• ? jimmarka proprjetà jew parametru tal-query fakultattiv.
• T | null ifisser li l-proprjetà hija preżenti u tista' tkun null.
• 204 empty ifisser ebda body tar-rispons.
• CursorPage<T> ifisser { items: T[], nextCursor: number|string|null }, ħlief fejn ir-ringiela ssemmi oġġett page jew pagination espliċitament.
• Ir-riżorsi nested kollha li ma jinstabux, inklużi IDs minn spazji tax-xogħol oħra, jużaw 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" } sakemm funzjoni ma tiddokumentax kunflitt aktar speċifiku.

Skemi kondiviżi tat-talbiet

Inputs tal-ispazju tax-xogħol u tas-sit

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
}

Input tal-ġestjoni tal-qawwa

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
}

Inputs taċ-ċarġers

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]
}

Inputs tar-rapporti

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

Il-firxiet tar-rapporti jridu jissodisfaw from < to u ma jistgħux jaqbżu 90 jum. Meta jitħallew barra, jintuża l-aħħar perjodu ta' 90 jum. userId u anonymous=true jeskludu lil xulxin. Esportazzjonijiet skedati jirkupraw minuta UTC mitlufa u jużaw tentattivi limitati (stennija ta' 5/10 minuti, lease ta' 30 minuta għal claim qadim, tliet tentattivi).

Inputs tat-tariffi

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 }

Inputs tal-profili tal-iċċarġjar

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 }

Inputs tal-utent

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 }

Mill-inqas wieħed minn energyValue jew timeValue irid ikun akbar minn żero meta jinħoloq limitu. Jitneħħew l-ispazji mit-truf tal-emails u jiġu kkonvertiti f'ittri żgħar. UIDs RFID jiġu aċċettati biss fil-kitbiet u huma moħbija fir-risponsi tal-qari.

Sommarju tad-DTOs tar-risponsi

It-tabelli tal-endpoints juru kull envelope tar-rispons fl-ogħla livell. Dawn huma d-DTOs prinċipali li jistgħu jerġgħu jintużaw f'dawk l-envelopes:

L-oġġetti lookup jiġu rritornati mir-rotot tal-lista/dettall biex min jagħmel is-sejħa jkun jista' jsib IDs validi. Qis oqsma ġodda mhux magħrufa bħala kompatibbli ma' verżjonijiet futuri u ddistingwi każijiet biss fuq oqsma stabbli u kodiċijiet tal-iżbalji dokumentati.

Endpoints tal-ispazju tax-xogħol

Endpoints tas-siti u tal-ġestjoni tal-qawwa

Endpoints taċ-ċarġers

Endpoints tar-rapporti

Endpoints tat-tariffi

TariffAssignment fih id, chargerId, connectorId, sommarju sigur tat-tariffa/munita, createdAt u updatedAt.

Endpoints tal-profili tal-iċċarġjar

ProfileAssignment fih l-ID tal-assenjazzjoni tiegħu, IDs taċ-ċarġer/konnettur u sommarju sigur tal-profil. L-oġġetti tar-riżultati OCPP juru informazzjoni stabbli tat-talba/status u qatt kredenzjali.

Endpoints tal-utenti, RFID, aċċess, limiti u utenti lokali

L-utent tas-sistema Tagless huwa protett minn dawn l-operazzjonijiet. Żbalji fl-email tal-istedina jirritornaw stat sigur tat-twassil mingħajr ma jikxfu dettalji SMTP; min jagħmel is-sejħa jista' jerġa' jipprova meta emailRetryReady jkun veru.

Risponsi binarji

Żewġ familji ta' endpoints ma jirritornawx JSON meta jirnexxu:

L-iżbalji minn endpoints binarji xorta huma JSON.