askacharge.com — EV charging network

Lista los cargadores de la marca con su estado OCPP, ubicación y último heartbeat. Empieza por aquí para saber qué hay y qué está caído. En una red grande filtra (estado, q) o pagina (limit, offset) en vez de traerla entera; para solo contar, el recuento está en GET /api/brand/charge-points/resumen.

{
  "type": "object",
  "properties": {
    "estado": {
      "type": "string",
      "enum": [
        "online",
        "offline",
        "charging",
        "available",
        "faulted",
        "pending",
        "simulated"
      ],
      "description": "online/offline = WebSocket abierto ahora o no; pending = conectó sin alta"
    },
    "q": {
      "type": "string",
      "description": "Busca en identificador, ubicación, fabricante y modelo"
    },
    "limit": {
      "type": "integer",
      "description": "Como mucho N cargadores (1-500). Sin limit, todos"
    },
    "offset": {
      "type": "integer",
      "description": "Saltar los N primeros (para la página siguiente)"
    }
  },
  "required": []
}

Detalle de un cargador concreto: conectores, potencia, modo de acceso y estado.

{
  "type": "object",
  "properties": {
    "charge_point_id": {
      "type": "string",
      "description": "Identificador de fábrica, p. ej. CP001"
    }
  },
  "required": [
    "charge_point_id"
  ]
}

Foto del momento: cargadores conectados, sesiones activas y potencia que se está entregando ahora mismo. Para diagnosticar, mejor esto que el histórico.

{
  "type": "object",
  "properties": {},
  "required": []
}

Devuelve los KPIs agregados de un periodo —energía, facturado, margen neto, sesiones y clientes— y la variación respecto al periodo anterior. Solo lee, no cambia nada. Para el detalle sesión a sesión usa askacharge_listar_sesiones; para lo que está pasando ahora mismo, askacharge_estado_en_vivo.

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "enum": [
        "today",
        "week",
        "month",
        "year"
      ],
      "description": "Periodo que se agrega: today (por defecto), week desde el lunes, month desde el día 1, year desde enero"
    }
  },
  "required": []
}

Historial de sesiones de carga con energía, ingresos y coste. Úsalo para analizar consumo, facturación o detectar cargas anómalas.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Cuántas devolver (por defecto 50)"
    }
  },
  "required": []
}

Incidencias abiertas por cargador (averías reportadas).

{
  "type": "object",
  "properties": {},
  "required": []
}

Lista los grupos de tarifa de la marca —por kWh, por hora, por sesión, combinado, margen sobre PVPC o mercado, por franjas horarias (con sus periods), coste de la luz + margen o gratis— con su precio, y la tarifa por defecto en primer lugar. Solo lee, no cambia nada. Para crear una nueva usa askacharge_crear_tarifa; para el precio horario del mercado, askacharge_precio_pvpc_hoy.

{
  "type": "object",
  "properties": {},
  "required": []
}

Precio PVPC hora a hora de hoy (mercado regulado español). Úsalo para decidir cuándo conviene cargar o para fijar un margen sobre el precio real.

{
  "type": "object",
  "properties": {},
  "required": []
}

Lista los clientes activos de la marca con su tarifa asignada y su consumo del mes. Solo lee, no cambia nada; devuelve todos de una vez (sin filtros ni paginación) y deja fuera a los dados de baja. Para dar de alta uno nuevo usa askacharge_crear_cliente; para sus cargas, askacharge_listar_sesiones.

{
  "type": "object",
  "properties": {},
  "required": []
}

Límite de kW por ubicación y estrategia de reparto. Consúltalo antes de arrancar cargas en sitio con potencia contratada justa.

{
  "type": "object",
  "properties": {},
  "required": []
}

Lista lo que han hecho las API keys de la marca, de lo más reciente a lo más antiguo: escrituras e intentos rechazados, con método, ruta, código de respuesta, IP y duración. Las lecturas correctas NO se registran, y la traza se borra a los 90 días. Solo lee, no cambia nada. Es la herramienta de auditoría de credenciales: para la actividad de carga usa askacharge_listar_sesiones.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Cuántas entradas devolver: 100 por defecto, 500 como máximo"
    },
    "solo_errores": {
      "type": "boolean",
      "description": "Si es true, solo los intentos rechazados (código 400 o superior). Por defecto false"
    },
    "key_id": {
      "type": "string",
      "description": "Id de una API key concreta para ver solo la suya. Por defecto, todas las de la marca"
    }
  },
  "required": []
}

