Charging Reports

Jak stáhnout historii nabíjecích relací přes API — energie, doba, náklady, RFID karty a tarify, s příklady billingu a exportu do CSV.

Přehled

Charging Reports API umožňuje získat kompletní přehled o všech nabíjecích relacích vašich stanic - dokončených i probíhajících. Získáte informace o spotřebované energii, době nabíjení, nákladech, RFID kartách, tarifech a dalších detailech.

Základní endpointy

Pro získání charging reportů použijte následující endpointy s vašimi API klíči:

1. Reporty podle zařízení

GET /external/charging-reports/device/{deviceId}

2. Reporty podle vlastníka

GET /external/charging-reports/owner/{email}

Interaktivní API Explorer

GET/external/charging-reports/device/{deviceId}

Získat Charging Reports ze zařízení

Získejte historii všech nabíjecích relací z vaší stanice - dokončených i probíhajících. Obsahuje informace o spotřebované energii, době nabíjení, nákladech, RFID kartách a tarifech.

Autentizace

Parametry

deviceId*(path)

ID vašeho zařízení (automaticky se načte seznam vašich zařízení)

startDate(query)

Počáteční datum a čas (ISO 8601 formát)

endDate(query)

Koncové datum a čas (ISO 8601 formát)

order(query)

Řazení výsledků (ASC nebo DESC)

limit(query)

Počet záznamů (default: 100)

offset(query)

Posun pro stránkování (default: 0)

Příklady kódu

curl -X GET "https://cloud.mybox.pro/admin-panel/v1/external/charging-reports/device/{deviceId}" \
  -u "YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Accept: application/json"

Příklad odpovědi

{
  "status": 1,
  "data": [
    {
      "id": 1234567890123456,
      "type": "network",
      "session_id": "047",
      "user_id": "0A896C4E",
      "user_tag_title": "Jan Novák",
      "device_id": "abc1-def2-ghi3-jkl4",
      "device_title": "Nabíječka - Budova A",
      "status": "Finished",
      "site": {
        "id": 9876543210987654,
        "title": "Centrála Praha",
        "address": "Hlavní 123, Praha 110 00"
      },
      "groups": [
        {
          "id": 1111111111111111,
          "title": "Veřejné"
        }
      ],
      "companies": [
        {
          "id": 5555555555555555,
          "title": "EnergyTech s.r.o."
        }
      ],
      "tariffs": [
        {
          "id": 2222222222222222,
          "title": "Management",
          "cost": [
            {
              "start": "00",
              "end": "14",
              "price": 7.7
            },
            {
              "start": "14",
              "end": "24",
              "price": 8.8
            }
          ],
          "currency": "CZK",
          "tag_groups": null,
          "user_tags": null
        }
      ],
      "owner": {
        "id": 3333333333333333,
        "email": "admin@example.com",
        "first_name": "Firma",
        "last_name": "Company Account",
        "color": null
      },
      "cp_status": "Finishing",
      "tags": [],
      "car_status": "F",
      "actual_meter_readings": "121.69",
      "start_meter_readings": "119.90",
      "energy_delivered": "1.79",
      "duration": "30m 36s",
      "charging_time": 1836,
      "connector": 2,
      "odometer": null,
      "price": "0.00",
      "currency": "CZK",
      "cost": "28.64",
      "last_stop_time": null,
      "start_time": "2025-09-15T13:30:40.000Z",
      "end_time": "2025-09-15T14:01:16.000Z",
      "deleted": null,
      "created": "2025-09-15T13:30:42.000Z",
      "updated": "2025-09-15T14:01:22.000Z"
    }
  ],
  "meta": {
    "totalCount": 15
  }
}

Parametry:

deviceId - ID vašeho zařízení (získáte z /external/device)
startDate - Počáteční datum a čas (formát: ISO 8601, např. 2025-09-01T00:00:00Z)
- Default: aktuální čas minus 1 týden
endDate - Koncové datum a čas (formát: ISO 8601, např. 2025-09-30T23:59:59Z)
- Default: aktuální čas
order - Řazení výsledků: ASC nebo DESC (default: DESC)
limit - Počet záznamů (default: 100)
offset - Posun pro stránkování (default: 0)

Struktura odpovědi

API vrací odpověď ve formátu:

{
  "status": 1,
  "data": [ ... ],
  "meta": {
    "totalCount": 15
  }
}

status - 1 = úspěch, 0 = chyba
data - Pole charging reportů
meta.totalCount - Celkový počet záznamů (užitečné pro stránkování)

Struktura charging reportu

Každý charging report obsahuje tyto informace:

