Arquitectura general

AskaCharge es una plataforma SaaS multi-tenant de gestión de cargadores de vehículos eléctricos (CSMS — Charging Station Management System). Backend en FastAPI (Python, async) con WebSocket nativo para OCPP, base de datos PostgreSQL, y frontend en React. Cada marca (brand) gestiona su propia flota de cargadores, tarifas, clientes y facturación de forma aislada, bajo un mismo despliegue.

Soporta OCPP 1.6J y OCPP 2.0.1 en el mismo servidor, testado con el OCTT (OCPP Compliance Testing Tool) de la Open Charge Alliance. La URL base de la API y el WebSocket es:

https://askacharge.com/askacharge

Autenticación y roles

Autenticación por JWT (Bearer token), obtenido vía POST /api/auth/login (OAuth2 password flow: username + password en form-data). El access token expira a los 30 minutos; hay refresh token (cookie httpOnly) para renovarlo sin volver a hacer login.

Capas de usuario

API REST por dominio

Resumen de los grupos de endpoints principales. La lista completa y siempre al día —456 operaciones sobre 379 rutas— se publica como OpenAPI 3.1 en /askacharge/openapi.json, con visor en /askacharge/docs. No hay ninguna operación del panel que no esté ahí: la interfaz web consume exactamente esta misma API.

Integración OCPP (cargadores)

Conexión por WebSocket, un cargador por conexión. El charge point debe estar pre-registrado en la marca antes de conectar.

wss://askacharge.com/askacharge/ocpp/{brand_slug}/{charge_point_id}

Subprotocolo negociado vía cabecera Sec-WebSocket-Protocol: ocpp1.6 o ocpp2.0.1.

Seguridad (Security Profile 2)

Opcionalmente, cada cargador puede tener una credencial Basic Auth asociada (usuario = charge_point_id, contraseña generada por el operador desde el panel — sección "Seguridad OCPP" de cada cargador). Si está activada, el handshake exige cabecera Authorization: Basic base64(charge_point_id:password) y se rechaza la conexión sin ella o con credenciales incorrectas. Si no está activada, se acepta la conexión solo por el charge_point_id de la URL — recomendamos activarla en todo cargador expuesto a internet.

Plug & Charge (ISO 15118)

Plug & Charge permite que un vehículo eléctrico se autentique y autorice una sesión de carga automáticamente al enchufar el cable, sin RFID, app ni QR. La autenticación se negocia entre el cargador y el vehículo por la propia línea de potencia (PLC) mediante el estándar ISO 15118-2.

Requiere cargadores con OCPP 2.0.1 y soporte ISO 15118 en el hardware. Los cargadores OCPP 1.6J no pueden participar en este flujo.

PKI por marca — CA propia

Cada marca genera su propia Root CA EC P-256 (V2G Root CA simplificada, válida 10 años) desde el panel o vía API. Esta CA firma los certificados de contrato de los vehículos de flota, y debe instalarse en los cargadores para que puedan validarlos.

Certificados de contrato (eMAID)

Para cada vehículo de flota se emite un certificado de contrato ligado a su eMAID (Electric Mobility Account ID, formato ES-ACH-XXXXXXXXXX-C). El vehículo lo almacena y lo presenta al cargador en cada sesión. AskaCharge lo entrega automáticamente vía Get15118EVCertificate OCPP si el cargador lo solicita.

Flujo OCPP 2.0.1

Cuando un vehículo compatible se enchufa, el cargador abre una sesión ISO 15118 y envía un mensaje Authorize con id_token.type = "ISO15118" y el campo iso15118CertificateHashData. AskaCharge verifica el eMAID en la tabla de contratos activos y valida el hash del certificado para prevenir suplantación. Si el vehículo no tiene aún el certificado descargado, el cargador solicita Get15118EVCertificate y AskaCharge responde con la cadena (contrato + CA) en formato EXI/DER.

Vehículos de mercado general (no flota)

Los coches de consumidor (IONIQ 6, BMW iX, etc.) vienen de fábrica con un certificado de contrato firmado por una CA raíz reconocida por los fabricantes — principalmente Hubject eMobility PKI en Europa. Para autorizar a esos conductores, AskaCharge tendría que conectarse a esa PKI externa, lo que requiere contrato con Hubject y está en hoja de ruta pero no activo aún.