Estado de un comando OCPP por su job_id (lo devuelve cada herramienta que manda un comando). Un comando tiene dos tiempos: la respuesta inmediata es solo el acuse del cargador; el efecto real llega después. Estados: 'acked' = aceptado y esperando el efecto (expected_event dice cuál: session.started tras arrancar, charger.online tras reiniciar, connector.status tras cambiar disponibilidad); 'confirmed' = el efecto llegó (en event); 'timeout' = no llegó en 5-10 minutos, algo falló en el cargador; 'rejected' = el cargador dijo que no; 'failed' = ni se pudo enviar. Sin job_id lista los últimos comandos de la marca. Úsala en vez de repetir el comando: repetirlo es arrancar dos cargas o reiniciar dos veces.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "El job_id devuelto por el comando. Opcional: sin él, los últimos 50"
    },
    "charge_point_id": {
      "type": "string",
      "description": "Filtrar la lista por cargador (solo sin job_id)"
    }
  },
  "required": []
}

Arranca una carga en remoto (OCPP RemoteStartTransaction). El cargador debe estar conectado y el id_tag autorizado en la marca. CUIDADO: entrega energía real y genera un cobro.

{
  "type": "object",
  "properties": {
    "charge_point_id": {
      "type": "string",
      "description": "Identificador de fábrica del cargador, p. ej. CP001"
    },
    "id_tag": {
      "type": "string",
      "description": "Tag RFID autorizado con el que se factura la sesión. Opcional: sin él se usa la tarjeta interna PANEL de la marca"
    },
    "connector_id": {
      "type": "integer",
      "description": "Conector, 1 por defecto"
    }
  },
  "required": [
    "charge_point_id"
  ]
}

Para una carga en curso (OCPP RemoteStopTransaction). CUIDADO: corta la carga de un conductor que puede estar esperándola.

{
  "type": "object",
  "properties": {
    "charge_point_id": {
      "type": "string",
      "description": "Identificador de fábrica del cargador, p. ej. CP001"
    },
    "transaction_id": {
      "type": "integer",
      "description": "Id OCPP de la sesión en curso. Opcional: si se omite, se para la sesión activa del cargador"
    }
  },
  "required": [
    "charge_point_id"
  ]
}

Reinicia el cargador (OCPP Reset). 'Soft' reinicia el software y 'Hard' es un corte completo. Deja el punto fuera de servicio unos minutos y aborta las sesiones en curso: comprueba antes que no haya ninguna activa.

{
  "type": "object",
  "properties": {
    "charge_point_id": {
      "type": "string",
      "description": "Identificador de fábrica del cargador, p. ej. CP001"
    },
    "reset_type": {
      "type": "string",
      "enum": [
        "Soft",
        "Hard"
      ],
      "description": "Hard por defecto"
    }
  },
  "required": [
    "charge_point_id"
  ]
}

Pone un cargador operativo o fuera de servicio (OCPP ChangeAvailability). Úsalo para retirar de servicio un punto averiado sin desconectarlo.

{
  "type": "object",
  "properties": {
    "charge_point_id": {
      "type": "string",
      "description": "Identificador de fábrica del cargador, p. ej. CP001"
    },
    "operational_status": {
      "type": "string",
      "enum": [
        "Operative",
        "Inoperative"
      ],
      "description": "Operative lo devuelve al servicio; Inoperative lo retira sin desconectarlo"
    }
  },
  "required": [
    "charge_point_id",
    "operational_status"
  ]
}

Libera el bloqueo del cable en un conector (OCPP UnlockConnector). Es lo que hay que mandar cuando un conductor no puede sacar el cable al terminar. Si hay sesión en curso, el cargador la para antes. Devuelve Unlocked, UnlockFailed o NotSupported; para un conector que sigue en Faulted, usa askacharge_reiniciar_cargador.

{
  "type": "object",
  "properties": {
    "charge_point_id": {
      "type": "string",
      "description": "Identificador de fábrica del cargador, p. ej. CP001"
    },
    "connector_id": {
      "type": "integer",
      "description": "Conector a desbloquear, 1 por defecto"
    }
  },
  "required": [
    "charge_point_id"
  ]
}

