Cereri și răspunsuri ale endpointurilor API-ului de administrare a spațiului de lucru

Aceasta este referința cererilor/răspunsurilor pentru fiecare endpoint /v2/admin. Autentificarea, idempotența, limitele de rată, crearea tokenurilor și semantica domeniilor de acces sunt documentate în API-ul de administrare a spațiului de lucru. Tipurile reutilizabile la nivel de câmp și exemplele se află în Scheme și exemple. Citește fiecare rând de endpoint împreună cu Contractul de răspunsuri și erori, care enumeră toate corpurile posibile de răspuns de nereușită comune și specifice endpointurilor.

Contract comun

Fiecare cale începe cu originea implementată app-api. Spațiul de lucru este derivat exclusiv din tokenul autentificat; clienții nu trebuie să trimită cpoId. Toate valorile documentate ale căilor de resurse :...Id sunt numere întregi zecimale pozitive. Fiecare cerere necesită exact unul:

Authorization: Bearer <workspace-access-token>

Cererile afișate cu un corp JSON necesită Content-Type: application/json. Toate modificările necesită Idempotency-Key (POST, PUT, PATCH și DELETE), inclusiv POST /v2/admin/reports/send; dacă un rând nu precizează altfel, tipul de conținut al succesului este application/json, datele JSON sunt șiruri RFC 3339, iar numerele sunt numere JSON.

Fiecare cerere poate include X-Request-Id și X-Error-Format: envelope; vezi Contractul de răspunsuri și erori. Aceste antete nu modifică schemele de succes.

Notația folosită mai jos:

• none înseamnă fără corp de cerere. Un DELETE care documentează un corp JSON necesită în continuare acel corp.
• ? marchează o proprietate sau un parametru de interogare opțional.
• T | null înseamnă că proprietatea este prezentă și poate fi null.
• 204 empty înseamnă fără corp de răspuns.
• CursorPage<T> înseamnă { items: T[], nextCursor: number|string|null }, cu excepția cazului în care rândul numește explicit un obiect page sau pagination.
• Toate cazurile de resurse imbricate negăsite, inclusiv ID-uri din alte spații de lucru, folosesc 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, cu excepția funcțiilor care documentează un conflict mai specific.

Scheme comune de cerere

Date de intrare pentru spații de lucru și locații

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
}

Date de intrare pentru gestionarea puterii

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
}

Date de intrare pentru stații

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

Date de intrare pentru rapoarte

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

Intervalele rapoartelor trebuie să respecte from < to și nu pot depăși 90 de zile. Când sunt omise, este folosit ultimul interval de 90 de zile. userId și anonymous=true se exclud reciproc. Exporturile programate recuperează o minută UTC ratată și folosesc reîncercări limitate (întârziere de 5/10 minute, rezervare de 30 de minute pentru o revendicare expirată, trei încercări).

Date de intrare pentru tarife

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 }

Date de intrare pentru profiluri de încărcare

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 }

Date de intrare pentru utilizatori

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 }

Cel puțin unul dintre energyValue sau timeValue trebuie să fie mai mare decât zero la crearea unei limite. Spațiile de la capetele adreselor de email sunt eliminate, iar adresele sunt convertite în litere mici. UID-urile RFID sunt acceptate doar la scriere și sunt mascate în răspunsurile de citire.

Rezumatul DTO-urilor de răspuns

Tabelele endpointurilor afișează fiecare anvelopă de răspuns de nivel superior. Acestea sunt principalele DTO-uri reutilizabile din acele anvelope:

Obiectele de referință sunt returnate de rutele de listă/detaliu, astfel încât apelanții să poată descoperi ID-uri valide. Tratează câmpurile noi necunoscute ca fiind compatibile cu versiunile viitoare și diferențiază cazurile doar pe baza câmpurilor stabile și codurilor de eroare documentate.

Endpointuri pentru spații de lucru

Endpointuri pentru locații și gestionarea puterii

Endpointuri pentru stații

Endpointuri pentru rapoarte

Endpointuri pentru tarife

TariffAssignment conține id, chargerId, connectorId, un rezumat sigur al tarifului/monedei, createdAt și updatedAt.

Endpointuri pentru profiluri de încărcare

ProfileAssignment conține ID-ul atribuirii, ID-urile stației/conectorului și un rezumat sigur al profilului. Obiectele de rezultat OCPP expun informații stabile despre cerere/stare și niciodată date de autentificare.

Endpointuri pentru utilizatori, RFID, acces, limite și utilizatori locali

Utilizatorul de sistem Tagless este protejat de aceste operațiuni. Eșecurile trimiterii emailurilor de invitație returnează o stare sigură a livrării fără a divulga detalii SMTP; apelanții pot reîncerca atunci când emailRetryReady este adevărat.

Răspunsuri binare

Două familii de endpointuri nu returnează JSON în caz de succes:

Erorile endpointurilor binare sunt în continuare JSON.