Admin API del espacio de trabajo

Workspace Admin API permite a las integraciones entre servidores administrar un espacio de trabajo de EVCharge. Esta documentación está dirigida a administradores de espacios de trabajo e integradores externos de la API. Utiliza tokens de acceso revocables y vinculados al espacio de trabajo, con ámbitos detallados; no acepta tokens de inicio de sesión de clientes ni sesiones de navegador.

Este directorio es la referencia canónica para desarrolladores de la API /v2/admin implementada por app-api. No documenta las rutas de clientes o móviles ni las rutas HTTP propias del portal de administración.

• Solicitudes y respuestas de endpoints enumera los 87 endpoints registrados, sus ámbitos, parámetros, cuerpos de solicitud y cuerpos de respuesta correcta.
• Esquemas y ejemplos define los tipos reutilizables de solicitud y respuesta y ejemplos representativos de datos JSON.
• Contrato de respuestas y errores define todos los cuerpos compartidos y específicos de respuestas no satisfactorias.

URL base y límite de los recursos

Todas las rutas son relativas al origen de app-api desplegado:

https://api.evcharge.mobi/v2/admin/...

No se acepta el ID del espacio de trabajo en la URL, la cadena de consulta ni el cuerpo de la solicitud. Cada token de acceso está vinculado exactamente a un espacio de trabajo y la API obtiene cpoId de la identidad del token autenticado. Si un emplazamiento, cargador, usuario, tarifa, perfil, asignación o transacción anidados no pertenecen a ese espacio, la API devuelve la misma respuesta 404 RESOURCE_NOT_FOUND, sin revelar la existencia del recurso.

Obtener un token de acceso

Un administrador del espacio de trabajo crea los tokens en Acceso a la API, dentro de Configuración del espacio de trabajo. La gestión de tokens no se ofrece deliberadamente a los tokens del espacio de trabajo.

• El acceso a la API está incluido en todos los planes, incluido Free. El administrador debe tener permiso para editar el espacio de trabajo.
• El host del espacio de trabajo debe activar Admin API mediante adminApiEnabled; de lo contrario, un token válido recibe de app-api una respuesta 404 que no revela la existencia del recurso.
• El administrador solo puede conceder ámbitos permitidos por sus propios permisos actuales y los derechos del espacio de trabajo.
• Los tokens nuevos pueden no caducar, que es la opción predeterminada en Configuración del espacio de trabajo, o tener una duración de 1 a 365 días completos seleccionada por el administrador; el servidor calcula fechas absolutas de caducidad finita. Los tokens sin caducidad siguen siendo válidos hasta su revocación.
• Un espacio de trabajo puede tener como máximo 50 tokens activos.
• La credencial en texto claro se muestra una sola vez. Guárdala inmediatamente en un gestor de secretos.
• El nombre, los ámbitos y la caducidad son inmutables. Para rotar el token, crea un sustituto, despliégalo, compruébalo y revoca el token anterior.
• La revocación es inmediata; las filas revocadas siguen visibles como historial inmutable del espacio de trabajo con datos sensibles ocultos, y no existe un endpoint de introspección de tokens Bearer ni de eliminación permanente.

app-api no tiene ningún endpoint que emita, renueve, liste o revoque estas credenciales. Obtener el token es un requisito previo realizado mediante el portal de administración por una persona, no otro endpoint de esta referencia.

Nunca incluyas el token en el control de versiones, URL, cadenas de consulta, cookies, registros, analítica ni informes de errores.

Autenticación

Envía exactamente una cabecera de estilo RFC 6750 en cada solicitud:

Authorization: Bearer evc_ws_<selector>.<secret>

La credencial opaca exacta es evc_ws_, seguida de un selector base64url canónico de 16 caracteres, . y un secreto base64url canónico de 43 caracteres. Envía la credencial completa sin cambios; no vuelvas a codificarla en base64.

La API rechaza cabeceras de autorización duplicadas, valores unidos por comas, otros esquemas, valores Bearer vacíos, JWT de clientes y credenciales proporcionadas en cualquier lugar distinto de esta cabecera.

Los tokens mal formados, desconocidos, caducados, revocados o no válidos por cualquier otro motivo reciben la misma respuesta:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Cache-Control: no-store
Content-Type: application/json

{
  "error": "Unauthorized",
  "code": "INVALID_WORKSPACE_TOKEN"
}

El servicio comprueba el estado del token y los derechos actuales del espacio de trabajo en cada solicitud. Por tanto, retirar un derecho puede desactivar los ámbitos afectados antes de que caduque el token.

