Geräte

9 endpoint

Le descrizioni degli endpoint provengono direttamente dall'API e sono in tedesco.

Geräte auflisten

get/v1/devices

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

Parametri

Nome	Posizione	Tipo
`location_id`facoltativo	Query	string
`kind`facoltativo	Query	string

Risposta 200DeviceList

Nome	Tipo	Descrizione
`object`obbligatorio	"list"
`data`obbligatorio	Device[]
`has_more`obbligatorio	boolean

Errori possibili

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

Esempio

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

Risposta 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.

Parametri

Nome	Posizione	Tipo
`id`obbligatorio	Percorso	string

Risposta 200Device

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

Errori possibili

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

Esempio

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

Risposta 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».

Parametri

Nome	Posizione	Tipo
`id`obbligatorio	Percorso	string

Richiesta

Nome	Tipo	Descrizione
`name`facoltativo	string
`location_id`facoltativo	string
`tariff_id`facoltativo	string \| null
`billing`facoltativo	object
`enabled`facoltativo	boolean

Risposta 200Device

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

Errori possibili

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

Esempio

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}'

Risposta 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.

Parametri

Nome	Posizione	Tipo
`id`obbligatorio	Percorso	string
`refresh`facoltativo	Query	boolean \| null

Risposta 200DeviceState

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

Errori possibili

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

Esempio

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

Risposta 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.

Parametri

Nome	Posizione	Tipo
`id`obbligatorio	Percorso	string
`idempotency-key`facoltativoWiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)	Intestazione	string

Risposta 201Session

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

Errori possibili

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

Esempio

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

Risposta 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.

Parametri

Nome	Posizione	Tipo
`id`obbligatorio	Percorso	string
`idempotency-key`facoltativoWiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)	Intestazione	string

Risposta 200Object

Errori possibili

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

Esempio

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

Risposta 200

{}

Gerät sperren

post/v1/devices/{id}/lock

Keine neuen Ladungen, laufende Ladung läuft weiter.

Parametri

Nome	Posizione	Tipo
`id`obbligatorio	Percorso	string
`idempotency-key`facoltativoWiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)	Intestazione	string

Risposta 200Device

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

Errori possibili

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

Esempio

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

Risposta 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.

Parametri

Nome	Posizione	Tipo
`id`obbligatorio	Percorso	string
`idempotency-key`facoltativoWiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)	Intestazione	string

Risposta 200Device

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

Errori possibili

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

Esempio

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

Risposta 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.

Parametri

Nome	Posizione	Tipo
`id`obbligatorio	Percorso	string
`idempotency-key`facoltativoWiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)	Intestazione	string

Richiesta

Nome	Tipo	Descrizione
`action`obbligatorio	"plug" \| "unplug" \| "offline" \| "online" \| "error" \| "clear_error" \| "set_power"
`vehicle_need_wh`facoltativo	integer
`power_w`facoltativo	integer

Risposta 200DeviceState

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

Errori possibili

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

Esempio

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}'

Risposta 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"
}