Zahtjevi i odgovori krajnjih točaka administratorskog API-ja radnog prostora

Ovo je referenca zahtjeva i odgovora za svaku krajnju točku /v2/admin. Autentifikacija, idempotentnost, ograničenja učestalosti, stvaranje tokena i značenje opsega pristupa dokumentirani su u odjeljku Administratorski API radnog prostora. Višekratno upotrebljivi tipovi pojedinih polja i primjeri nalaze se u odjeljku Sheme i primjeri. Svaki redak krajnje točke čitajte zajedno s odjeljkom Ugovor odgovora i pogrešaka, koji navodi sva moguća tijela zajedničkih neuspješnih odgovora i onih specifičnih za krajnju točku.

Zajednički ugovor

Svaka putanja započinje ishodištem postavljene usluge app-api. Radni prostor određuje se isključivo iz autentificiranog tokena; klijenti ne smiju slati cpoId. Sve dokumentirane vrijednosti :...Id u putanjama resursa pozitivni su decimalni cijeli brojevi. Svaki zahtjev zahtijeva točno jedno:

Authorization: Bearer <workspace-access-token>

Zahtjevi prikazani s JSON tijelom zahtijevaju Content-Type: application/json. Sve operacije koje mijenjaju podatke zahtijevaju Idempotency-Key (POST, PUT, PATCH i DELETE), uključujući POST /v2/admin/reports/send; ako u retku nije navedeno drukčije, vrsta sadržaja uspješnog odgovora je application/json, JSON datumi su tekstualni nizovi RFC 3339, a brojevi su JSON brojevi.

Svaki zahtjev može uključivati X-Request-Id i X-Error-Format: envelope; pogledajte Ugovor odgovora i pogrešaka. Ta zaglavlja ne mijenjaju sheme uspješnih odgovora.

Oznake koje se upotrebljavaju u nastavku:

• none znači da nema tijela zahtjeva. DELETE za koji je dokumentirano JSON tijelo i dalje zahtijeva to tijelo.
• ? označava neobavezno svojstvo ili parametar upita.
• T | null znači da je svojstvo prisutno i može biti null.
• 204 empty znači da nema tijela odgovora.
• CursorPage<T> znači { items: T[], nextCursor: number|string|null }, osim kada redak izričito imenuje objekt page ili pagination.
• Za sve slučajeve kada ugniježđeni resurs nije pronađen, uključujući ID-jeve iz drugog radnog prostora, upotrebljava se 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, osim ako za značajku nije dokumentiran konkretniji sukob.

Zajedničke sheme zahtjeva

Ulazni podaci radnog prostora i lokacije

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
}

Ulazni podaci upravljanja snagom

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
}

Ulazni podaci punjača

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

Ulazni podaci izvještaja

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

Rasponi izvještaja moraju zadovoljavati from < to i ne smiju prelaziti 90 dana. Ako se izostave, upotrebljava se najnovije razdoblje od 90 dana. userId i anonymous=true međusobno se isključuju. Zakazani izvozi nadoknađuju propuštenu UTC minutu i upotrebljavaju ograničene ponovne pokušaje (čekanje od 5/10 minuta, vremenska rezervacija zastarjelog preuzimanja zadatka od 30 minuta, tri pokušaja).

Ulazni podaci tarifa

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 }

Ulazni podaci profila punjenja

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 }

Ulazni podaci korisnika

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 }

Pri stvaranju ograničenja barem jedno od polja energyValue ili timeValue mora biti veće od nule. Adresama e-pošte uklanjaju se rubni razmaci i pretvaraju se u mala slova. RFID UID-jevi prihvaćaju se samo pri upisu, a u odgovorima za čitanje prikazuju se maskirani.

Sažetak DTO-ova odgovora

Tablice krajnjih točaka prikazuju svaku omotnicu odgovora na najvišoj razini. Ovo su glavni višekratno upotrebljivi DTO-ovi unutar tih omotnica:

Referentni objekti vraćaju se rutama za popise i pojedinosti kako bi pozivatelji mogli pronaći valjane ID-jeve. Nepoznata dodana polja smatrajte proširenjima kompatibilnima s budućim verzijama, a odluke temeljite samo na dokumentiranim stabilnim poljima i kodovima pogrešaka.

Krajnje točke za radni prostor

Krajnje točke za lokacije i upravljanje snagom

Krajnje točke za punjače

Krajnje točke za izvještaje

Krajnje točke za tarife

TariffAssignment sadrži id, chargerId, connectorId, siguran sažetak tarife/valute, createdAt i updatedAt.

Krajnje točke za profile punjenja

ProfileAssignment sadrži ID dodjele, ID-jeve punjača/priključka i siguran sažetak profila. Objekti OCPP rezultata prikazuju stabilne podatke o zahtjevu/statusu, a nikada vjerodajnice.

Krajnje točke za korisnike, RFID, pristup, ograničenja i lokalne korisnike

Sistemski korisnik Tagless zaštićen je od tih operacija. Neuspjelo slanje pozivnice e-poštom vraća sigurno stanje dostave bez otkrivanja SMTP pojedinosti; pozivatelji mogu pokušati ponovno kada je emailRetryReady istinit.

Binarni odgovori

Dvije skupine krajnjih točaka pri uspjehu ne vraćaju JSON:

Pogreške binarnih krajnjih točaka i dalje su u JSON formatu.