# Sitzungen und Zustände

> Wie eine Ladung vom Scan bis zur Abrechnung verläuft, welche Zustände es gibt und wann eine Sitzung endet.

Eine **Sitzung** (`ses_…`) ist eine Ladung von der Zahlung oder Freigabe bis zur Abrechnung. Sie gehört zu genau einem Ladepunkt und friert beim Start die gültige Tarifversion ein. Spätere Tarifänderungen wirken sich nicht auf laufende Sitzungen aus.

## Ablauf

1. Die fahrende Person scannt den QR-Code oder wählt am Terminal den Ladepunkt. Ladehase legt eine Sitzung an (`created`).
2. Sie reserviert einen Betrag oder kauft ein Paket (`awaiting_payment`).
3. Ist die Zahlung autorisiert (`authorized`), gibt Ladehase den Ladepunkt frei und wartet auf das Auto (`waiting_for_vehicle`).
4. Das Auto lädt (`charging`). Ladehase misst laufend die Energie und rechnet den Betrag hoch.
5. Das Kabel wird abgezogen oder die Ladung gestoppt (`completed`).
6. Ladehase belastet den Endbetrag, gibt den Rest der Reservation frei und stellt die Quittung aus (`settled`).

## Zustände

<table>
  <thead>
    <tr><th>Zustand</th><th>Bedeutung</th></tr>
  </thead>
  <tbody>
    <tr><td>`created`</td><td>Sitzung angelegt, noch keine Zahlung.</td></tr>
    <tr><td>`awaiting_payment`</td><td>Zahlung läuft beim Zahlungspartner.</td></tr>
    <tr><td>`authorized`</td><td>Bezahlt oder per Zugang freigegeben.</td></tr>
    <tr><td>`waiting_for_vehicle`</td><td>Ladepunkt freigegeben, Auto noch nicht eingesteckt oder lädt noch nicht.</td></tr>
    <tr><td>`charging`</td><td>Das Auto lädt.</td></tr>
    <tr><td>`suspended`</td><td>Ladung pausiert, zum Beispiel durch das Auto oder das Lastmanagement.</td></tr>
    <tr><td>`idle`</td><td>Auto voll, Kabel steckt noch. Hier kann eine Standzeitgebühr anfallen.</td></tr>
    <tr><td>`stopping`</td><td>Stopp angefordert, Ladehase wartet auf die Bestätigung der Ladestation.</td></tr>
    <tr><td>`completed`</td><td>Ladung beendet, Abrechnung folgt.</td></tr>
    <tr><td>`settled`</td><td>Abgerechnet. Endzustand.</td></tr>
    <tr><td>`payment_failed`</td><td>Zahlung fehlgeschlagen. Endzustand.</td></tr>
    <tr><td>`expired`</td><td>Kein Auto innert der Frist eingesteckt, Reservation freigegeben. Endzustand.</td></tr>
    <tr><td>`canceled`</td><td>Abgebrochen, Reservation freigegeben. Endzustand.</td></tr>
    <tr><td>`error`</td><td>Störung. Wird behoben (weiter zu `completed`) oder abgebrochen (`canceled`).</td></tr>
  </tbody>
</table>

Pro Anschluss gibt es höchstens eine aktive Sitzung. Eine zweite Anfrage für denselben Anschluss beantwortet die API mit `409` und dem Code `conflict`.

## Gründe für das Ende

Das Feld `stop_reason` sagt, warum eine Ladung endete:

- `unplugged`: Kabel abgezogen
- `amount_reached`: Reservation erreicht (abzüglich Sicherheitsmarge)
- `package_reached`: Paket aufgebraucht
- `driver`: von der fahrenden Person beendet
- `operator`: von den Betreibenden beendet
- `api`: über die API beendet
- `max_duration`: Höchstdauer erreicht
- `device_error`: Störung an der Ladestation

## Abrechnungsarten

Das Feld `mode` zeigt, wie abgerechnet wird:

- `reservation`: Betrag reservieren, nach Verbrauch belasten, Rest freigeben.
- `prepaid`: Paket vorab bezahlt. Nicht genutztes Guthaben wird je nach Einstellung zurückerstattet oder verfällt.
- `access`: Ladung über einen Zugang, gratis oder zum Sondertarif.

## Beträge einer Sitzung

<table>
  <thead>
    <tr><th>Feld</th><th>Bedeutung</th></tr>
  </thead>
  <tbody>
    <tr><td>`authorized_amount`</td><td>Reservierter beziehungsweise vorab bezahlter Betrag in Rappen.</td></tr>
    <tr><td>`amount`</td><td>Laufend hochgerechneter Betrag oder Endbetrag in Rappen.</td></tr>
    <tr><td>`captured_amount`</td><td>Tatsächlich belasteter Betrag in Rappen.</td></tr>
    <tr><td>`refunded_amount`</td><td>Zurückerstatteter Betrag in Rappen.</td></tr>
    <tr><td>`vat_amount`</td><td>Enthaltener MWST-Anteil in Rappen.</td></tr>
    <tr><td>`energy_wh`</td><td>Geladene Energie in Wattstunden.</td></tr>
  </tbody>
</table>

Die Zeitleiste einer Sitzung mit allen Ereignissen liefert `GET /v1/sessions/{id}/events`.