Verzoeken en antwoorden van de Beheer-API voor werkruimten

Dit is de verzoek-/antwoordreferentie voor elk /v2/admin-eindpunt. Authenticatie, idempotentie, verzoeklimieten, tokenaanmaak en de betekenis van scopes staan in Beheer-API voor werkruimten. Herbruikbare veldtypen en voorbeelden staan in Schema's en voorbeelden. Lees elke eindpuntrij samen met Antwoord- en foutcontract, dat alle mogelijke gedeelde en eindpuntspecifieke antwoordbodies bij mislukking beschrijft.

Gedeeld contract

Elk pad begint met de oorsprong van de geïmplementeerde app-api. De werkruimte wordt uitsluitend afgeleid van het geauthenticeerde token; clients mogen geen cpoId verzenden. Alle gedocumenteerde :...Id-resourcepadwaarden zijn positieve decimale gehele getallen. Elk verzoek vereist precies één:

Authorization: Bearer <workspace-access-token>

Verzoeken met een JSON-body vereisen Content-Type: application/json. Alle mutaties vereisen Idempotency-Key (POST, PUT, PATCH en DELETE), waaronder POST /v2/admin/reports/send; tenzij een rij anders vermeldt, is het inhoudstype bij succes application/json, zijn JSON-datums RFC 3339-tekenreeksen en zijn getallen JSON-getallen.

Elk verzoek mag X-Request-Id en X-Error-Format: envelope bevatten; zie Antwoord- en foutcontract. Deze headers veranderen de successchema's niet.

Hieronder gebruikte notatie:

• none betekent geen verzoekbody. Een DELETE waarvoor een JSON-body is gedocumenteerd, vereist die body nog steeds.
• ? geeft een optionele eigenschap of queryparameter aan.
• T | null betekent dat de eigenschap aanwezig is en null mag zijn.
• 204 empty betekent geen antwoordbody.
• CursorPage<T> betekent { items: T[], nextCursor: number|string|null }, behalve als de rij expliciet een page- of pagination-object noemt.
• Alle ontbrekende geneste resources, ook ID's uit een andere werkruimte, gebruiken 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, tenzij een functie een specifieker conflict documenteert.

Gedeelde verzoekschema's

Invoer voor werkruimten en locaties

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
}

Invoer voor vermogensbeheer

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
}

Invoer voor laders

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

Invoer voor rapporten

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

Rapportbereiken moeten voldoen aan from < to en mogen niet langer zijn dan 90 dagen. Als ze ontbreken, worden de laatste 90 dagen gebruikt. userId en anonymous=true sluiten elkaar uit. Geplande exports halen een gemiste UTC-minuut in en gebruiken begrensde nieuwe pogingen (5/10 minuten wachttijd, 30 minuten reservering voor een verouderde claim, drie pogingen).

Invoer voor tarieven

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 }

Invoer voor laadprofielen

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 }

Invoer voor gebruikers

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 }

Bij het aanmaken van een limiet moet ten minste één van energyValue of timeValue groter zijn dan nul. Spaties aan het begin en einde van e-mailadressen worden verwijderd en letters worden naar kleine letters omgezet. RFID-UID's worden alleen bij schrijven geaccepteerd en worden in leesantwoorden gemaskeerd.

Samenvatting van antwoord-DTO's

De eindpunttabellen tonen elk antwoordomhulsel op het hoogste niveau. Dit zijn de belangrijkste herbruikbare DTO's binnen die omhulsels:

Referentieobjecten worden door lijst- en detailroutes geretourneerd zodat aanroepende toepassingen geldige ID's kunnen vinden. Behandel onbekende toegevoegde velden als toekomstige compatibele uitbreidingen en baseer beslissingen alleen op gedocumenteerde stabiele velden en foutcodes.

Werkruimte-eindpunten

Eindpunten voor locaties en vermogensbeheer

Ladereindpunten

Rapporteindpunten

Tariefeindpunten

TariffAssignment bevat id, chargerId, connectorId, een veilige tarief-/valutasamenvatting, createdAt en updatedAt.

Eindpunten voor laadprofielen

ProfileAssignment bevat de toewijzings-ID, lader-/connector-ID's en een veilige profielsamenvatting. OCPP-resultaatobjecten tonen stabiele verzoek-/statusinformatie en nooit referenties.

Eindpunten voor gebruikers, RFID, toegang, limieten en lokale gebruikers

De Tagless-systeemgebruiker is beschermd tegen deze bewerkingen. Mislukte uitnodigingsmails retourneren een veilige bezorgstatus zonder SMTP-details te onthullen; aanroepende toepassingen kunnen opnieuw proberen als emailRetryReady waar is.

Binaire antwoorden

Twee eindpuntgroepen retourneren bij succes geen JSON:

Fouten van binaire eindpunten blijven JSON.