Los tokens de espacios de trabajo son credenciales opacas, no JWT. No tienen token de renovación ni existe un endpoint para renovarlos. Un token con duración limitada deja de autenticar en su expiresAt absoluto; uno sin caducidad sigue siendo válido hasta que se revoca. La rotación consiste en crear una credencial sustituta en el portal, desplegarla en el cliente y revocar la anterior.

Convenciones de solicitudes

• Utiliza Content-Type: application/json para solicitudes con cuerpo JSON.
• Se eliminan los espacios de los extremos de los valores opcionales de X-Request-Id y solo se aceptan si contienen entre 1 y 128 caracteres de A-Z, a-z, 0-9, ., _, : o -; en caso contrario, el servidor genera un UUID. Cada respuesta devuelve el valor seleccionado como X-Request-Id.
• La cabecera opcional X-Error-Format: envelope convierte todas las respuestas de error JSON a la envoltura estructurada documentada en el Contrato de respuestas y errores. Cualquier otro valor conserva el cuerpo de compatibilidad predeterminado.
• Los ID de los parámetros de ruta son enteros positivos. Los ID de tokens de acceso devueltos por el portal son cadenas decimales porque son valores de base de datos de 64 bits sin signo.
• Los valores de fecha y hora son cadenas RFC 3339 con desplazamiento horario explícito, por ejemplo 2026-08-13T12:30:00Z.
• Las eliminaciones correctas suelen devolver 204 No Content.
• Las operaciones de creación suelen devolver 201 Created.
• El trabajo OCPP que solo se ha puesto en cola puede devolver 202 Accepted; no lo interpretes como una confirmación del cargador salvo que la respuesta lo indique explícitamente.
• Las respuestas autenticadas utilizan Cache-Control: no-store. Los endpoints de QR y exportación de informes devuelven cuerpos binarios con cabeceras de contenido explícitas.
• Los orígenes de navegador permitidos pueden leer X-Request-Id, Idempotency-Replayed, Retry-After y Content-Disposition mediante CORS. Esto permite a los clientes del navegador relacionar solicitudes, detectar repeticiones idempotentes, respetar los tiempos de reintento y conservar los nombres de descarga seleccionados por el servidor.

Idempotencia

Todas las solicitudes de administración POST, PUT, PATCH y DELETE deben incluir una cabecera Idempotency-Key. Las claves contienen entre 1 y 255 caracteres visibles y se limitan al token, método y ruta.

Idempotency-Key: provisioning-2026-08-13-site-42

Reutilizar una clave completada con una URL y un cuerpo idénticos repite la respuesta guardada y añade:

Idempotency-Replayed: true

Reutilizar una clave con una solicitud diferente devuelve 409 IDEMPOTENCY_CONFLICT. Una solicitud que aún se está procesando devuelve 409 IDEMPOTENT_REQUEST_PROCESSING con Retry-After: 5.

Las respuestas completadas y los resultados definitivos se conservan para repetición o conciliación durante siete días desde su última actualización. Después, la misma clave puede tratarse como un comando nuevo, por lo que los clientes deben utilizar claves globalmente únicas y no reutilizarlas deliberadamente.

Si caduca la concesión de procesamiento, se cierra la conexión tras iniciarse la ejecución o la operación devuelve un error del servidor, la API no puede determinar con seguridad si se produjo un efecto externo. Durante los siete días de retención, la clave queda con resultado indeterminado definitivo y devuelve 409 IDEMPOTENCY_OUTCOME_UNKNOWN; no se recupera ni se ejecuta automáticamente de nuevo. Comprueba los efectos de la operación antes de una recuperación manual y no envíes la misma operación con una clave nueva hasta completar la conciliación.

Todos los endpoints de administración que modifican datos, incluido POST /reports/send, requieren Idempotency-Key.

Límites de solicitudes

Los límites se aplican tanto al token individual como a su espacio de trabajo. Los valores predeterminados incluidos en el código son:

Una solicitud limitada devuelve 429 Too Many Requests y una cabecera Retry-After. Las instalaciones pueden modificar estos valores.

Errores

Los errores JSON utilizan un code estable cuando el cliente necesita distinguir casos:

{
  "error": "Insufficient workspace-token scope",
  "code": "INSUFFICIENT_SCOPE"
}

Los errores de validación utilizan matrices por campo:

{
  "validationErrors": {
    "name": ["String must contain at least 1 character(s)"]
  }
}