Hoy, Plug & Charge en AskaCharge funciona para flota propia: vehículos cuyos eMAID hayas emitido tú como operador. Para el resto de conductores se recomienda combinar con RFID, pago QR o portal del conductor.

Smart Charging & Energía

AskaCharge gestiona la potencia de carga de forma dinámica en tres niveles independientes que se pueden combinar: reparto de potencia por ubicación, reglas condicionales basadas en producción solar o precio de la energía, y perfiles de carga OCPP por cargador. Todo se aplica en tiempo real sin intervención del operador.

Reparto de potencia por ubicación (SPL / load balancing)

Cada ubicación puede tener un límite de potencia máxima (kW). AskaCharge reparte ese techo entre los cargadores activos enviando SetChargingProfile (OCPP 1.6J y 2.0.1) automáticamente cuando arranca o para una sesión. Estrategias disponibles: even (igual para todos) y priority (prioridad por cargador). Esto permite instalar cargadores sin ampliar la acometida eléctrica.

Integración solar

El operador configura su instalación fotovoltaica (potencia pico, batería opcional, excedente mínimo para activar carga) y publica lecturas en tiempo real desde su inversor o contador. AskaCharge calcula el excedente disponible y lo usa en el motor de reglas.

Motor de reglas de carga

El operador define reglas priorizadas que se evalúan cada 5 minutos contra el estado actual (excedente solar, hora, precio de energía). La primera regla que cumple su condición aplica su acción vía ChangeConfiguration OCPP a todos los cargadores activos de la marca.

POST /api/brand/solar/rules
{
  "name": "Solo excedente solar",
  "priority": 10,
  "condition_type": "surplus_min",
  "condition_value": { "watts": 1500 },
  "action": "charge_solar_only"
}

Tarifas de energía dinámicas

El motor de reglas puede operar con tres fuentes de precio de la red:

• PVPC — precios horarios de REE ESIOS, actualizados automáticamente cada hora. Disponibles en GET /api/brand/pvpc/today.
• OMIE — precio mayorista del mercado diario (spot), con margen configurable por marca.
• Tarifa fija — precio constante definido por el operador.

La condición pvpc_max en las reglas de carga permite, por ejemplo, cargar solo cuando la energía cuesta menos de 0,10 €/kWh y pausar en horas punta — sin ninguna intervención manual.

Analítica y reporting

La plataforma ofrece dashboards en tiempo real, analítica histórica con comparativa de periodos, previsión financiera mensual, ranking de rendimiento por cargador, informes ESG exportables en PDF y detección automática de anomalías mediante IA. Todos los datos son accesibles vía API para integración con BI externos.

Dashboard operacional

Analítica avanzada

Informe ESG (PDF)

GET /api/brand/esg-report genera un PDF descargable con el impacto ambiental del periodo: kWh entregados, CO₂ evitado (factor 130 g/kWh vs combustión), equivalencia en árboles plantados y desglose por cliente fleet. Listo para incluir en memorias de sostenibilidad corporativa o reporting CSRD.

Detección de anomalías (IA)

Un motor de detección ejecuta cuatro analizadores independientes cada 30 minutos sobre todas las transacciones recientes. Las alertas se almacenan en la tabla anomaly_alerts con severidad y descripción, y se notifican al operador por email.

Hub AskaCharge / roaming OCPI

El Hub AskaCharge es una red de roaming interna entre marcas/operadores que comparten plataforma: una sola integración OCPI da acceso a todos los cargadores de la red, sin necesidad de acuerdos bilaterales individuales. De cara a socios externos (Hubject, GIREVE, ocpi.io...), el Hub se presenta como un único partido OCPI 2.2: ES*ACH.

https://askacharge.com/askacharge/ocpi/hub/versions

Modelo de comisión: 1% por sesión cross-brand, liquidado el día 1 de cada mes. El eMSP cobra al conductor con su tarjeta guardada y AskaCharge transfiere al CPO — sin riesgo de impago entre marcas, porque ambas cuentas de cobro están en la misma plataforma. Solicitudes de membresía externa: POST /api/public/hub/apply, ver también la página del Hub.