{
  "id": 1234567890123456,
  "type": "network",
  "session_id": "047",
  "user_id": "0A896C4E",
  "user_tag_title": "Jan Novák",
  "device_id": "abc1-def2-ghi3-jkl4",
  "device_title": "Nabíječka - Budova A",
  "status": "Finished",
  "site": {
    "id": 9876543210987654,
    "title": "Centrála Praha",
    "address": "Hlavní 123, Praha 110 00",
    "description": "",
    "company_id": 5555555555555555,
    "color": "#989898",
    "created": "2025-06-15T07:26:53.000Z",
    "updated": "2025-06-15T07:29:22.000Z"
  },
  "groups": [
    {
      "id": 1111111111111111,
      "title": "Veřejné",
      "color": "#989898",
      "labels": [],
      "devices": [
        { "identifier": "abc1-def2-ghi3-jkl4" }
      ]
    }
  ],
  "companies": [
    {
      "id": 5555555555555555,
      "title": "EnergyTech s.r.o.",
      "alias": "EnergyTech",
      "parent_company_id": 1,
      "address": "Hlavní 123, 110 00 Praha"
    }
  ],
  "tariffs": [
    {
      "id": 2222222222222222,
      "title": "Management",
      "cost": [
        { "start": "00", "end": "14", "price": 7.7 },
        { "start": "14", "end": "24", "price": 8.8 }
      ],
      "currency": "CZK",
      "timezone": "Europe/Prague",
      "valid_from": null,
      "valid_to": null,
      "tag_groups": null,
      "user_tags": null,
      "devices": [
        { "identifier": "abc1-def2-ghi3-jkl4" }
      ],
      "device_groups": []
    }
  ],
  "labels": [],
  "owner": {
    "id": 3333333333333333,
    "email": "admin@example.com",
    "first_name": "Firma",
    "last_name": "Company Account",
    "color": null
  },
  "cp_status": "Finishing",
  "tags": [],
  "car_status": "F",
  "actual_meter_readings": "121.69",
  "start_meter_readings": "119.90",
  "energy_delivered": "1.79",
  "duration": "30m 36s",
  "charging_time": 1836,
  "connector": 2,
  "odometer": null,
  "price": "0.00",
  "currency": "CZK",
  "cost": "28.64",
  "last_stop_time": null,
  "start_time": "2025-09-15T13:30:40.000Z",
  "end_time": "2025-09-15T14:01:16.000Z",
  "deleted": null,
  "created": "2025-09-15T13:30:42.000Z",
  "updated": "2025-09-15T14:01:22.000Z"
}

Popis polí

Identifikace

Pole	Typ	Popis
`id`	number	Unikátní ID záznamu v databázi
`session_id`	string	ID nabíjecí relace (unikátní v rámci zařízení)
`device_id`	string	Identifikátor nabíjecí stanice
`device_title`	string	Název stanice
`type`	string	Typ relace: `network` (síťová/RFID), `personal` (osobní), `local` (lokální)
`status`	string	`"Finished"` nebo `"In Progress"`

Uživatelské údaje a RFID

Pole	Typ	Popis
`user_id`	string	ID RFID karty (např. `"0A896C4E"`, `"F41682BF"`)
`user_tag_title`	string	Jméno přiřazené k RFID kartě (např. `"Jan Novák"`)
`owner`	object	Vlastník relace (viz struktura níže)

Owner objekt

Pole	Typ	Popis
`owner.id`	number	ID vlastníka
`owner.email`	string	Email vlastníka
`owner.first_name`	string	Jméno
`owner.last_name`	string	Příjmení
`owner.color`	string/null	Barva v UI

Billing podle RFID karet

Pro identifikaci kdo nabíjel použijte kombinaci user_id (číslo RFID karty) a user_tag_title (jméno přiřazené ke kartě). Tato pole umožňují automatizovaný billing energie na konkrétní uživatele.

Časové údaje

Pole	Typ	Popis
`start_time`	ISO 8601	Začátek nabíjení (UTC)
`end_time`	ISO 8601	Konec nabíjení (UTC, `null` u "In Progress")
`duration`	string	Doba nabíjení, lidsky čitelný formát (`"9h 5m 29s"`)
`charging_time`	number	Doba nabíjení v sekundách (strojově čitelné)
`last_stop_time`	ISO 8601/null	Čas posledního přerušení nabíjení

Energetické údaje

Pole	Typ	Popis
`energy_delivered`	string	Dodaná energie v kWh
`start_meter_readings`	string	Stav elektroměru na začátku relace (kWh)
`actual_meter_readings`	string	Stav elektroměru na konci relace (kWh)

Finanční údaje

Pole	Typ	Popis
`cost`	string	Celkové náklady za relaci
`currency`	string	Měna (`CZK`, `EUR`)
`price`	string	Cena za kWh

Stav zařízení a vozidla

