Geräte

9 Endpunkte

Geräte auflisten

get/v1/devices

Ladepunkte mit aktuellem Zustand, Tarif, Abrechnungsmodell und QR-Code-URL.

Parameter

Name	Ort	Typ
`location_id`optional	Abfrage	string
`kind`optional	Abfrage	string

Antwort 200DeviceList

Name	Typ	Beschreibung
`object`Pflicht	"list"
`data`Pflicht	Device[]
`has_more`Pflicht	boolean

Mögliche Fehler

400 Anfrage ungültig
401 Nicht angemeldet
403 Berechtigung fehlt
404 Nicht gefunden
409 Zustand passt nicht
429 Zu viele Anfragen

Beispiel

curl -X GET https://api.ladehase.com/v1/devices \n  -H "Authorization: Bearer lh_test_…"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "dev_7d3a9c1b0e2f4a6b",
      "object": "device",
      "kind": "string",
      "livemode": true,
      "name": "Ladepunkt Scheune",
      "location_id": "string",
      "integration_id": "string",
      "manufacturer": "string",
      "model": "string",
      "serial_number": "string",
      "max_power_w": 0,
      "tariff_id": "string",
      "billing": {},
      "enabled": true,
      "locked": true,
      "prepared": true,
      "status": "string",
      "state": {
        "online": true,
        "status": "string",
        "cable_plugged": true,
        "power_w": 0,
        "meter_wh": 0,
        "authorization_required": true,
        "last_seen_at": "2026-10-25T08:30:00.000Z",
        "error": "string"
      },
      "active_session_id": "string",
      "connectors": [
        {
          "id": "string",
          "code": "string",
          "url": "string"
        }
      ],
      "created_at": "string"
    }
  ],
  "has_more": true
}

Gerät abrufen

get/v1/devices/{id}

Ein Gerät mit Zustand.

Parameter

Name	Ort	Typ
`id`Pflicht	Pfad	string

Antwort 200Device

Name	Typ	Beschreibung
`id`Pflicht	string	ID mit Präfix «dev_»
`object`Pflicht	"device"
`kind`Pflicht	string	Geräteart, vorerst «ev_charger»
`livemode`Pflicht	boolean
`name`Pflicht	string
`location_id`Pflicht	string
`integration_id`Pflicht	string \| null
`manufacturer`Pflicht	string \| null
`model`Pflicht	string \| null
`serial_number`Pflicht	string \| null
`max_power_w`Pflicht	integer \| null
`tariff_id`Pflicht	string \| null
`billing`Pflicht	object	Abrechnungsmodell, Reservationsgrenzen, Pakete
`enabled`Pflicht	boolean	Von Ladehase verwaltet und für Fahrende freigegeben
`locked`Pflicht	boolean	Vorübergehend gesperrt (keine neuen Ladungen)
`prepared`Pflicht	boolean	«Autorisierung erforderlich» beim Hersteller gesetzt
`status`Pflicht	string	Zusammengefasster Status für Anzeigen
`state`Pflicht	DeviceState
`active_session_id`Pflicht	string \| null
`connectors`Pflicht	object[]
`created_at`Pflicht	string

Mögliche Fehler

400 Anfrage ungültig
401 Nicht angemeldet
403 Berechtigung fehlt
404 Nicht gefunden
409 Zustand passt nicht
429 Zu viele Anfragen

Beispiel

curl -X GET https://api.ladehase.com/v1/devices/{id} \n  -H "Authorization: Bearer lh_test_…"

Antwort 200

{
  "id": "dev_7d3a9c1b0e2f4a6b",
  "object": "device",
  "kind": "string",
  "livemode": true,
  "name": "Ladepunkt Scheune",
  "location_id": "string",
  "integration_id": "string",
  "manufacturer": "string",
  "model": "string",
  "serial_number": "string",
  "max_power_w": 0,
  "tariff_id": "string",
  "billing": {},
  "enabled": true,
  "locked": true,
  "prepared": true,
  "status": "string",
  "state": {
    "online": true,
    "status": "string",
    "cable_plugged": true,
    "power_w": 0,
    "meter_wh": 0,
    "authorization_required": true,
    "last_seen_at": "2026-10-25T08:30:00.000Z",
    "error": "string"
  },
  "active_session_id": "string",
  "connectors": [
    {
      "id": "string",
      "code": "string",
      "url": "string"
    }
  ],
  "created_at": "string"
}