Facturación fiscal española

AskaCharge genera y registra facturas en los sistemas tributarios españoles de forma automática, sin configuración adicional por parte del operador más allá de introducir sus datos fiscales en el onboarding. La plataforma detecta el territorio de la marca y aplica el sistema correspondiente.

Verifactu — territorio común (AEAT)

Cada transacción completada genera un registro de factura en formato Verifactu (Real Decreto 1007/2023): XML firmado con la cadena de huellas SHA-256 encadenadas, código QR de validación y envío automático al webservice SOAP de la AEAT. Los registros quedan almacenados con el estado de respuesta de hacienda (aeat_ok, código de error, timestamp). Las facturas rechazadas entran en cola de reintento automático.

TicketBAI — territorios forales

Para operadores de Bizkaia, Gipuzkoa o Araba, la plataforma emite facturas TicketBAI con firma XAdES-EPES usando el certificado digital de la marca. Se envían al endpoint correcto de cada hacienda foral. Bizkaia también soporta el envío mensual agregado vía LROE (Lote de Registros de Operaciones Económicas). El QR TicketBAI se incluye en el PDF de la factura.

Qué se factura

Integración con ERP

Las facturas emitidas se sincronizan opcionalmente con Holded vía API (PUT /api/brand/erp/config). El operador proporciona su API key de Holded y la plataforma envía cada factura en el momento de su generación.

Seguridad

La plataforma implementa seguridad en capas: autenticación robusta con rotación de tokens, 2FA por software, seguridad a nivel de protocolo OCPP, firma de eventos salientes y controles de privacidad GDPR.

Autenticación — JWT + refresh token rotativo

El access token JWT tiene vida de 30 minutos. El refresh token se emite como cookie httpOnly; SameSite=Lax; Secure (nunca accesible desde JavaScript) y se rota en cada uso: al renovar el access token se invalida el refresh anterior y se emite uno nuevo. Si un token ya usado vuelve a presentarse, la plataforma detecta posible robo de sesión y revoca todos los refresh tokens del usuario inmediatamente. Las cookies de la app principal (/app) y del portal de conductores (/portal) son independientes para evitar escalada de privilegios entre capas.

2FA — TOTP (RFC 6238)

Los usuarios brand_admin pueden activar autenticación de dos factores con cualquier app compatible (Google Authenticator, Aegis, 1Password…). El flujo: setup → URI de aprovisionamiento + QR → verificación del primer código → activación con entrega de 8 códigos de respaldo de un solo uso (SHA-256 en BD, valor en claro mostrado una vez). El 2FA se exige en el login si está activo.

OCPP Security Profile 2 — Basic Auth por cargador

Cada cargador puede tener una credencial independiente: usuario = charge_point_id, contraseña generada y rotable desde el panel (hash SHA-256 almacenado, valor en claro mostrado una vez). Si está activada, el handshake WebSocket exige la cabecera Authorization: Basic … y rechaza la conexión sin ella. El endpoint POST /api/brand/chargers/{id}/rotate-password permite rotar la credencial sin tocar la configuración del resto de la flota.

API keys — hash SHA-256, scopes

Las API keys se almacenan exclusivamente como hash SHA-256 — el valor en claro solo se muestra en el momento de creación y nunca se puede recuperar. Cada key lleva un conjunto de scopes de lectura y de escritura que delimitan lo que puede hacer, y toda escritura queda registrada: ver la sección de API keys.

Webhooks — firma HMAC-SHA256

Cada evento saliente incluye la cabecera X-AskaCharge-Signature: sha256=<hex>, calculada con el secreto propio del endpoint (distinto por endpoint, nunca compartido). El receptor puede verificar la autenticidad del evento antes de procesarlo.

Privacidad y GDPR

Para cada cliente fleet el operador puede ejecutar:

V2G y agregación de energía

Vehicle-to-Grid (V2G) permite que los vehículos eléctricos devuelvan energía a la red en momentos de alta demanda o precio elevado, convirtiéndose en baterías distribuidas gestionables. AskaCharge está diseñado para operar como plataforma de agregación V2G en cuanto el hardware lo permita — los estándares, los protocolos y la lógica de despacho ya están en la arquitectura.