Los estados habituales son:

Catálogo de ámbitos

El siguiente catálogo de ámbitos se utiliza cuando un administrador crea un token. Un ámbito de escritura o de alto impacto puede implicar el ámbito de lectura correspondiente, pero los ámbitos de lectura nunca conceden escritura. Los ámbitos disponibles dependen de los permisos del administrador y de las funciones activadas en el espacio de trabajo.

El acceso a la API está incluido en todos los planes y se controla mediante el ajuste adminApiEnabled del host. Los derechos adicionales a funciones indicados anteriormente siguen siendo aplicables; el acceso a la API no concede funciones ajenas al plan del espacio de trabajo.

Referencia de endpoints

Las tablas siguientes enumeran las 87 rutas de administración del espacio de trabajo. Si una celda incluye varios ámbitos, todos son obligatorios.

Espacio de trabajo

Campos de actualización del espacio de trabajo: name, email, website, addressLine1, addressLine2, postalCode, city, state y countryId. Se requiere al menos un campo. Las cadenas vacías que admiten null se normalizan a null.

Emplazamientos y gestión de potencia

Los cuerpos de creación y actualización de emplazamientos utilizan:

{
  "name": "Main depot",
  "description": null,
  "addressLine1": "1 Example Street",
  "addressLine2": null,
  "postalCode": "LV-1001",
  "city": "Riga",
  "state": null,
  "countryId": 1,
  "timezoneId": 1,
  "latitude": 56.9496,
  "longitude": 24.1052
}

La geocodificación de emplazamientos acepta los campos opcionales de consulta street, city, state, country y countryCode de dos letras, además de la cabecera de solicitud Accept-Language. La búsqueda combinada de calle/ciudad/estado debe contener al menos dos caracteres. Las respuestas solo contienen placeId, displayName, latitude y longitude; no se exponen credenciales ni metadatos específicos del proveedor. El servidor aplica la cola compartida del proveedor de una solicitud por segundo, un tiempo de espera de ocho segundos, una caché acotada de 24 horas y límites globales de solicitudes para tokens de espacios de trabajo.

La gestión de potencia acepta { "pools": [...] }. Un grupo tiene id, name, limit, meterSources opcional y children recursivos. Un cargador secundario tiene chargepointId y priority. La API limita el tamaño del árbol y el número de contadores y realiza un borrado OCPP y una revalidación en dos fases al sustituir el estado instalado. Un cambio rechazado, con tiempo agotado o afectado por una condición de carrera devuelve 409 POWER_MANAGEMENT_CONFLICT y conserva la configuración anterior.

Cargadores

Los parámetros de consulta de registros del cargador son cursor, limit (50 por defecto, máximo 200), from, to, action, direction y levelId. Los de sesiones son page, limit (25 por defecto, máximo 100), from, to y customerId (un ID positivo o unknown). El historial de programaciones compuestas utiliza cursor, limit (20 por defecto, máximo 50) y connectorId opcional.

Informes

Los filtros de datos y exportación de informes son from, to, siteId, chargerId, userId, anonymous y active. from/to usan por defecto los últimos 90 días y no pueden abarcar más de 90 días. userId no se puede combinar con anonymous=true.

• Paginación de datos: cursor opaco, limit=50 por defecto, máximo 100.
• Mediciones: transactionLogId obligatorio, cursor opaco, limit=500 por defecto, máximo 1.000.
• Exportación: format=csv|pdf, csv por defecto, límite máximo de 2.000 filas.
• Las respuestas de exportación utilizan Content-Disposition: attachment, Cache-Control: private, no-store y X-Content-Type-Options: nosniff.

Cuerpo de programación:

{
  "enabled": true,
  "recipientEmail": "reports@example.com",
  "format": "csv",
  "sendDay": 5,
  "sendTime": "08:30"
}

sendDay está entre 1 y 28 y sendTime se interpreta en UTC. El planificador recupera un minuto programado perdido durante el mes de entrega actual. Las generaciones fallidas anteriores a la entrega se reintentan después de 5 y 10 minutos; una reserva building interrumpida se puede recuperar después de 30 minutos y la entrega automática se detiene tras tres intentos. El planificador guarda indeterminate inmediatamente antes de la entrega a SMTP; tanto indeterminate como el estado heredado sending son definitivos porque reintentar automáticamente cualquiera de ellos podría enviar un adjunto duplicado. Los operadores deben conciliar manualmente estos resultados antes de cambiar el estado de la programación. Cada ejecución selecciona como máximo diez programaciones, deja de iniciar trabajo tras un presupuesto de 45 segundos y utiliza tiempos de espera SMTP acotados. El trabajo está desactivado por defecto y debe activarse explícitamente tras validar SMTP y la capacidad. La programación de la API pertenece al espacio de trabajo y no utiliza la identidad de la persona que creó el token.

