Solicitudes y respuestas de endpoints de Admin API del espacio de trabajo

Esta es la referencia de solicitudes y respuestas de cada endpoint /v2/admin. La autenticación, idempotencia, límites de solicitudes, creación de tokens y semántica de ámbitos se documentan en Workspace Admin API. Los tipos reutilizables de campos y los ejemplos están en Esquemas y ejemplos. Lee cada fila de endpoint junto con el Contrato de respuestas y errores, que enumera todos los posibles cuerpos compartidos y específicos de respuestas no satisfactorias.

Contrato común

Cada ruta comienza con el origen de app-api desplegado. El espacio de trabajo se obtiene exclusivamente del token autenticado; los clientes no deben enviar cpoId. Todos los valores de recurso :...Id documentados en la ruta son enteros decimales positivos. Cada solicitud requiere exactamente una:

Authorization: Bearer <workspace-access-token>

Las solicitudes mostradas con cuerpo JSON requieren Content-Type: application/json. Todas las modificaciones requieren Idempotency-Key (POST, PUT, PATCH y DELETE), incluida POST /v2/admin/reports/send; salvo que una fila indique lo contrario, el tipo de contenido correcto es application/json, las fechas JSON son cadenas RFC 3339 y los números son números JSON.

Cada solicitud puede incluir X-Request-Id y X-Error-Format: envelope; consulta el Contrato de respuestas y errores. Estas cabeceras no cambian los esquemas de respuesta correcta.

Notación utilizada a continuación:

• none significa que no hay cuerpo de solicitud. Un DELETE que documenta un cuerpo JSON sigue requiriendo ese cuerpo.
• ? marca una propiedad o parámetro de consulta opcional.
• T | null significa que la propiedad está presente y admite null.
• 204 empty significa que no hay cuerpo de respuesta.
• CursorPage<T> significa { items: T[], nextCursor: number|string|null }, salvo que la fila nombre explícitamente un objeto page o pagination.
• Todos los casos de recursos anidados no encontrados, incluidos los ID de otros espacios de trabajo, utilizan 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, salvo que una función documente un conflicto más específico.

Esquemas de solicitud compartidos

Entradas de espacios de trabajo y emplazamientos

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
}

Entrada de gestión de potencia

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
}

Entradas de cargadores

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

Entradas de informes

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

Los intervalos de informes deben cumplir from < to y no superar 90 días. Si se omiten, se usan los últimos 90 días. userId y anonymous=true se excluyen mutuamente. Las exportaciones programadas recuperan una ejecución perdida tras el minuto UTC previsto y utilizan reintentos limitados: espera de 5/10 minutos, concesión de 30 minutos para reservas obsoletas y tres intentos.

Entradas de tarifas

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 }

Entradas de perfiles de carga

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 }

Entradas de usuarios

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 }

Al menos uno de energyValue o timeValue debe ser mayor que cero al crear un límite. Se eliminan los espacios iniciales y finales de los correos y se convierten a minúsculas. Los UID RFID solo se aceptan al escribir y se enmascaran en las respuestas de lectura.

Resumen de DTO de respuesta

Las tablas de endpoints muestran todas las envolturas de respuesta de nivel superior. Estos son los principales DTO reutilizables dentro de ellas:

Los objetos de referencia se devuelven en las rutas de lista y detalle para que los clientes descubran los ID válidos. Considera los nuevos campos desconocidos compatibles con versiones futuras y basa la lógica solo en los campos estables y códigos de error documentados.

Endpoints del espacio de trabajo

Endpoints de emplazamientos y gestión de potencia

Endpoints de cargadores

Endpoints de informes

Endpoints de tarifas

TariffAssignment contiene id, chargerId, connectorId, un resumen seguro de tarifa/moneda, createdAt y updatedAt.

Endpoints de perfiles de carga

ProfileAssignment contiene su ID de asignación, los ID de cargador/conector y un resumen seguro del perfil. Los objetos de resultado OCPP muestran información estable de solicitud/estado y nunca credenciales.

Endpoints de usuarios, RFID, acceso, límites y usuarios locales

El usuario de sistema de Tagless está protegido frente a estas operaciones. Los fallos de correo de invitación devuelven un estado de entrega seguro sin revelar detalles SMTP; los clientes pueden reintentar cuando emailRetryReady sea verdadero.

Respuestas binarias

Dos familias de endpoints no devuelven JSON cuando la operación tiene éxito:

Los errores de los endpoints binarios siguen siendo JSON.