Estándares implementados

Motor de despacho — ya operativo

El motor de reglas de Smart Charging (ver sección anterior) está diseñado para despacho bidireccional: las condiciones pvpc_max y time_range ya permiten definir ventanas de descarga ("descarga cuando PVPC > 0,18 €/kWh"), y la acción charge_watts con valor negativo se mapeará a un perfil de descarga OCPP cuando el cargador lo soporte. Los precios PVPC y OMIE spot se actualizan hora a hora desde REE ESIOS — la señal de precio para el despacho ya está disponible en tiempo real.

Rol de agregador (RD 88/2026 — SRAD)

El marco regulatorio español (Real Decreto 88/2026) habilita la figura del Sistema de Respuesta Activa de la Demanda (SRAD): un agregador que agrupa capacidad de flexibilidad distribuida (baterías de VE, solar, bombas de calor) y la ofrece a Red Eléctrica como servicio de balance. AskaCharge está posicionado para operar como SRAD en cuanto:

• Se alcance el volumen mínimo regulatorio (1 MW de capacidad gestionable agregada)
• Se disponga de hardware bidireccional certificado en la flota
• Se complete el registro como agregador independiente ante CNMC/REE (figura habilitada por RD 88/2026, sin necesidad de ser comercializadora)

La plataforma ya agrega métricas de potencia en tiempo real por ubicación (location_limits), conoce el estado de cada cargador y sesión activa, y tiene el canal OCPP para modificar perfiles de carga en segundos — los tres ingredientes del despacho de respuesta de demanda.

AskaCharge como agregador independiente (RD 88/2026)

El Real Decreto 88/2026 crea en España la figura del agregador independiente: una entidad que agrega capacidad de flexibilidad distribuida (baterías de VE, solar, bombas de calor) y la ofrece a Red Eléctrica en los mercados de balance y servicios de ajuste, sin necesidad de ser comercializadora.

AskaCharge está posicionado para registrarse como agregador independiente con una ventaja estructural única: ya controla en tiempo real los cargadores de todas las marcas de la red. Cada operador que se adhiera aporta su capacidad instalada al pool agregado. El umbral regulatorio es de 1 MW — alcanzable agregando varias marcas de la red antes de que cualquier operador individual lo lograra por sí solo.

Para los operadores cliente de AskaCharge, adherirse al pool de agregación supone una nueva línea de ingresos pasivos: sus cargadores siguen funcionando con normalidad, y cuando REE activa una señal de curtailment (reducción de carga), AskaCharge gestiona el despacho automáticamente y les transfiere su parte de la compensación.

V2G: inyección a red y arbitraje dinámico de precio

Con hardware bidireccional, la flota de VEs aparcados puede devolver energía a la red en momentos de demanda pico — un servicio adicional que REE remunera por encima de la disponibilidad. Combinado con el arbitraje de precio, el VE se convierte en un activo financiero para el operador:

Importante: con la alta penetración solar en España, el modelo tradicional "noche barato / día caro" ya no es válido. Los precios PVPC pueden estar en mínimos históricos al mediodía por sobreproducción fotovoltaica (valores por debajo de 2 ct€/kWh son habituales), mientras el pico real de precio se produce en la tarde-noche (19-22h), cuando el sol cae pero la demanda permanece alta. El arbitraje óptimo es valle solar de mediodía → pico de tarde, con spreads que pueden superar el factor 15×.

AskaCharge resuelve esto de forma nativa: los precios PVPC y OMIE spot se actualizan hora a hora desde REE ESIOS y ya están disponibles en el dashboard de cada operador en tiempo real. La condición pvpc_max del motor de reglas evalúa el precio actual en cada decisión de carga — sin asumir patrones fijos de hora, adaptándose automáticamente a la estacionalidad solar.

App del conductor (marketplace)

AskaCharge incluye una experiencia de conductor en tres capas complementarias, sin necesidad de app nativa: mapa público de acceso libre, flujo de carga por QR sin registro, y portal de conductor completo instalable como PWA.

Mapa público — marketplace de carga