Gerät ändern

patch/v1/devices/{id}

Name, Standort, Tarif, Abrechnungsmodell (reservation, prepaid, both), Reservationsgrenzen, Pakete. `enabled: true` aktiviert das Gerät und setzt beim Hersteller «Autorisierung erforderlich».

Parameter

Name	Ort	Typ
`id`Pflicht	Pfad	string

Anfrage

Name	Typ	Beschreibung
`name`optional	string
`location_id`optional	string
`tariff_id`optional	string \| null
`billing`optional	object
`enabled`optional	boolean

Antwort 200Device

Name	Typ	Beschreibung
`id`Pflicht	string	ID mit Präfix «dev_»
`object`Pflicht	"device"
`kind`Pflicht	string	Geräteart, vorerst «ev_charger»
`livemode`Pflicht	boolean
`name`Pflicht	string
`location_id`Pflicht	string
`integration_id`Pflicht	string \| null
`manufacturer`Pflicht	string \| null
`model`Pflicht	string \| null
`serial_number`Pflicht	string \| null
`max_power_w`Pflicht	integer \| null
`tariff_id`Pflicht	string \| null
`billing`Pflicht	object	Abrechnungsmodell, Reservationsgrenzen, Pakete
`enabled`Pflicht	boolean	Von Ladehase verwaltet und für Fahrende freigegeben
`locked`Pflicht	boolean	Vorübergehend gesperrt (keine neuen Ladungen)
`prepared`Pflicht	boolean	«Autorisierung erforderlich» beim Hersteller gesetzt
`status`Pflicht	string	Zusammengefasster Status für Anzeigen
`state`Pflicht	DeviceState
`active_session_id`Pflicht	string \| null
`connectors`Pflicht	object[]
`created_at`Pflicht	string

Mögliche Fehler

400 Anfrage ungültig
401 Nicht angemeldet
403 Berechtigung fehlt
404 Nicht gefunden
409 Zustand passt nicht
429 Zu viele Anfragen

Beispiel

curl -X PATCH https://api.ladehase.com/v1/devices/{id} \n  -H "Authorization: Bearer lh_test_…" \n  -H "Content-Type: application/json" \n  -d '{"name":"string","location_id":"string","tariff_id":"string","billing":{"model":"reservation","reservationDefault":3000,"reservationMin":1000,"reservationMax":10000,"safetyMarginBps":300,"packages":[],"prepaidRemainder":"refund","plugTimeoutMinutes":10,"maxDurationMinutes":1440},"enabled":true}'

Antwort 200

{
  "id": "dev_7d3a9c1b0e2f4a6b",
  "object": "device",
  "kind": "string",
  "livemode": true,
  "name": "Ladepunkt Scheune",
  "location_id": "string",
  "integration_id": "string",
  "manufacturer": "string",
  "model": "string",
  "serial_number": "string",
  "max_power_w": 0,
  "tariff_id": "string",
  "billing": {},
  "enabled": true,
  "locked": true,
  "prepared": true,
  "status": "string",
  "state": {
    "online": true,
    "status": "string",
    "cable_plugged": true,
    "power_w": 0,
    "meter_wh": 0,
    "authorization_required": true,
    "last_seen_at": "2026-10-25T08:30:00.000Z",
    "error": "string"
  },
  "active_session_id": "string",
  "connectors": [
    {
      "id": "string",
      "code": "string",
      "url": "string"
    }
  ],
  "created_at": "string"
}

Zustand abfragen

get/v1/devices/{id}/state

Aktueller Zustand. Mit `refresh=true` wird beim Hersteller nachgefragt.

Parameter

Name	Ort	Typ
`id`Pflicht	Pfad	string
`refresh`optional	Abfrage	boolean \| null

Antwort 200DeviceState

