# API-Referenz: Sitzungen

## Sitzungen auflisten

`GET /v1/sessions`

Ladungen, neueste zuerst. Filter: state (kommagetrennt), device_id, location_id, access_grant_id, from, to.

Parameter:

- `limit` (query, integer)
- `starting_after` (query, string)
- `state` (query, string)
- `device_id` (query, string)
- `location_id` (query, string)
- `access_grant_id` (query, string)
- `from` (query, string (date-time))
- `to` (query, string (date-time))

Antwort 200:

```json
{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "has_more": true
}
```

## Sitzung starten

`POST /v1/sessions`

Startet eine Ladung ohne Zahlung über die API (z. B. für eigene Apps oder Weiterverrechnung). Mit `access_grant_id` gilt der Sondertarif des Zugangs.

Parameter:

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

Anfrage:

```json
{
  "device_id": "string",
  "access_grant_id": "string",
  "metadata": {}
}
```

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

## Sitzung abrufen

`GET /v1/sessions/{id}`

Eine Ladung mit Beträgen, Energie und Preisaufstellung.

Parameter:

- `id` (path, string, Pflicht)

Antwort 200:

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

## Sitzung stoppen

`POST /v1/sessions/{id}/stop`

Stoppt die Ladung. Abgerechnet wird automatisch.

Parameter:

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

Antwort 200:

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

## Zeitleiste einer Sitzung

`GET /v1/sessions/{id}/events`

Alle Zustandswechsel und Messwerte (Ladekurve).

Parameter:

- `id` (path, string, Pflicht)

Antwort 200:

```json
{}
```

## Rückerstatten

`POST /v1/sessions/{id}/refund`

Voll oder teilweise (`amount` in Rappen).

Parameter:

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

Anfrage:

```json
{
  "amount": 0,
  "reason": "string"
}
```

Antwort 200:

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