API Documentation

Push charging sessions from local wallboxes or third-party systems

Introduction

ChargeReport offers a REST API for pushing charging sessions from local wallboxes or third-party systems. If your wallbox does not support a cloud connection or OCPP, you can use the Push API to send charging data directly to ChargeReport.

Base URL: https://chargereport.app

All requests and responses use JSON. Timestamps must be in ISO 8601 format with timezone offset.

Authentication

All API requests require a Bearer token. Generate an API key in your dashboardunder Settings → API Keys.

Include the key in the Authorization header:

Authorization: Bearer cr_live_abc123...

Keep your API key secret. Do not expose it in client-side code or public repositories.

POST /api/gateway/sessions

Push one or more charging sessions to ChargeReport. Duplicate sessions (same timestamps and energy) are automatically detected and skipped.

Headers

Header	Value
Authorization	Bearer {api_key}
Content-Type	application/json

Request Body

json

{
  "sessions": [
    {
      "carConnected": "2026-04-14T18:30:00+02:00",
      "carDisconnected": "2026-04-14T06:45:00+02:00",
      "kiloWattHours": 32.5
    }
  ]
}

Field	Type	Description
sessions	array	Array of charging session objects (required)
sessions[].carConnected	string	ISO 8601 timestamp when the car was plugged in
sessions[].carDisconnected	string	ISO 8601 timestamp when the car was unplugged
sessions[].kiloWattHours	number	Energy consumed in kWh (up to 1 decimal)

Response

200 OK

json

{
  "accepted": 1,
  "duplicates": 0
}

Error Codes

Code	Status	Description
AUTH_HEADER_MISSING	401	Authorization header is not present
INVALID_API_KEY	401	The API key is invalid or has been revoked
SESSIONS_ARRAY_REQUIRED	400	Request body must contain a sessions array
MAX_SESSIONS_EXCEEDED	400	More than 100 sessions in a single request

OCPP 1.6J Gateway

For wallboxes that support OCPP 1.6J, ChargeReport provides a WebSocket-based OCPP gateway. No software installation is needed — simply enter the connection URL in your wallbox settings.

Connection URL

wss://ocpp.chargereport.app/cp/{connection_token}

Generate a connection token in your dashboardunder Settings → OCPP Gateway.

Protocol

OCPP 1.6J over WebSocket (RFC 6455). The gateway acts as a Central System.

Supported Messages

Message	Direction	Description
BootNotification	CP → CS	Wallbox registers with the gateway
Heartbeat	CP → CS	Keep-alive signal
StartTransaction	CP → CS	Charging session begins
StopTransaction	CP → CS	Charging session ends, energy value recorded
MeterValues	CP → CS	Periodic energy meter readings during a session

Setup

Generate a connection token in the ChargeReport dashboard.
Open your wallbox admin panel or app.
Find the OCPP / backend settings.
Enter the URL: wss://ocpp.chargereport.app/cp/YOUR_TOKEN
Save and reboot the wallbox. It will connect automatically.

Code Examples

cURL

bash

curl -X POST https://chargereport.app/api/gateway/sessions \
  -H "Authorization: Bearer cr_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "sessions": [
      {
        "carConnected": "2026-04-14T18:30:00+02:00",
        "carDisconnected": "2026-04-14T06:45:00+02:00",
        "kiloWattHours": 32.5
      }
    ]
  }'

Python

python

import requests

response = requests.post(
    "https://chargereport.app/api/gateway/sessions",
    headers={
        "Authorization": "Bearer cr_live_abc123...",
        "Content-Type": "application/json",
    },
    json={
        "sessions": [
            {
                "carConnected": "2026-04-14T18:30:00+02:00",
                "carDisconnected": "2026-04-14T06:45:00+02:00",
                "kiloWattHours": 32.5,
            }
        ]
    },
)

data = response.json()
print(f"Accepted: {data['accepted']}, Duplicates: {data['duplicates']}")

Node.js

javascript

const response = await fetch(
  "https://chargereport.app/api/gateway/sessions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer cr_live_abc123...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sessions: [
        {
          carConnected: "2026-04-14T18:30:00+02:00",
          carDisconnected: "2026-04-14T06:45:00+02:00",
          kiloWattHours: 32.5,
        },
      ],
    }),
  }
);

const data = await response.json();
console.log(`Accepted: ${data.accepted}, Duplicates: ${data.duplicates}`);

Rate Limits

Limit	Value
Requests per hour	100 per API key
Sessions per request	100 max

If you exceed the rate limit, the API returns 429 Too Many Requests. Wait until the next hour window before retrying.

Get your API key

Create a free account and generate an API key in your dashboard to start pushing charging sessions.