Richieste e risposte degli endpoint dell'API di amministrazione dello spazio di lavoro

Questo è il riferimento delle richieste e delle risposte per ogni endpoint /v2/admin. Autenticazione, idempotenza, limiti di frequenza, creazione dei token e semantica degli ambiti sono documentati in API di amministrazione dello spazio di lavoro. I tipi riutilizzabili a livello di campo e gli esempi sono in Schemi ed esempi. Leggi ogni riga degli endpoint insieme a Contratto delle risposte e degli errori, che elenca tutti i possibili corpi di errore comuni e specifici degli endpoint.

Contratto comune

Ogni percorso inizia con l’origine del servizio app-api distribuito. Lo spazio di lavoro deriva esclusivamente dal token autenticato; i client non devono inviare cpoId. Tutti i valori :...Id documentati nei percorsi delle risorse sono interi decimali positivi. Ogni richiesta richiede esattamente una:

Authorization: Bearer <workspace-access-token>

Le richieste mostrate con un corpo JSON richiedono Content-Type: application/json. Tutte le operazioni di modifica richiedono Idempotency-Key (POST, PUT, PATCH e DELETE), incluso POST /v2/admin/reports/send; salvo indicazione diversa nella riga, il tipo di contenuto in caso di successo è application/json, le date JSON sono stringhe RFC 3339 e i numeri sono numeri JSON.

Ogni richiesta può includere X-Request-Id e X-Error-Format: envelope; vedi Contratto di risposte ed errori. Queste intestazioni non cambiano gli schemi di successo.

Notazione usata di seguito:

• none significa nessun corpo della richiesta. Un DELETE che documenta un corpo JSON richiede comunque quel corpo.
• ? indica una proprietà o un parametro di query facoltativo.
• T | null significa che la proprietà è presente e ammette null.
• 204 empty significa nessun corpo della risposta.
• CursorPage<T> significa { items: T[], nextCursor: number|string|null }, salvo quando la riga nomina esplicitamente un oggetto page o pagination.
• Tutti i casi di risorse annidate mancanti, inclusi gli ID di altri spazi di lavoro, usano 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, salvo che una funzione documenti un conflitto più specifico.

Schemi di richiesta condivisi

Dati di ingresso di spazi di lavoro e siti

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
}

Dati di ingresso per la gestione della potenza

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
}

Dati in ingresso dei caricatori

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

Dati di ingresso dei report

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

Gli intervalli dei report devono soddisfare from < to e non possono superare 90 giorni. Se omessi, si usano gli ultimi 90 giorni. userId e anonymous=true si escludono a vicenda. Le esportazioni pianificate vengono recuperate dopo un minuto UTC saltato e usano tentativi limitati (attesa di 5/10 minuti tra i tentativi, riserva delle attività non aggiornate di 30 minuti, tre tentativi).

Dati di ingresso delle tariffe

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 }

Dati in ingresso dei profili di ricarica

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 }

Dati di ingresso degli utenti

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 }

Quando si crea un limite, almeno uno tra energyValue e timeValue deve essere maggiore di zero. Alle e-mail vengono rimossi gli spazi iniziali e finali e le lettere sono convertite in minuscolo. Gli UID RFID sono accettati solo in scrittura e mascherati nelle risposte di lettura.

Riepilogo dei DTO di risposta

Le tabelle degli endpoint mostrano tutte le strutture di risposta di primo livello. Questi sono i principali DTO riutilizzabili al loro interno:

Le route di elenco e dettaglio restituiscono gli oggetti di riferimento per consentire ai chiamanti di individuare gli ID validi. Considera compatibili con le versioni future i campi aggiunti sconosciuti e basa le diramazioni soltanto sui campi stabili e sui codici di errore documentati.

Endpoint dello spazio di lavoro

Endpoint dei siti e della gestione della potenza

Endpoint dei caricatori

Endpoint dei report

Endpoint delle tariffe

TariffAssignment contiene id, chargerId, connectorId, un riepilogo non sensibile di tariffa/valuta, createdAt e updatedAt.

Endpoint dei profili di ricarica

ProfileAssignment contiene l'ID dell'assegnazione, gli ID del caricatore/connettore e un riepilogo non sensibile del profilo. Gli oggetti dei risultati OCPP espongono informazioni stabili su richiesta/stato e non contengono mai credenziali.

Endpoint di utenti, RFID, accessi, limiti e utenti locali

L'utente di sistema Tagless è protetto da queste operazioni. Gli errori delle email di invito restituiscono uno stato di consegna non sensibile senza rivelare i dettagli SMTP; i chiamanti possono riprovare quando emailRetryReady è true.

Risposte binarie

Due famiglie di endpoint non restituiscono JSON in caso di successo:

Gli errori degli endpoint binari rimangono in JSON.