Pide al cargador que envíe ya un mensaje concreto (OCPP TriggerMessage): StatusNotification para refrescar el estado del conector, Heartbeat para comprobar que responde, MeterValues para una lectura del contador. Úsalo tras un comando para verificar el resultado sin esperar al siguiente latido. No cambia nada en el cargador; el estado nuevo llega por webhook connector.status y se ve en askacharge_ver_cargador.

{
  "type": "object",
  "properties": {
    "charge_point_id": {
      "type": "string",
      "description": "Identificador de fábrica del cargador, p. ej. CP001"
    },
    "requested_message": {
      "type": "string",
      "enum": [
        "StatusNotification",
        "Heartbeat",
        "MeterValues",
        "BootNotification",
        "FirmwareStatusNotification",
        "DiagnosticsStatusNotification"
      ],
      "description": "Mensaje que se pide; StatusNotification por defecto"
    },
    "connector_id": {
      "type": "integer",
      "description": "Conector concreto; si se omite, el cargador entero"
    }
  },
  "required": [
    "charge_point_id"
  ]
}

Pide al cargador que suba su fichero de diagnóstico (OCPP GetDiagnostics). Es el primer paso razonable ante un cargador que falla y no dice por qué.

{
  "type": "object",
  "properties": {
    "charge_point_id": {
      "type": "string",
      "description": "Identificador de fábrica del cargador, p. ej. CP001"
    }
  },
  "required": [
    "charge_point_id"
  ]
}

Da de alta un cargador. El charge_point_id es el identificador de fábrica y solo tiene que ser único dentro de esta marca. Tras crearlo, el cargador debe apuntar su OCPP a wss://askacharge.com/askacharge/ocpp/{slug}/{charge_point_id}.

{
  "type": "object",
  "properties": {
    "charge_point_id": {
      "type": "string",
      "description": "Identificador de fábrica del cargador, p. ej. CP001. Único dentro de la marca"
    },
    "location_name": {
      "type": "string",
      "description": "Ubicación donde está instalado. Es lo que acota una API key limitada por sitio"
    },
    "latitude": {
      "type": "number",
      "description": "Latitud en grados decimales, para el mapa público"
    },
    "longitude": {
      "type": "number",
      "description": "Longitud en grados decimales, para el mapa público"
    },
    "num_connectors": {
      "type": "integer",
      "description": "Cuántas mangueras tiene el equipo (1 si no se indica)"
    }
  },
  "required": [
    "charge_point_id"
  ]
}

Da de alta cargadores simulados en la marca para probar sin hardware: conectan por OCPP en menos de un minuto, laten, cargan solos unas veces al día y responden a todos los comandos (un Reset los desconecta de verdad 20 s y vuelven). Cada uno trae una tarjeta RFID <PREFIJO>-TARJETA-nn. Máximo 10 por marca; si ya están todos devuelve 409. Se quitan con DELETE /api/brand/sandbox (askacharge_llamar_api). Úsalo para ensayar comandos y webhooks antes de tocar un cargador real.

{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "description": "Cuántos crear, 1-10; 5 por defecto"
    },
    "location_name": {
      "type": "string",
      "description": "Ubicación que se les asigna; 'Aparcamiento de pruebas' por defecto"
    }
  },
  "required": []
}

