askacharge 0.1.0

Official Python SDK for the askacharge.com EV charging platform API — chargers, charging sessions and webhook signature verification.

askacharge — Python SDK

Official Python SDK for the askacharge.com API.

askacharge.com is a multi-tenant, white-label EV charge point management system (CSMS) built on open standards — OCPP 1.6J and 2.0.1 for chargers, OCPI 2.2 (CPO + eMSP) for roaming — with flat pricing (€20/month, unlimited chargers), QR payments without an app, Spanish tax-compliant invoicing (Verifactu / TicketBAI) and its own roaming hub (ES*ACH).

This SDK covers the external REST API (chargers and charging sessions) and verification of signed webhooks. Zero dependencies — Python standard library only.

Installation

pip install askacharge

Requires Python 3.9+.

Authentication

Create an API key in the askacharge.com dashboard (Settings → API keys). Keys look like ask_live_... and carry scopes (chargers:read, sessions:read).

from askacharge import AskaCharge

client = AskaCharge(api_key="ask_live_...")

White-label deployment on your own domain? Point the client at it:

client = AskaCharge(api_key="ask_live_...", base_url="https://charging.yourbrand.com/api")

Chargers

for charger in client.chargers.list():
    print(charger["id"], charger["status"], charger["location"])

Each charger: {"id", "status", "location", "lat", "lng"} — status is the live OCPP status (Available, Charging, Faulted, ...).

Charging sessions

sessions = client.sessions.list(limit=100)  # newest first, API caps at 200
for s in sessions:
    print(s["start_time"], s["energy_kwh"], "kWh", s["revenue"], "EUR")

Each session: {"id", "id_tag", "status", "energy_kwh", "revenue", "start_time", "stop_time", "co2_saved_g"}.

Webhooks

askacharge.com signs every outgoing webhook with HMAC-SHA256. The signature arrives in the X-AskaCharge-Signature header (sha256=<hex>), the event name in X-AskaCharge-Event, and the payload is {"event", "timestamp", "data"}. Verify against the raw request body:

from askacharge import webhooks, SignatureVerificationError

# FastAPI example
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

@app.post("/my-webhook")
async def handle(request: Request):
    body = await request.body()
    signature = request.headers.get("X-AskaCharge-Signature", "")
    try:
        event = webhooks.construct_event(body, signature, secret="whsec-from-dashboard")
    except SignatureVerificationError:
        raise HTTPException(status_code=400, detail="Bad signature")
    if event["event"] == "session.stopped":
        print("Charged", event["data"])
    return {"ok": True}

Or just the boolean check: webhooks.verify_signature(body, signature, secret).

Error handling

from askacharge import AskaCharge, AuthenticationError, ScopeError, APIError

try:
    client.sessions.list()
except AuthenticationError:   # invalid or expired API key (401)
    ...
except ScopeError:            # key lacks sessions:read (403)
    ...
except APIError as e:         # anything else
    print(e.status_code, e.body)

Links

• Platform: askacharge.com
• Technical documentation (REST API, OCPP, OCPI, webhooks): askacharge.com/askacharge/docs.html
• Support: [e-mail]

---

En español

SDK oficial de Python para la API de askacharge.com, la plataforma de gestión de cargadores de vehículos eléctricos: CSMS multi-marca con OCPP 1.6J/2.0.1, roaming OCPI 2.2, pago por QR sin app y facturación fiscal española (Verifactu/TicketBAI) de serie, por €20/mes con cargadores ilimitados.

from askacharge import AskaCharge

client = AskaCharge(api_key="ask_live_...")
print(client.chargers.list())    # tus cargadores con estado OCPP en vivo
print(client.sessions.list())    # últimas sesiones de carga

La API key se crea en el panel de askacharge.com (Configuración → API keys). Documentación completa en askacharge.com/askacharge/docs.html.

License

MIT