Αιτήματα και αποκρίσεις endpoints Admin API χώρου εργασίας

Αυτή είναι η αναφορά αιτημάτων/αποκρίσεων για κάθε endpoint /v2/admin. Έλεγχος ταυτότητας, ιδιοδυναμία, όρια, δημιουργία διακριτικών και σημασιολογία πεδίων πρόσβασης τεκμηριώνονται στο Admin API χώρου εργασίας. Τύποι πεδίων και παραδείγματα βρίσκονται στα Σχήματα και παραδείγματα. Διαβάζετε κάθε γραμμή μαζί με τη Σύμβαση αποκρίσεων και σφαλμάτων, που παραθέτει όλα τα κοινά και ειδικά ανεπιτυχή σώματα.

Κοινή σύμβαση

Κάθε διαδρομή αρχίζει με την εγκατεστημένη προέλευση app-api. Ο χώρος εργασίας προκύπτει αποκλειστικά από το επαληθευμένο διακριτικό· οι πελάτες δεν πρέπει να στέλνουν cpoId. Όλες οι τεκμηριωμένες τιμές :...Id διαδρομών πόρων είναι θετικοί δεκαδικοί ακέραιοι. Κάθε αίτημα απαιτεί ακριβώς μία:

Authorization: Bearer <workspace-access-token>

Τα αιτήματα με σώμα JSON απαιτούν Content-Type: application/json. Όλες οι μεταβολές απαιτούν Idempotency-Key (POST, PUT, PATCH και DELETE), περιλαμβανομένου του POST /v2/admin/reports/send· εκτός αν αναφέρεται αλλιώς, ο τύπος περιεχομένου επιτυχίας είναι application/json, οι ημερομηνίες JSON είναι συμβολοσειρές RFC 3339 και οι αριθμοί αριθμοί JSON.

Κάθε αίτημα μπορεί να περιέχει X-Request-Id και X-Error-Format: envelope· βλ. Σύμβαση αποκρίσεων και σφαλμάτων. Οι κεφαλίδες δεν αλλάζουν τα σχήματα επιτυχίας.

Σημειογραφία παρακάτω:

• Το none σημαίνει χωρίς σώμα αιτήματος. Ένα DELETE που τεκμηριώνει σώμα JSON εξακολουθεί να το απαιτεί.
• Το ? δηλώνει προαιρετική ιδιότητα ή παράμετρο ερωτήματος.
• Το T | null σημαίνει ότι η ιδιότητα υπάρχει και δέχεται null.
• Το 204 empty σημαίνει χωρίς σώμα απόκρισης.
• Το CursorPage<T> σημαίνει { items: T[], nextCursor: number|string|null }, εκτός όπου η γραμμή ονομάζει ρητά αντικείμενο page ή pagination.
• Όλοι οι απόντες ένθετοι πόροι, ακόμη και αναγνωριστικά άλλου χώρου εργασίας, χρησιμοποιούν 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, εκτός αν η λειτουργία τεκμηριώνει πιο συγκεκριμένη διένεξη.

Κοινά σχήματα αιτημάτων

Είσοδοι χώρου εργασίας και τοποθεσίας

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
}

Είσοδος διαχείρισης ισχύος

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
}

Είσοδοι φορτιστών

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

Είσοδοι αναφορών

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

Τα διαστήματα αναφορών πρέπει να ικανοποιούν from < to και να μην υπερβαίνουν 90 ημέρες. Αν παραλειφθούν, χρησιμοποιούνται οι τελευταίες 90 ημέρες. Τα userId και anonymous=true αποκλείονται αμοιβαία. Οι προγραμματισμένες εξαγωγές αναπληρώνουν χαμένο λεπτό UTC και χρησιμοποιούν περιορισμένες επαναλήψεις (αναμονή 5/10 λεπτών, μίσθωση παλιάς δέσμευσης 30 λεπτών, τρεις προσπάθειες).

Είσοδοι τιμολογίων

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 }

Είσοδοι προφίλ φόρτισης

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 }

Είσοδοι χρηστών

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 }

Τουλάχιστον ένα από energyValue ή timeValue πρέπει να είναι μεγαλύτερο από μηδέν κατά τη δημιουργία ορίου. Τα email περικόπτονται και γίνονται πεζά. Τα UID RFID γίνονται δεκτά μόνο σε εγγραφές και καλύπτονται στις αποκρίσεις ανάγνωσης.

Σύνοψη DTO απόκρισης

Οι πίνακες endpoints δείχνουν κάθε φάκελο απόκρισης ανώτατου επιπέδου. Αυτά είναι τα κύρια επαναχρησιμοποιήσιμα DTO μέσα τους:

Οι διαδρομές λίστας/λεπτομερειών επιστρέφουν αντικείμενα αναφοράς για εύρεση έγκυρων ID. Αντιμετωπίζετε άγνωστα πρόσθετα πεδία ως συμβατά με μελλοντικές εκδόσεις και διακλαδώστε μόνο σε τεκμηριωμένα σταθερά πεδία και κωδικούς σφαλμάτων.

Endpoints χώρου εργασίας

Endpoints τοποθεσίας και διαχείρισης ισχύος

Endpoints φορτιστών

Endpoints αναφορών

Endpoints τιμολογίων

Το TariffAssignment περιέχει id, chargerId, connectorId, ασφαλή σύνοψη τιμολογίου/νομίσματος, createdAt και updatedAt.

Endpoints προφίλ φόρτισης

Το ProfileAssignment περιέχει ID ανάθεσης, ID φορτιστή/υποδοχής και ασφαλή σύνοψη προφίλ. Τα αποτελέσματα OCPP εκθέτουν σταθερές πληροφορίες αιτήματος/κατάστασης και ποτέ διαπιστευτήρια.

Endpoints χρήστη, RFID, πρόσβασης, ορίων και τοπικού χρήστη

Ο χρήστης συστήματος Tagless προστατεύεται από αυτές τις λειτουργίες. Αποτυχίες email πρόσκλησης επιστρέφουν ασφαλή κατάσταση παράδοσης χωρίς λεπτομέρειες SMTP· οι καλούντες επαναλαμβάνουν όταν το emailRetryReady είναι true.

Δυαδικές αποκρίσεις

Δύο ομάδες endpoints δεν επιστρέφουν JSON στην επιτυχία:

Τα σφάλματα δυαδικών endpoints παραμένουν JSON.