Pole	Typ	Popis
`connector`	number	Číslo konektoru (1 nebo 2)
`cp_status`	string	Stav charge pointu (`Charging`, `Finishing`, `Available`, ...)
`car_status`	string	Status vozidla dle OCPP (`A` = odpojeno, `B` = připojeno, `C` = nabíjí, `F` = dokončeno)
`odometer`	number/null	Stav tachometru (pokud vozidlo podporuje)

Lokalita a organizace

Pole	Typ	Popis
`site`	object/null	Lokalita (nabíjecí místo)
`site.id`	number	ID lokality
`site.title`	string	Název lokality
`site.address`	string	Adresa
`site.company_id`	number	ID přiřazené společnosti
`groups`	array	Skupiny zařízení (device groups), do kterých stanice patří
`companies`	array	Společnosti přiřazené k zařízení
`labels`	array	Štítky přiřazené k relaci
`tags`	array	Tagy

Tarify

Pole tariffs obsahuje pole tarifů přiřazených k zařízení. Každý tarif má:

Pole	Typ	Popis
`tariffs[].id`	number	ID tarifu
`tariffs[].title`	string	Název tarifu (např. `"Management"`, `"Návštěva"`)
`tariffs[].cost`	array	Cenové pásma: `[{start, end, price}]` — hodiny dne a cena za kWh
`tariffs[].currency`	string	Měna tarifu
`tariffs[].timezone`	string	Časová zóna pro cenová pásma (např. `"Europe/Prague"`)
`tariffs[].valid_from`	string/null	Platnost tarifu od
`tariffs[].valid_to`	string/null	Platnost tarifu do
`tariffs[].tag_groups`	array/null	Skupiny RFID tagů přiřazené k tarifu
`tariffs[].user_tags`	array/null	Konkrétní RFID tagy přiřazené k tarifu
`tariffs[].devices`	array	Zařízení, na kterých tarif platí
`tariffs[].device_groups`	array	Skupiny zařízení, na kterých tarif platí

Tag Groups v tarifech

Pole tag_groups a user_tags v tarifech umožňují přiřazení tarifů ke skupinám RFID karet. Konfiguraci tag groups provádíte přes webové rozhraní MyBox Cloud.

Systémové údaje

Pole	Typ	Popis
`created`	ISO 8601	Datum vytvoření záznamu
`updated`	ISO 8601	Datum poslední aktualizace
`deleted`	ISO 8601/null	Datum smazání (`null` pokud aktivní)

Praktické příklady

1. Získání reportů za měsíc (CURL)

# Získání všech nabíjení za září 2025
curl -X GET "https://cloud.mybox.pro/admin-panel/v1/external/charging-reports/device/abc1-def2-ghi3-jkl4?startDate=2025-09-01T00:00:00Z&endDate=2025-09-30T23:59:59Z" \
  -u "VÁŠ_API_KEY:VÁŠ_API_SECRET" \
  -H "Accept: application/json"

2. Python - billing podle RFID karet

import requests
from datetime import datetime, timedelta, timezone
from collections import defaultdict

# Vaše přihlašovací údaje
API_KEY = "váš_api_key"
API_SECRET = "váš_api_secret"
DEVICE_ID = "váš_device_id"
BASE_URL = "https://cloud.mybox.pro/admin-panel/v1"

# Získání dat za posledních 30 dní
date_to = datetime.now(timezone.utc)
date_from = date_to - timedelta(days=30)

response = requests.get(
    f"{BASE_URL}/external/charging-reports/device/{DEVICE_ID}",
    auth=(API_KEY, API_SECRET),
    params={
        'startDate': date_from.isoformat(),
        'endDate': date_to.isoformat(),
        'limit': 1000
    }
)

if response.status_code == 200:
    data = response.json()
    reports = data['data']
    total_count = data['meta']['totalCount']

    print(f"Celkem relací: {total_count}")
    print(f"Načteno: {len(reports)}\n")

    # Billing podle RFID karet
    billing = defaultdict(lambda: {'name': '', 'sessions': 0, 'energy': 0.0, 'cost': 0.0})

    for r in reports:
        rfid = r['user_id']
        billing[rfid]['name'] = r.get('user_tag_title', 'Neznámý')
        billing[rfid]['sessions'] += 1
        billing[rfid]['energy'] += float(r.get('energy_delivered', 0) or 0)
        billing[rfid]['cost'] += float(r.get('cost', 0) or 0)

    print(f"{'RFID':<20} {'Jméno':<25} {'Relací':>8} {'Energie (kWh)':>15} {'Náklady (CZK)':>15}")
    print("-" * 85)
    for rfid, info in sorted(billing.items(), key=lambda x: x[1]['energy'], reverse=True):
        print(f"{rfid:<20} {info['name']:<25} {info['sessions']:>8} {info['energy']:>15.2f} {info['cost']:>15.2f}")