Name	Typ	Beschreibung
`online`optional	boolean
`status`optional	string	offline, available, vehicle_connected, awaiting_authorization, charging, suspended, finished, error
`cable_plugged`optional	boolean
`power_w`optional	integer	Aktuelle Leistung in Watt
`meter_wh`optional	integer \| null	Zählerstand in Wh
`authorization_required`optional	boolean \| null
`last_seen_at`optional	string \| null	Zeitpunkt (ISO 8601, UTC)
`error`optional	string \| null

Mögliche Fehler

400 Anfrage ungültig
401 Nicht angemeldet
403 Berechtigung fehlt
404 Nicht gefunden
409 Zustand passt nicht
429 Zu viele Anfragen

Beispiel

curl -X GET https://api.ladehase.com/v1/devices/{id}/state \n  -H "Authorization: Bearer lh_test_…"

Antwort 200

{
  "online": true,
  "status": "string",
  "cable_plugged": true,
  "power_w": 0,
  "meter_wh": 0,
  "authorization_required": true,
  "last_seen_at": "2026-10-25T08:30:00.000Z",
  "error": "string"
}

Ladung ohne Zahlung starten

post/v1/devices/{id}/start

Gibt den Ladepunkt ohne Zahlung frei (z. B. eigenes Auto). Ladehase legt dafür eine Gratis-Sitzung an, damit die Energie erfasst wird.

Parameter

Name	Ort	Typ
`id`Pflicht	Pfad	string
`idempotency-key`optionalWiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)	Kopfzeile	string

Antwort 201Session

Name	Typ	Beschreibung
`id`Pflicht	string	ID mit Präfix «ses_»
`object`Pflicht	"session"
`livemode`Pflicht	boolean
`state`Pflicht	string	Zustand gemäss Zustandsautomat (created … settled)
`mode`Pflicht	"reservation" \| "prepaid" \| "access"
`channel`Pflicht	"qr" \| "terminal" \| "api" \| "rfid" \| "access_link"
`location_id`Pflicht	string
`device_id`Pflicht	string
`connector_id`Pflicht	string
`currency`Pflicht	string
`authorized_amount`Pflicht	integer	Reservierter beziehungsweise bezahlter Betrag in Rappen
`amount`Pflicht	integer	Hochgerechneter Betrag (laufend) oder Endbetrag in Rappen
`captured_amount`Pflicht	integer	Belasteter Betrag in Rappen
`refunded_amount`Pflicht	integer	Zurückerstatteter Betrag in Rappen
`vat_amount`Pflicht	integer	MWST-Anteil in Rappen
`energy_wh`Pflicht	integer	Geladene Energie in Wh
`idle_minutes`Pflicht	integer
`stop_reason`Pflicht	string \| null
`receipt_number`Pflicht	string \| null
`started_at`Pflicht	string \| null	Zeitpunkt (ISO 8601, UTC)
`ended_at`Pflicht	string \| null	Zeitpunkt (ISO 8601, UTC)
`settled_at`Pflicht	string \| null	Zeitpunkt (ISO 8601, UTC)
`created_at`Pflicht	string

Mögliche Fehler

400 Anfrage ungültig
401 Nicht angemeldet
403 Berechtigung fehlt
404 Nicht gefunden
409 Zustand passt nicht
429 Zu viele Anfragen

Beispiel

curl -X POST https://api.ladehase.com/v1/devices/{id}/start \n  -H "Authorization: Bearer lh_test_…"

Antwort 201

{
  "id": "ses_1a2b3c4d5e6f7a8b9c0d",
  "object": "session",
  "livemode": true,
  "state": "string",
  "mode": "reservation",
  "channel": "qr",
  "location_id": "string",
  "device_id": "string",
  "connector_id": "string",
  "currency": "string",
  "authorized_amount": 1235,
  "amount": 1235,
  "captured_amount": 1235,
  "refunded_amount": 1235,
  "vat_amount": 1235,
  "energy_wh": 0,
  "idle_minutes": 0,
  "stop_reason": "string",
  "receipt_number": "string",
  "started_at": "2026-10-25T08:30:00.000Z",
  "ended_at": "2026-10-25T08:30:00.000Z",
  "settled_at": "2026-10-25T08:30:00.000Z",
  "created_at": "string"
}