Disponible en /mapa sin login. Muestra cargadores AskaCharge y la red nacional REVE/REE en tiempo real. Al hacer clic en un cargador AskaCharge se abre un modal con:

• Estado por conector (hasta 4), con selector visual y color en tiempo real
• Tarifa pública del operador con estimación de coste por hora
• QR generado en el cliente para el conector seleccionado
• Botón "Iniciar carga" directo al flujo de pago

Carga por QR — sin cuenta, sin app

El conductor escanea el QR físico del cargador o el del mapa. El flujo completo:

1. Info del cargador: nombre, estado, tarifa y estimación de coste
2. Pre-autorización Stripe de €50 (Apple Pay / Google Pay / tarjeta) — captura manual del importe exacto
3. Sesión activa en vivo: tiempo transcurrido, kWh cargados, importe acumulado
4. Resumen final con ticket y CO₂ ahorrado

Compatible con todos los modos de tarifa: por kWh, por hora, por sesión, combinado, PVPC dinámico y gratuito. La estimación de coste se muestra antes de confirmar el pago.

Portal del conductor — PWA instalable

Cada operador puede ofrecer un portal de conductor en /portal/{slug}/, instalable como PWA en iOS y Android (sin pasar por App Store). Incluye:

Webhooks salientes

Cada marca puede registrar endpoints HTTP propios para recibir eventos en tiempo real (firmados con HMAC, secreto propio por endpoint) desde /api/brand/webhooks. Eventos: session.started, session.stopped (energía, importe, CO₂ ahorrado y motivo de parada), charger.online (BootNotification: el que cierra un Reset), charger.offline (desconexión o sin latido), connector.status (cada StatusNotification), charger.error (conector en Faulted), payment.captured y anomaly.detected. El catálogo con la descripción de cada uno está en GET /api/brand/webhooks/events. Con esto un agente que manda un comando puede esperar el evento en vez de consultar en bucle.

Sandbox: cargadores simulados

Para probar sin hardware. En Cargadores hay un botón "Añadir 5 cargadores simulados" (o POST /api/brand/sandbox, count 1–10): en menos de un minuto conectan por OCPP, laten, cargan solos unas veces al día en horario de día y responden a todos los comandos como un equipo real — un Reset los desconecta de verdad 20 segundos y vuelven, con su webhook charger.online. Cada uno trae una tarjeta RFID <PREFIJO>-TARJETA-nn. Hasta 10 por marca; se quitan con un clic (DELETE /api/brand/sandbox) con sus sesiones y tarjetas, y los cargadores reales no se tocan. Cuando llegue el equipo real solo cambia la URL OCPP. Vale igual en un trial que en una marca de pago que quiera ensayar una integración o un agente sin tocar su red. Vídeo de dos minutos: prueba askacharge.com sin cargador.

API keys — la credencial de un agente o una integración

Alternativa al JWT para integraciones servidor-a-servidor y para agentes IA. Se gestionan desde /api/brand/api-keys, se guardan como hash SHA-256 y el valor en claro solo se muestra una vez al crearla. Se envían en X-Api-Key o como Authorization: Bearer.

Una API key alcanza lo mismo que el administrador humano de la marca, limitada por los scopes que esa marca le haya concedido. Es una decisión deliberada: la plataforma ofrece todas las opciones y es el operador quien decide cuáles entrega a su agente. Puede empezar por solo lectura y ampliar después, o dar acceso total.

El scope necesario se deduce del recurso y del método: GET pide :read y el resto :write. Escribir incluye leer. Se admiten los comodines * (todo) y familia:*.

El catálogo vivo lo devuelve GET /api/brand/api-keys/scopes, para que un agente pueda consultar qué permisos existen antes de pedirlos.

Cuánto alcanza una API key

De las 456 operaciones de la API, 242 están al alcance de una API key y 214 quedan fuera de su perímetro a propósito: el portal del conductor (52), la superadministración de la plataforma (37), los endpoints OCPI de roaming (37+10), los públicos de pago por QR (18), la autenticación (16) y la facturación interna (19). Esa mitad no es una carencia: son operaciones que un agente de una marca no debe tocar.

Las cifras salen de contar el OpenAPI publicado contra la tabla de permisos, no de una estimación. Puede reproducirlo con openapi.json.

