Requêtes et réponses des points de terminaison de l’API d’administration de l’espace de travail

Il s’agit de la référence des requêtes/réponses pour chaque point de terminaison /v2/admin. L’authentification, l’idempotence, les limites de fréquence, la création des jetons et le sens des portées sont documentés dans API d’administration de l’espace de travail. Les types de champs réutilisables et les exemples figurent dans Schémas et exemples. Lisez chaque ligne de point de terminaison avec Contrat des réponses et des erreurs, qui répertorie tous les corps possibles de réponse d’échec communs ou spécifiques.

Contrat commun

Chaque chemin commence par l’origine du service app-api déployé. L’espace de travail est déduit exclusivement du jeton authentifié ; les clients ne doivent pas envoyer cpoId. Toutes les valeurs de chemin de ressource :...Id documentées sont des entiers décimaux positifs. Chaque requête nécessite exactement un :

Authorization: Bearer <workspace-access-token>

Les requêtes présentées avec un corps JSON nécessitent Content-Type: application/json. Toutes les mutations nécessitent Idempotency-Key (POST, PUT, PATCH et DELETE), y compris POST /v2/admin/reports/send ; sauf mention contraire sur la ligne, le type de contenu en cas de réussite est application/json, les dates JSON sont des chaînes RFC 3339 et les nombres sont des nombres JSON.

Chaque requête peut inclure X-Request-Id et X-Error-Format: envelope ; voir Contrat des réponses et des erreurs. Ces en-têtes ne modifient pas les schémas de réussite.

Notation utilisée ci-dessous :

• none signifie aucun corps de requête. Un DELETE documentant un corps JSON exige toujours ce corps.
• ? indique une propriété ou un paramètre de requête facultatif.
• T | null signifie que la propriété est présente et peut être null.
• 204 empty signifie aucun corps de réponse.
• CursorPage<T> signifie { items: T[], nextCursor: number|string|null }, sauf lorsque la ligne nomme explicitement un objet page ou pagination.
• Tous les cas de ressources imbriquées introuvables, y compris les ID d’autres espaces de travail, utilisent 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, sauf si une fonctionnalité documente un conflit plus précis.

Schémas de requête communs

Entrées de l’espace de travail et du site

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
}

Entrée de gestion de la puissance

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
}

Entrées des bornes

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

Entrées des rapports

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

Les plages de rapport doivent satisfaire from < to et ne peuvent pas dépasser 90 jours. Si elles sont omises, les 90 derniers jours sont utilisés. userId et anonymous=true s’excluent mutuellement. Les exports planifiés rattrapent une minute UTC manquée et utilisent des tentatives limitées : attente de 5/10 minutes, bail de 30 minutes pour une réservation devenue obsolète, trois tentatives.

Entrées des tarifs

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 }

Entrées des profils de recharge

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 }

Entrées des utilisateurs

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 }

Lors de la création d’une limite, au moins une valeur parmi energyValue et timeValue doit être supérieure à zéro. Les espaces en début et en fin d’e-mail sont supprimés et les lettres converties en minuscules. Les UID RFID sont acceptés uniquement en écriture et masqués dans les réponses de lecture.

Résumé des DTO de réponse

Les tableaux des points de terminaison montrent chaque enveloppe de réponse de premier niveau. Voici les principaux DTO réutilisables contenus dans ces enveloppes :

Les objets de référentiel sont renvoyés par les routes de liste et de détail pour permettre aux appelants de découvrir les ID valides. Traitez les nouveaux champs inconnus comme des extensions compatibles avec les versions futures et fondez vos décisions uniquement sur les champs stables documentés et les codes d’erreur.

Points de terminaison de l’espace de travail

Points de terminaison des sites et de gestion de la puissance

Points de terminaison des bornes

Points de terminaison des rapports

Points de terminaison des tarifs

TariffAssignment contient id, chargerId, connectorId, une synthèse sûre du tarif/de la devise, createdAt et updatedAt.

Points de terminaison des profils de recharge

ProfileAssignment contient son ID d’attribution, les ID de borne/connecteur et une synthèse sûre du profil. Les objets de résultat OCPP exposent des informations stables de requête/statut et jamais d’identifiants de connexion.

Points de terminaison des utilisateurs, RFID, accès, limites et utilisateurs locaux

L’utilisateur système Tagless est protégé contre ces opérations. Les échecs d’envoi des invitations renvoient un état de livraison sûr sans divulguer les détails SMTP ; les appelants peuvent réessayer lorsque emailRetryReady vaut true.

Réponses binaires

Deux familles de points de terminaison ne renvoient pas de JSON en cas de réussite :

Les erreurs des points de terminaison binaires restent en JSON.