Ladung am Gerät stoppen

post/v1/devices/{id}/stop

Stoppt die laufende Sitzung des Geräts und rechnet ab. Ohne Sitzung wird nur der Stoppbefehl gesendet.

Parameter

Name	Ort	Typ
`id`Pflicht	Pfad	string
`idempotency-key`optionalWiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)	Kopfzeile	string

Antwort 200Object

Mögliche Fehler

400 Anfrage ungültig
401 Nicht angemeldet
403 Berechtigung fehlt
404 Nicht gefunden
409 Zustand passt nicht
429 Zu viele Anfragen

Beispiel

curl -X POST https://api.ladehase.com/v1/devices/{id}/stop \n  -H "Authorization: Bearer lh_test_…"

Antwort 200

{}

Gerät sperren

post/v1/devices/{id}/lock

Keine neuen Ladungen, laufende Ladung läuft weiter.

Parameter

Name	Ort	Typ
`id`Pflicht	Pfad	string
`idempotency-key`optionalWiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)	Kopfzeile	string

Antwort 200Device

Name	Typ	Beschreibung
`id`Pflicht	string	ID mit Präfix «dev_»
`object`Pflicht	"device"
`kind`Pflicht	string	Geräteart, vorerst «ev_charger»
`livemode`Pflicht	boolean
`name`Pflicht	string
`location_id`Pflicht	string
`integration_id`Pflicht	string \| null
`manufacturer`Pflicht	string \| null
`model`Pflicht	string \| null
`serial_number`Pflicht	string \| null
`max_power_w`Pflicht	integer \| null
`tariff_id`Pflicht	string \| null
`billing`Pflicht	object	Abrechnungsmodell, Reservationsgrenzen, Pakete
`enabled`Pflicht	boolean	Von Ladehase verwaltet und für Fahrende freigegeben
`locked`Pflicht	boolean	Vorübergehend gesperrt (keine neuen Ladungen)
`prepared`Pflicht	boolean	«Autorisierung erforderlich» beim Hersteller gesetzt
`status`Pflicht	string	Zusammengefasster Status für Anzeigen
`state`Pflicht	DeviceState
`active_session_id`Pflicht	string \| null
`connectors`Pflicht	object[]
`created_at`Pflicht	string

Mögliche Fehler

400 Anfrage ungültig
401 Nicht angemeldet
403 Berechtigung fehlt
404 Nicht gefunden
409 Zustand passt nicht
429 Zu viele Anfragen

Beispiel

curl -X POST https://api.ladehase.com/v1/devices/{id}/lock \n  -H "Authorization: Bearer lh_test_…"

Antwort 200

{
  "id": "dev_7d3a9c1b0e2f4a6b",
  "object": "device",
  "kind": "string",
  "livemode": true,
  "name": "Ladepunkt Scheune",
  "location_id": "string",
  "integration_id": "string",
  "manufacturer": "string",
  "model": "string",
  "serial_number": "string",
  "max_power_w": 0,
  "tariff_id": "string",
  "billing": {},
  "enabled": true,
  "locked": true,
  "prepared": true,
  "status": "string",
  "state": {
    "online": true,
    "status": "string",
    "cable_plugged": true,
    "power_w": 0,
    "meter_wh": 0,
    "authorization_required": true,
    "last_seen_at": "2026-10-25T08:30:00.000Z",
    "error": "string"
  },
  "active_session_id": "string",
  "connectors": [
    {
      "id": "string",
      "code": "string",
      "url": "string"
    }
  ],
  "created_at": "string"
}

Gerät entsperren

post/v1/devices/{id}/unlock

Hebt die Sperre auf.

Parameter

Name	Ort	Typ
`id`Pflicht	Pfad	string
`idempotency-key`optionalWiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)	Kopfzeile	string

Antwort 200Device