Acotar una key a ubicaciones

En chargers y commands, el scope admite un sufijo con la ubicación: commands:write@hotel-madrid. Un instalador que gestiona varias sedes bajo la misma marca puede así dar a un agente permiso para reiniciar los cargadores de Madrid y no los de Barcelona. Se puede repetir el sufijo para varias ubicaciones en la misma key.

La ubicación es el location_name del cargador, comparado por slug (Parking Norte y parking-norte son la misma). Las ubicaciones reales de su marca las devuelve GET /api/brand/api-keys/scopes, y en el panel salen como botones al elegir los permisos.

Acota sobre qué cargadores puede actuar la key, no lo que puede consultar. Un comando o un alta fuera de sus ubicaciones devuelve 403 diciendo cuáles tiene permitidas; una escritura que no indique charge_point_id ni location_name también se rechaza, porque no se puede comprobar dónde cae. Pero un listado o el panel siguen devolviendo la marca entera: filtrar además la lectura obligaría a recortar el cuerpo de decenas de respuestas distintas, y preferimos no prometer a medias algo de lo que depende la confianza en el permiso.

En las demás familias el sufijo se rechaza al crear la key: una tarifa o una factura no pertenecen a una ubicación. Y una key sin sufijo sigue llegando a toda la marca — manda siempre el permiso más amplio que se le haya concedido.

Reintentos sin duplicados

Cualquier escritura acepta la cabecera Idempotency-Key. Si la petición se repite con la misma clave, se devuelve la respuesta de la primera junto a Idempotent-Replay: true en vez de ejecutarla otra vez. Repetir la clave con un cuerpo distinto devuelve 422, y reintentar mientras la primera sigue en curso devuelve 409. Un agente reintenta por diseño y esto evita que un corte de red duplique un cargador, un cliente o un cobro.

Servidor MCP

Un agente puede conectarse por Model Context Protocol a https://askacharge.com/askacharge/api/mcp, autenticándose con la misma API key (Authorization: Bearer ask_live_… o X-Api-Key). No hay nada que instalar: es HTTP, transporte JSON-RPC 2.0 sobre POST.

Devuelve las herramientas ya descritas —qué hace cada una y cuándo usarla— y solo las que esa key puede ejecutar: si la marca no concedió commands:write, las de arrancar, parar o reiniciar ni siquiera aparecen en la lista. Para lo que no tenga herramienta propia está askacharge_llamar_api, que abre las 456 operaciones con el mismo control de permisos. El filtrado es por familia y acción: una key acotada a ubicaciones sí ve esas herramientas, y es al ejecutarlas sobre un cargador de otra ubicación cuando recibe el 403.

El saludo del protocolo —initialize, ping y tools/list— se responde sin API key, porque es lo que consultan los directorios de MCP y los clientes antes de tener credenciales; sin key se ve el catálogo completo de las 24 herramientas, que es público. Ejecutar cualquiera de ellas sí exige la key, y entonces vuelve a valer todo lo anterior.

El MCP no es una puerta lateral: cada herramienta se ejecuta contra esta misma API REST, así que pasa por los mismos scopes, la misma traza de actividad y el mismo límite de uso.

Traza de actividad

Cada escritura y cada intento rechazado quedan registrados: qué key, qué operación, con qué resultado, desde qué IP y cuánto tardó. Se consulta en el panel, en API keys → Actividad de las keys, o por API con GET /api/brand/api-keys/audit (scope keys:read). Se conserva 90 días. Las consultas correctas no se registran: un agente hace cientos y taparían lo que importa. Un intento con una key que no existe también queda anotado.

Límite de uso

300 peticiones por minuto y key. Al superarlo se responde 429 con Retry-After.

Dónde NO llega una API key

Ni con el comodín *: /api/auth (identidad y contraseñas), /api/admin (superadministración de la plataforma), el portal del conductor y los endpoints OCPI. Ahí devuelve 401. Una key es siempre de una marca y no puede salirse de ella.

Endpoints simplificados

Además de la API completa, hay dos endpoints de conveniencia con formato estable, pensados para integraciones que solo quieren volcar datos:

Enlaces relacionados