Crea un grupo de tarifa y devuelve el grupo creado con su id. Rellena solo el precio del modo elegido: per_kwh usa price_per_kwh, per_hour usa price_per_hour, per_session usa price_per_session, combined suma los de kWh y hora, pvpc_margin suma pvpc_margin al PVPC (solo España), market_margin suma pvpc_margin al mercado diario de la zona de la marca (solo zonas con precio y marcas que cobran en EUR; si no, 400), tou cobra por franjas horarias que defines en periods (hora local de la marca; price_per_kwh es el precio de las horas sin franja), cost_plus suma pvpc_margin a lo que le cuesta la luz a la marca en cada momento (exige haberlo configurado) y free no cobra nada. Los modos que cambian con la hora cobran cada kWh a su precio. CUIDADO: con is_default en true, la que fuera tarifa por defecto deja de serlo. Para ver las que ya existen, askacharge_listar_tarifas.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Nombre del grupo, el que se ve en el panel"
    },
    "billing_mode": {
      "type": "string",
      "enum": [
        "per_kwh",
        "per_hour",
        "per_session",
        "combined",
        "pvpc_margin",
        "market_margin",
        "tou",
        "cost_plus",
        "free"
      ],
      "description": "Cómo se cobra la sesión; decide cuál de los precios de abajo se usa"
    },
    "price_per_kwh": {
      "type": "number",
      "description": "€ por kWh entregado (modos per_kwh y combined)"
    },
    "price_per_hour": {
      "type": "number",
      "description": "€ por hora conectado (modos per_hour y combined)"
    },
    "price_per_session": {
      "type": "number",
      "description": "€ fijos por sesión (modo per_session)"
    },
    "pvpc_margin": {
      "type": "number",
      "description": "Margen por kWh sobre el PVPC (pvpc_margin), el mercado diario (market_margin) o el coste de la luz de la marca (cost_plus)"
    },
    "periods": {
      "type": "array",
      "description": "Solo tou: franjas {period_type: valley|flat|peak, price_per_kwh, hour_start 'HH:MM', hour_end 'HH:MM' (igual = todo el día), weekdays '12345' (1=lunes; vacío = todos)}",
      "items": {
        "type": "object"
      }
    },
    "is_default": {
      "type": "boolean",
      "description": "Si es true, pasa a ser la tarifa por defecto de la marca y la anterior deja de serlo"
    }
  },
  "required": [
    "name",
    "billing_mode"
  ]
}

Da de alta un cliente y devuelve el creado con su id. NO comprueba duplicados: dos llamadas con el mismo email crean dos clientes, así que mira antes askacharge_listar_clientes. Si no le pasas tariff_group_id, el cliente hereda la tarifa por defecto de la marca. Para autorizarle una tarjeta física, después: askacharge_crear_tag_rfid.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Nombre del cliente. Es el único obligatorio"
    },
    "email": {
      "type": "string",
      "description": "Correo de contacto, al que se le mandan las facturas"
    },
    "phone": {
      "type": "string",
      "description": "Teléfono de contacto"
    },
    "company": {
      "type": "string",
      "description": "Razón social, si factura a nombre de una empresa"
    },
    "client_type": {
      "type": "string",
      "enum": [
        "individual",
        "fleet",
        "community"
      ],
      "description": "individual por defecto; fleet para flotas con factura mensual; community para comunidades"
    },
    "tariff_group_id": {
      "type": "string",
      "description": "Id de un grupo de tarifa que ya exista (askacharge_listar_tarifas)"
    }
  },
  "required": [
    "name"
  ]
}

Autoriza un tag RFID en la marca. Sin esto, la tarjeta no puede arrancar cargas. El id_tag es único dentro de la marca.

{
  "type": "object",
  "properties": {
    "id_tag": {
      "type": "string",
      "description": "Código que la tarjeta manda al cargador. Único dentro de la marca"
    },
    "user_name": {
      "type": "string",
      "description": "A quién se le entrega la tarjeta, para reconocerla luego"
    },
    "client_id": {
      "type": "string",
      "description": "Id del cliente al que se le factura lo que cargue esta tarjeta (askacharge_listar_clientes)"
    }
  },
  "required": [
    "id_tag"
  ]
}

Llama a cualquier endpoint de la API de la marca, para lo que no cubran las herramientas anteriores. El contrato completo (456 operaciones) está en https://askacharge.com/askacharge/openapi.json. Los permisos se comprueban igual que en el resto: la clave necesita el scope de ese recurso. Solo valen rutas bajo /api/brand y /api/ext.

{
  "type": "object",
  "properties": {
    "metodo": {
      "type": "string",
      "enum": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "description": "Verbo HTTP. GET necesita el scope de lectura del recurso; el resto, el de escritura"
    },
    "ruta": {
      "type": "string",
      "description": "Ruta completa, p. ej. /api/brand/webhooks"
    },
    "cuerpo": {
      "type": "object",
      "description": "Cuerpo JSON para POST y PUT"
    }
  },
  "required": [
    "metodo",
    "ruta"
  ]
}