Tarifas

El cuerpo de una tarifa contiene name, exactamente uno de currencyId, currencyCode o currency, biddingZoneId opcional y tax. El cuerpo de una asignación es:

{ "tariffId": 17, "connectorId": 0 }

Al crear una asignación, la tarifa se aplica a todos los conectores físicos si se omite connectorId o se establece explícitamente en 0. Las actualizaciones actúan sobre una asignación guardada y, por tanto, requieren un connectorId físico positivo y explícito; se rechaza 0.

Un componente contiene typeId, seasonId y price; priority y los límites de validez por mes, día de la semana y hora son opcionales.

Perfiles de carga

Los campos de metadatos del perfil son label, locationId, stackLevel, purposeId, kindId, recurrencyKindId opcional, validFrom, validTo, startSchedule, rateUnitId y minChargingRate opcional. Un periodo de programación contiene startPeriod, limit y numberOfPhases opcional. El cuerpo de una asignación contiene profileId y connectorId (0 por defecto).

La eliminación de perfiles y la sustitución de la gestión de potencia pueden esperar la confirmación del cargador. Un rechazo, tiempo de espera agotado o cambio de estado concurrente devuelve un conflicto y conserva la configuración de la base de datos, en lugar de asumir que se ha borrado la configuración del cargador.

Usuarios, invitaciones, RFID, acceso y límites

La paginación de vehículos y la de usuarios con status=members utilizan un cursor numérico positivo. Las páginas de invitaciones utilizan un cursor opaco i2.*, mientras que status=all utiliza un cursor compuesto opaco a2.* después de la primera página; un cursor numérico solo sigue siendo válido como continuación del flujo heredado de miembros. La búsqueda de usuarios se proporciona en la cabecera de solicitud X-Admin-User-Search para evitar que los correos aparezcan en URL o registros de acceso. limit tiene un valor predeterminado de 50 y un máximo de 100; la lista de usuarios admite status=all|members|invitations. Trata todos los cursores devueltos como opacos y devuélvelos sin cambios.

La creación directa de usuarios no crea una contraseña, una identidad de inicio de sesión ni una sesión. Solo vincula un cliente ya registrado. Utiliza el endpoint de invitaciones para un correo desconocido. El usuario de sistema protegido de Tagless no se puede modificar mediante estas rutas.

Ejemplos

Establece los valores en la consola sin imprimir el token:

export ADMIN_API_BASE_URL="https://api.example.com"
export WORKSPACE_TOKEN="<read from secret manager>"

Listar emplazamientos:

curl --fail-with-body \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  "${ADMIN_API_BASE_URL}/v2/admin/sites"

Crea un emplazamiento de forma segura:

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: site-main-depot-v1" \
  --data '{
    "name":"Main depot",
    "description":null,
    "addressLine1":"1 Example Street",
    "addressLine2":null,
    "postalCode":"LV-1001",
    "city":"Riga",
    "state":null,
    "countryId":1,
    "timezoneId":1,
    "latitude":56.9496,
    "longitude":24.1052
  }' \
  "${ADMIN_API_BASE_URL}/v2/admin/sites"

Descarga un informe CSV para un intervalo UTC explícito:

curl --fail-with-body \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  -o report.csv \
  "${ADMIN_API_BASE_URL}/v2/admin/reports/export?format=csv&from=2026-07-01T00%3A00%3A00Z&to=2026-08-01T00%3A00%3A00Z"

Exclusiones deliberadas

La API de tokens de espacios de trabajo no expone operaciones que requieran una identidad humana o autoridad más amplia. Entre ellas:

• crear, mostrar, rotar o revocar tokens mediante otro token;
• inicio de sesión, restablecimiento de contraseña, sesiones, delegación de roles o privilegios humanos y cambios de propiedad de espacios de trabajo;
• creación/eliminación de espacios de trabajo y pertenencia a cuentas de facturación;
• ajustes de pago, alta en Stripe, planes, facturas y facturación del host;
• operaciones de soporte de todo el host y webhooks de proveedores;
• notificaciones a personas, redirecciones de navegación, recursos de marca y rutas de desarrollo/prueba.