Endpointanrop och svar i arbetsytans Admin API

Detta är anrops- och svarsreferensen för varje /v2/admin-endpoint. Autentisering, idempotens, anropsgränser, tokenskapande och behörighetsområdenas betydelse dokumenteras i Workspace Admin API. Återanvändbara fälttyper och exempel finns i Scheman och exempel. Läs varje endpointrad tillsammans med Kontrakt för svar och fel, som listar alla möjliga gemensamma och endpointspecifika svarskroppar vid fel.

Gemensamt kontrakt

Varje sökväg börjar med den driftsatta app-api-serverns ursprung. Arbetsytan härleds uteslutande från den autentiserade token; klienter får inte skicka cpoId. Alla dokumenterade resursvärden :...Id i sökvägen är positiva decimala heltal. Varje anrop kräver exakt en:

Authorization: Bearer <workspace-access-token>

Anrop som visas med JSON-kropp kräver Content-Type: application/json. Alla ändringsåtgärder kräver Idempotency-Key (POST, PUT, PATCH och DELETE), inklusive POST /v2/admin/reports/send; om inget annat anges är innehållstypen vid framgång application/json, JSON-datum är RFC 3339-strängar och tal är JSON-tal.

Varje anrop får innehålla X-Request-Id och X-Error-Format: envelope; se Kontrakt för svar och fel. Dessa headrar ändrar inte scheman för lyckade svar.

Notation som används nedan:

• none betyder ingen anropskropp. En DELETE som dokumenterar en JSON-kropp kräver fortfarande den kroppen.
• ? markerar en valfri egenskap eller frågeparameter.
• T | null betyder att egenskapen finns och får vara null.
• 204 empty betyder ingen svarskropp.
• CursorPage<T> betyder { items: T[], nextCursor: number|string|null }, utom där raden uttryckligen nämner ett page- eller pagination-objekt.
• Alla saknade underordnade resurser, även ID:n från andra arbetsytor, använder 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" } om inte en funktion dokumenterar en mer specifik konflikt.

Gemensamma anropsscheman

Indata för arbetsytor och platser

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
}

Indata för effektstyrning

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
}

Laddarindata

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

Rapportindata

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

Rapportintervall måste uppfylla from < to och får inte överstiga 90 dagar. Vid utelämnande används de senaste 90 dagarna. userId och anonymous=true utesluter varandra. Schemalagda exporter körs i efterhand efter en missad UTC-minut och använder begränsade återförsök: 5/10 minuters väntetid, 30 minuters reservation för inaktuella behandlingsanspråk och tre försök.

Tariffindata

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 }

Indata för laddprofiler

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 }

Användarindata

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 }

Minst ett av energyValue eller timeValue måste vara större än noll när en gräns skapas. Inledande och avslutande blanksteg tas bort från e-postadresser och bokstäverna görs gemena. RFID-UID:n accepteras endast vid skrivning och maskeras i lässvar.

Sammanfattning av svars-DTO:er

Endpointtabellerna visar varje svarsomslutning på översta nivån. Detta är de viktigaste återanvändbara DTO:erna i omslutningarna:

Uppslagsobjekt returneras av list- och detaljrutter så att klienter kan hitta giltiga ID:n. Behandla okända nytillkomna fält som framåtkompatibla och basera logiken enbart på dokumenterade stabila fält och felkoder.

Arbetsyteendpoints

Endpoints för platser och effektstyrning

Laddarendpoints

Rapportendpoints

Tariffendpoints

TariffAssignment innehåller id, chargerId, connectorId, en säker tariff-/valutasammanfattning, createdAt och updatedAt.

Endpoints för laddprofiler

ProfileAssignment innehåller tilldelnings-ID, laddar-/kontakt-ID:n och en säker profilsammanfattning. OCPP-resultatobjekt visar stabil anrops- och statusinformation men aldrig autentiseringsuppgifter.

Endpoints för användare, RFID, åtkomst, gränser och lokala användare

Tagless-systemanvändaren skyddas från dessa åtgärder. Fel vid inbjudningsmejl returnerar ett säkert leveranstillstånd utan att läcka SMTP-uppgifter; klienter kan försöka igen när emailRetryReady är sant.

Binära svar

Två endpointgrupper returnerar inte JSON vid framgång:

Fel från binära endpoints är fortfarande JSON.