# API-Referenz: Geräte

## Geräte auflisten

`GET /v1/devices`

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

Parameter:

- `location_id` (query, string)
- `kind` (query, string)

Antwort 200:

```json
{
  "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:

- `id` (path, string, Pflicht)

Antwort 200:

```json
{
  "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:

- `id` (path, string, Pflicht)

Anfrage:

```json
{
  "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:

```json
{
  "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:

- `id` (path, string, Pflicht)
- `refresh` (query, boolean | null)

Antwort 200:

```json
{
  "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:

- `id` (path, string, Pflicht)
- `idempotency-key` (header, string): Wiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)

Antwort 201:

```json
{
  "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:

- `id` (path, string, Pflicht)
- `idempotency-key` (header, string): Wiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)

Antwort 200:

```json
{}
```

## Gerät sperren

`POST /v1/devices/{id}/lock`

Keine neuen Ladungen, laufende Ladung läuft weiter.

Parameter:

- `id` (path, string, Pflicht)
- `idempotency-key` (header, string): Wiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)

Antwort 200:

```json
{
  "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:

- `id` (path, string, Pflicht)
- `idempotency-key` (header, string): Wiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)

Antwort 200:

```json
{
  "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:

- `id` (path, string, Pflicht)
- `idempotency-key` (header, string): Wiederholbare Anfragen ohne doppelte Wirkung (24 Stunden)

Anfrage:

```json
{
  "action": "plug",
  "vehicle_need_wh": 0,
  "power_w": 0
}
```

Antwort 200:

```json
{
  "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"
}
```