Name	Typ	Beschreibung
`id`Pflicht	string	ID mit Präfix «dev_»
`object`Pflicht	"device"
`kind`Pflicht	string	Geräteart, vorerst «ev_charger»
`livemode`Pflicht	boolean
`name`Pflicht	string
`location_id`Pflicht	string
`integration_id`Pflicht	string \| null
`manufacturer`Pflicht	string \| null
`model`Pflicht	string \| null
`serial_number`Pflicht	string \| null
`max_power_w`Pflicht	integer \| null
`tariff_id`Pflicht	string \| null
`billing`Pflicht	object	Abrechnungsmodell, Reservationsgrenzen, Pakete
`enabled`Pflicht	boolean	Von Ladehase verwaltet und für Fahrende freigegeben
`locked`Pflicht	boolean	Vorübergehend gesperrt (keine neuen Ladungen)
`prepared`Pflicht	boolean	«Autorisierung erforderlich» beim Hersteller gesetzt
`status`Pflicht	string	Zusammengefasster Status für Anzeigen
`state`Pflicht	DeviceState
`active_session_id`Pflicht	string \| null
`connectors`Pflicht	object[]
`created_at`Pflicht	string

Mögliche Fehler

400 Anfrage ungültig
401 Nicht angemeldet
403 Berechtigung fehlt
404 Nicht gefunden
409 Zustand passt nicht
429 Zu viele Anfragen

Beispiel

curl -X POST https://api.ladehase.com/v1/devices/{id}/unlock \n  -H "Authorization: Bearer lh_test_…"

Antwort 200

{
  "id": "dev_7d3a9c1b0e2f4a6b",
  "object": "device",
  "kind": "string",
  "livemode": true,
  "name": "Ladepunkt Scheune",
  "location_id": "string",
  "integration_id": "string",
  "manufacturer": "string",
  "model": "string",
  "serial_number": "string",
  "max_power_w": 0,
  "tariff_id": "string",
  "billing": {},
  "enabled": true,
  "locked": true,
  "prepared": true,
  "status": "string",
  "state": {
    "online": true,
    "status": "string",
    "cable_plugged": true,
    "power_w": 0,
    "meter_wh": 0,
    "authorization_required": true,
    "last_seen_at": "2026-10-25T08:30:00.000Z",
    "error": "string"
  },
  "active_session_id": "string",
  "connectors": [
    {
      "id": "string",
      "code": "string",
      "url": "string"
    }
  ],
  "created_at": "string"
}

Testgerät steuern

post/v1/devices/{id}/simulate

Nur Testmodus: simuliertes Auto anstecken (`plug`), abziehen (`unplug`), offline, Störung, Leistung ändern.

Parameter

Name	Ort	Typ
`id`Pflicht	Pfad	string
`idempotency-key`optionalWiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)	Kopfzeile	string

Anfrage

Name	Typ	Beschreibung
`action`Pflicht	"plug" \| "unplug" \| "offline" \| "online" \| "error" \| "clear_error" \| "set_power"
`vehicle_need_wh`optional	integer
`power_w`optional	integer

Antwort 200DeviceState

Name	Typ	Beschreibung
`online`optional	boolean
`status`optional	string	offline, available, vehicle_connected, awaiting_authorization, charging, suspended, finished, error
`cable_plugged`optional	boolean
`power_w`optional	integer	Aktuelle Leistung in Watt
`meter_wh`optional	integer \| null	Zählerstand in Wh
`authorization_required`optional	boolean \| null
`last_seen_at`optional	string \| null	Zeitpunkt (ISO 8601, UTC)
`error`optional	string \| null

Mögliche Fehler

400 Anfrage ungültig
401 Nicht angemeldet
403 Berechtigung fehlt
404 Nicht gefunden
409 Zustand passt nicht
429 Zu viele Anfragen

Beispiel

curl -X POST https://api.ladehase.com/v1/devices/{id}/simulate \n  -H "Authorization: Bearer lh_test_…" \n  -H "Content-Type: application/json" \n  -d '{"action":"plug","vehicle_need_wh":0,"power_w":0}'

Antwort 200

{
  "online": true,
  "status": "string",
  "cable_plugged": true,
  "power_w": 0,
  "meter_wh": 0,
  "authorization_required": true,
  "last_seen_at": "2026-10-25T08:30:00.000Z",
  "error": "string"
}