# API-Referenz: Tarife

## Tarife auflisten

`GET /v1/tariffs`

Aktive Tarife mit aktueller Version.

Antwort 200:

```json
{
  "object": "list",
  "data": [
    {
      "id": "trf_5e2a8b1c9d0f3e7a",
      "object": "tariff",
      "name": "string",
      "description": "string",
      "version": 0,
      "version_id": "string",
      "rules": {},
      "archived": true,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "has_more": true
}
```

## Tarif anlegen

`POST /v1/tariffs`

Tarifregeln: `energyPrice` in Hundertstel-Rappen pro kWh (4500 = 45 Rappen), `startFee` und `serviceFee` in Rappen, `timeWindows` für zeitabhängige Preise, `idleFee` für die Standzeitgebühr, `maxAmount` als Höchstbetrag. Preise inkl. MWST.

Parameter:

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

Anfrage:

```json
{
  "name": "string",
  "description": "string",
  "rules": {
    "currency": "CHF",
    "energyPrice": 0,
    "startFee": 0,
    "serviceFee": 0,
    "timeWindows": [],
    "idleFee": {
      "pricePerMinute": 0,
      "graceMinutes": 0,
      "trigger": "after_charging",
      "maxAmount": 0,
      "quietHours": {
        "from": "string",
        "to": "string"
      }
    },
    "maxAmount": 0,
    "timeZone": "Europe/Zurich"
  }
}
```

Antwort 201:

```json
{
  "id": "trf_5e2a8b1c9d0f3e7a",
  "object": "tariff",
  "name": "string",
  "description": "string",
  "version": 0,
  "version_id": "string",
  "rules": {},
  "archived": true,
  "created_at": "string",
  "updated_at": "string"
}
```

## Tarif abrufen

`GET /v1/tariffs/{id}`

Ein Tarif mit Regeln der aktuellen Version.

Parameter:

- `id` (path, string, Pflicht)

Antwort 200:

```json
{
  "id": "trf_5e2a8b1c9d0f3e7a",
  "object": "tariff",
  "name": "string",
  "description": "string",
  "version": 0,
  "version_id": "string",
  "rules": {},
  "archived": true,
  "created_at": "string",
  "updated_at": "string"
}
```

## Tarif ändern

`PATCH /v1/tariffs/{id}`

Neue Regeln ergeben eine neue Version. Laufende Ladungen behalten ihre Version.

Parameter:

- `id` (path, string, Pflicht)

Anfrage:

```json
{
  "name": "string",
  "description": "string",
  "rules": {
    "currency": "CHF",
    "energyPrice": 0,
    "startFee": 0,
    "serviceFee": 0,
    "timeWindows": [],
    "idleFee": {
      "pricePerMinute": 0,
      "graceMinutes": 0,
      "trigger": "after_charging",
      "maxAmount": 0,
      "quietHours": {
        "from": "string",
        "to": "string"
      }
    },
    "maxAmount": 0,
    "timeZone": "Europe/Zurich"
  }
}
```

Antwort 200:

```json
{
  "id": "trf_5e2a8b1c9d0f3e7a",
  "object": "tariff",
  "name": "string",
  "description": "string",
  "version": 0,
  "version_id": "string",
  "rules": {},
  "archived": true,
  "created_at": "string",
  "updated_at": "string"
}
```

## Tarif archivieren

`DELETE /v1/tariffs/{id}`

Nur Tarife ohne aktive Geräte.

Parameter:

- `id` (path, string, Pflicht)

Antwort 200:

```json
{
  "id": "trf_5e2a8b1c9d0f3e7a",
  "object": "tariff",
  "name": "string",
  "description": "string",
  "version": 0,
  "version_id": "string",
  "rules": {},
  "archived": true,
  "created_at": "string",
  "updated_at": "string"
}
```

## Versionen auflisten

`GET /v1/tariffs/{id}/versions`

Alle Versionen eines Tarifs.

Parameter:

- `id` (path, string, Pflicht)

Antwort 200:

```json
{}
```

## Tarifvorschau

`POST /v1/tariffs/{id}/preview`

Beispielbeträge, etwa «So viel kostet eine Ladung mit 20 kWh». Mit `rules` im Body lässt sich ein Entwurf berechnen.

Parameter:

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

Anfrage:

```json
{
  "rules": {
    "currency": "CHF",
    "energyPrice": 0,
    "startFee": 0,
    "serviceFee": 0,
    "timeWindows": [],
    "idleFee": {
      "pricePerMinute": 0,
      "graceMinutes": 0,
      "trigger": "after_charging",
      "maxAmount": 0,
      "quietHours": {
        "from": "string",
        "to": "string"
      }
    },
    "maxAmount": 0,
    "timeZone": "Europe/Zurich"
  },
  "energy_wh": [
    10000,
    20000,
    40000
  ],
  "power_w": 11000,
  "idle_minutes": 0,
  "start_at": "2026-10-25T08:30:00.000Z"
}
```

Antwort 200:

```json
{}
```

## Vorschau für Entwurf

`POST /v1/tariffs/preview`

Wie die Tarifvorschau, aber ohne gespeicherten Tarif (Regeln im Body).

Parameter:

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

Anfrage:

```json
{
  "rules": {
    "currency": "CHF",
    "energyPrice": 0,
    "startFee": 0,
    "serviceFee": 0,
    "timeWindows": [],
    "idleFee": {
      "pricePerMinute": 0,
      "graceMinutes": 0,
      "trigger": "after_charging",
      "maxAmount": 0,
      "quietHours": {
        "from": "string",
        "to": "string"
      }
    },
    "maxAmount": 0,
    "timeZone": "Europe/Zurich"
  },
  "energy_wh": [
    10000,
    20000,
    40000
  ],
  "power_w": 11000,
  "idle_minutes": 0,
  "start_at": "2026-10-25T08:30:00.000Z"
}
```

Antwort 200:

```json
{}
```