3. Export do CSV

import csv
import requests

def export_charging_reports_to_csv(device_id, filename='nabijeni.csv'):
    """Exportuje charging reporty do CSV souboru"""

    response = requests.get(
        f"https://cloud.mybox.pro/admin-panel/v1/external/charging-reports/device/{device_id}",
        auth=(API_KEY, API_SECRET),
        params={'limit': 1000}
    )

    if response.status_code != 200:
        print("Chyba při získávání dat")
        return

    reports = response.json()['data']

    with open(filename, 'w', newline='', encoding='utf-8') as csvfile:
        fieldnames = [
            'Datum', 'Čas začátku', 'Doba nabíjení', 'Doba (s)',
            'Energie (kWh)', 'Stav měřidla start', 'Stav měřidla konec',
            'Náklady', 'Měna', 'RFID karta', 'Jméno uživatele',
            'Konektor', 'Status', 'Typ'
        ]
        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
        writer.writeheader()

        for report in reports:
            writer.writerow({
                'Datum': report['start_time'].split('T')[0],
                'Čas začátku': report['start_time'].split('T')[1].replace('.000Z', ''),
                'Doba nabíjení': report['duration'],
                'Doba (s)': report.get('charging_time', ''),
                'Energie (kWh)': report['energy_delivered'],
                'Stav měřidla start': report.get('start_meter_readings', ''),
                'Stav měřidla konec': report.get('actual_meter_readings', ''),
                'Náklady': report['cost'],
                'Měna': report['currency'],
                'RFID karta': report.get('user_id', ''),
                'Jméno uživatele': report.get('user_tag_title', ''),
                'Konektor': report.get('connector', ''),
                'Status': report['status'],
                'Typ': report.get('type', '')
            })

    print(f"Export dokončen: {filename} ({len(reports)} záznamů)")

Stránkování

Pro velké množství dat použijte parametry limit, offset a meta.totalCount:

def get_all_reports(device_id, start_date, end_date):
    """Načte všechny reporty s automatickým stránkováním"""
    all_reports = []
    offset = 0
    limit = 100

    while True:
        response = requests.get(
            f"{BASE_URL}/external/charging-reports/device/{device_id}",
            auth=(API_KEY, API_SECRET),
            params={
                'startDate': start_date,
                'endDate': end_date,
                'limit': limit,
                'offset': offset
            }
        )
        data = response.json()
        reports = data['data']
        total = data['meta']['totalCount']

        all_reports.extend(reports)

        if len(all_reports) >= total:
            break
        offset += limit

    return all_reports

# První stránka (záznamy 0-99)
curl -X GET "...?limit=100&offset=0"

# Druhá stránka (záznamy 100-199)
curl -X GET "...?limit=100&offset=100"

Důležité informace

Časové zóny: Všechny časy jsou v UTC (přičtěte +1 hod pro zimní čas, +2 hod pro letní čas)
Formát dat: Energie v kWh, náklady v CZK nebo EUR
Limity: Maximum 1000 záznamů na jeden požadavek
Probíhající nabíjení: Status = "In Progress", end_time je null
Stránkování: Používejte meta.totalCount pro zjištění celkového počtu záznamů
RFID identifikace: user_id obsahuje ID RFID karty, user_tag_title jméno přiřazené ke kartě
Tarify: Pole tariffs obsahuje kompletní cenové informace včetně časových pásem

Řešení problémů

Prázdná odpověď?

Zkontrolujte správnost device ID
Ověřte, že v daném období proběhlo nabíjení

Chyba 401 Unauthorized?

Zkontrolujte API klíče
Ověřte, že používáte správný formát autentizace (Basic Auth)

Stránkování nefunguje?

Zkontrolujte meta.totalCount pro celkový počet záznamů
Porovnejte s offset + limit pro další stránku

/site/charging-session-reports/csv - CSV export
/site/charging-session-reports/xlsx - Excel export
/site/charging-session-reports/statistics/csv - Statistiky

Tyto funkce jsou dostupné pouze přes webové rozhraní MyBox Cloud s přihlášením.

Jak začít?

Získejte ID vašich zařízení:

curl -X GET "https://cloud.mybox.pro/admin-panel/v1/external/device" \
  -u "VÁŠ_API_KEY:VÁŠ_API_SECRET"

Stáhněte reporty pro vaše zařízení:

curl -X GET "https://cloud.mybox.pro/admin-panel/v1/external/charging-reports/device/DEVICE_ID?startDate=2025-09-01T00:00:00Z&endDate=2025-09-30T23:59:59Z" \
  -u "VÁŠ_API_KEY:VÁŠ_API_SECRET"

Zpracujte JSON data - použijte Python příklady výše pro billing podle RFID karet nebo export do CSV