# API-Referenz: Zugänge

## Zugänge auflisten

`GET /v1/access_grants`

Personen und Ladekarten, die gratis oder zum Sondertarif laden.

Antwort 200:

```json
{
  "object": "list",
  "data": [
    {
      "id": "acc_0e9d8c7b6a5f4e3d",
      "object": "access_grant",
      "name": "string",
      "email": "string",
      "rfid_uid": "string",
      "link_url": "string",
      "free": true,
      "tariff_id": "string",
      "monthly_limit_wh": 0,
      "revoked": true,
      "created_at": "string"
    }
  ],
  "has_more": true
}
```

## Zugang anlegen

`POST /v1/access_grants`

Ohne `tariff_id` gratis, mit `tariff_id` Sondertarif und Monatsabrechnung. Erzeugt einen persönlichen Link.

Parameter:

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

Anfrage:

```json
{
  "name": "string",
  "email": "person@example.ch",
  "rfid_uid": "string",
  "create_link": true,
  "valid_from": "2026-10-25T08:30:00.000Z",
  "valid_until": "2026-10-25T08:30:00.000Z",
  "device_ids": [],
  "tariff_id": "string",
  "monthly_limit_wh": 0,
  "billing_integration_id": "string",
  "note": "string"
}
```

Antwort 201:

```json
{
  "id": "acc_0e9d8c7b6a5f4e3d",
  "object": "access_grant",
  "name": "string",
  "email": "string",
  "rfid_uid": "string",
  "link_url": "string",
  "free": true,
  "tariff_id": "string",
  "monthly_limit_wh": 0,
  "revoked": true,
  "created_at": "string"
}
```

## Zugang abrufen

`GET /v1/access_grants/{id}`

Ein Zugang.

Parameter:

- `id` (path, string, Pflicht)

Antwort 200:

```json
{
  "id": "acc_0e9d8c7b6a5f4e3d",
  "object": "access_grant",
  "name": "string",
  "email": "string",
  "rfid_uid": "string",
  "link_url": "string",
  "free": true,
  "tariff_id": "string",
  "monthly_limit_wh": 0,
  "revoked": true,
  "created_at": "string"
}
```

## Zugang ändern

`PATCH /v1/access_grants/{id}`

Auch `revoked` und `regenerate_link`.

Parameter:

- `id` (path, string, Pflicht)

Anfrage:

```json
{
  "name": "string",
  "email": "person@example.ch",
  "rfid_uid": "string",
  "create_link": true,
  "valid_from": "2026-10-25T08:30:00.000Z",
  "valid_until": "2026-10-25T08:30:00.000Z",
  "device_ids": [],
  "tariff_id": "string",
  "monthly_limit_wh": 0,
  "billing_integration_id": "string",
  "note": "string",
  "revoked": true,
  "regenerate_link": true
}
```

Antwort 200:

```json
{
  "id": "acc_0e9d8c7b6a5f4e3d",
  "object": "access_grant",
  "name": "string",
  "email": "string",
  "rfid_uid": "string",
  "link_url": "string",
  "free": true,
  "tariff_id": "string",
  "monthly_limit_wh": 0,
  "revoked": true,
  "created_at": "string"
}
```

## Zugang widerrufen

`DELETE /v1/access_grants/{id}`

Link und Berechtigung werden ungültig.

Parameter:

- `id` (path, string, Pflicht)

Antwort 200:

```json
{
  "id": "string",
  "object": "string",
  "deleted": true
}
```

## Monatsabrechnungen

`GET /v1/billing_statements`

Abrechnungen für Zugänge mit Sondertarif.

Parameter:

- `period` (query, string)

Antwort 200:

```json
{}
```

## Abrechnungen erstellen

`POST /v1/billing_statements/generate`

Für einen Monat (`period` = JJJJ-MM).

Parameter:

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

Anfrage:

```json
{
  "period": "string"
}
```

Antwort 200:

```json
{}
```

## Abrechnung senden

`POST /v1/billing_statements/{id}/send`

E-Mail mit Zahlungslink über zahls.ch oder Freika.

Parameter:

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

Antwort 200:

```json
{}
```

## Als bezahlt markieren

`POST /v1/billing_statements/{id}/paid`

Zum Beispiel bei Barzahlung.

Parameter:

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

Antwort 200:

```json
{}
```