AskaCharge — Documentación técnica (API, OCPP, Hub/Roaming)

¿Buscas qué resuelve AskaCharge para tu hotel, restaurante, camping o flota, no cómo conectarte por API? Esta página es la referencia técnica para devs/integradores — la versión para negocios está en AskaCharge por sector.

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

Dashboard de AskaCharge: KPIs de energía, facturación, margen y sesiones, gráfico de uso diario y estado de cargadores en tiempo real — Dashboard de marca — KPIs, uso diario y estado de cargadores en tiempo real.

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

Rol	Alcance
`superadmin`	Gestión global de marcas y del Hub
`brand_admin`	Control total de su marca, incluida facturación y equipo
`brand_technician`	Operación de la marca (cargadores, tarifas, incidencias) sin acceso a facturación ni equipo
`brand_viewer`	Solo lectura: dashboard, tarifas y clientes, sin importes
conductor del portal	Cliente final autenticado en `/portal/{slug}/`
conductor anónimo	Pago por QR sin cuenta, en `/qr/{charge_point_id}`

API REST por dominio

Resumen de los grupos de endpoints principales (no exhaustivo):

Prefijo	Qué cubre
`/api/auth`	Login, registro, 2FA (TOTP)
`/api/brand`	Cargadores, tarifas, clientes, RFID, dashboard, incidencias, OCPI, webhooks, comandos OCPP avanzados
`/api/brand/team`	Gestión de equipo: invitar, listar, cambiar rol, eliminar
`/api/admin`	Superadmin: marcas, facturas, Hub
`/api/portal`	Portal del conductor: login, sesiones, wallet, suscripciones, tarjeta guardada
`/api/public`	Endpoints públicos: pago QR, info de cargador, mapa
`/api/hub`	Estadísticas y gestión del Hub de roaming
`/api/ext`	API pública para integraciones externas, autenticada con API key
`/ocpi/{brand_slug}`	OCPI 2.2 — CPO por marca
`/ocpi/emsp/{brand_slug}`	OCPI 2.2 — eMSP por marca
`/ocpi/hub`	OCPI 2.2 del Hub como partido único `ES*ACH`

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/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.

Mensajes soportados (1.6J): BootNotification, Heartbeat, Authorize, StartTransaction, MeterValues, StopTransaction, StatusNotification, y comandos avanzados (GetConfiguration, ChangeConfiguration, RemoteStartTransaction, RemoteStopTransaction, Reset, GetDiagnostics, UpdateFirmware, SetChargingProfile, ReserveNow, SendLocalList, InstallCertificate...). OCPP 2.0.1 añade GetVariables/SetVariables, GetBaseReport, ChangeAvailability y actualización segura de firmware.

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.

Panel de Roaming OCPI del Hub AskaCharge: miembros, cargadores y sesiones totales de la red, balance por cobrar como CPO y por pagar como eMSP — Pestaña Hub del panel de roaming — miembros, cargadores y balance de settlement.

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. Evento incluido: session.stopped (entre otros), con energía, importe, CO₂ ahorrado y motivo de parada.

API keys para integraciones externas

Alternativa a JWT para integraciones servidor-a-servidor: claves con alcance (scopes) por marca, gestionadas desde /api/brand/api-keys (hash SHA-256 en BD, el valor en claro solo se muestra una vez al crearla). Endpoints públicos disponibles con API key:

Endpoint	Qué devuelve
`GET /api/ext/chargers`	Cargadores de la marca y su estado
`GET /api/ext/sessions`	Sesiones de carga

Enlaces relacionados

Mapa público de cargadores	Cobertura en tiempo real, sin login
Hub AskaCharge	Red de roaming entre operadores, estadísticas en vivo
Crear cuenta	30 días de prueba gratuita