Anmodninger og svar for endpoints i arbejdsområdets Admin API

Dette er anmodnings- og svarreferencen for hvert /v2/admin-endpoint. Autentificering, idempotens, anmodningsgrænser, tokenoprettelse og scopes betydning er dokumenteret i Workspace Admin API. Genanvendelige felttyper og eksempler findes i Skemaer og eksempler. Læs hver endpointrække sammen med Kontrakt for svar og fejl, som viser alle mulige fælles og endpointspecifikke svartekster ved manglende succes.

Fælles kontrakt

Hver sti begynder med den installerede app-api-oprindelse. Arbejdsområdet udledes udelukkende af det autentificerede token; klienter må ikke sende cpoId. Alle dokumenterede ressourcestiværdier af typen :...Id er positive decimale heltal. Hver anmodning kræver præcis én:

Authorization: Bearer <workspace-access-token>

Anmodninger vist med JSON-anmodningstekst kræver Content-Type: application/json. Alle ændringshandlinger kræver Idempotency-Key (POST, PUT, PATCH og DELETE), inklusive POST /v2/admin/reports/send; medmindre en række angiver andet, er indholdstypen ved succes application/json, JSON-datoer er RFC 3339-strenge, og tal er JSON-tal.

Hver anmodning kan indeholde X-Request-Id og X-Error-Format: envelope; se Kontrakt for svar og fejl. Disse headere ændrer ikke skemaer for vellykkede svar.

Notation anvendt nedenfor:

• none betyder ingen anmodningstekst. En DELETE, der dokumenterer en JSON-anmodningstekst, kræver stadig denne tekst.
• ? markerer en valgfri egenskab eller forespørgselsparameter.
• T | null betyder, at egenskaben er til stede og kan være null.
• 204 empty betyder ingen svartekst.
• CursorPage<T> betyder { items: T[], nextCursor: number|string|null }, undtagen hvor rækken udtrykkeligt angiver et page- eller pagination-objekt.
• Alle tilfælde, hvor en underordnet ressource ikke findes, inklusive ID'er fra andre arbejdsområder, bruger 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, medmindre en funktion dokumenterer en mere specifik konflikt.

Fælles anmodningsskemaer

Input til arbejdsområder og steder

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 til strømstyring

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
}

Laderinput

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

Rapportinput

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

Rapportintervaller skal opfylde from < to og må ikke overstige 90 dage. Ved udeladelse bruges det seneste 90-dagesinterval. userId og anonymous=true udelukker hinanden. Planlagte eksporter indhenter et overskredet UTC-minut og bruger begrænsede genforsøg: 5/10 minutters ventetid, en 30-minutters lås på forældede behandlingskrav og tre forsøg.

Tarifinput

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 }

Input til ladeprofiler

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 }

Brugerinput

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 }

Mindst én af energyValue eller timeValue skal være større end nul, når en grænse oprettes. Indledende og afsluttende mellemrum fjernes fra e-mailadresser, som konverteres til små bogstaver. RFID-UID'er accepteres kun ved skrivning og maskeres i læsesvar.

Oversigt over svar-DTO'er

Endpointtabellerne viser alle svaromslutninger på øverste niveau. Dette er de vigtigste genanvendelige DTO'er inde i disse omslutninger:

Opslagsobjekter returneres af liste- og detaljeruter, så klienter kan finde gyldige ID'er. Behandl ukendte tilføjede felter som fremadkompatible, og basér kun logik på dokumenterede stabile felter og fejlkoder.

Arbejdsområde-endpoints

Endpoints til steder og strømstyring

Lader-endpoints

Rapport-endpoints

Tarif-endpoints

TariffAssignment indeholder id, chargerId, connectorId, en sikker tarif-/valutaoversigt, createdAt og updatedAt.

Endpoints til ladeprofiler

ProfileAssignment indeholder tildelings-ID, lader-/stik-ID'er og en sikker profiloversigt. OCPP-resultatobjekter viser stabile anmodnings- og statusoplysninger og aldrig legitimationsoplysninger.

Endpoints til brugere, RFID, adgang, grænser og lokale brugere

Tagless-systembrugeren er beskyttet mod disse handlinger. Fejl ved invitationsmails returnerer en sikker leveringsstatus uden at afsløre SMTP-oplysninger; klienter kan prøve igen, når emailRetryReady er sand.

Binære svar

To endpointgrupper returnerer ikke JSON ved succes:

Fejl fra binære endpoints er stadig JSON.