# Benutzerhandbuch — Katalog-Service

Version 1.2.0 · Stand 2026-04-24

Dieses Handbuch richtet sich an zwei Zielgruppen:

1. **Administratoren** — Anlage und Pflege von Tenants, Katalogen, GKV-Importen.
2. **Integratoren** (z. B. Pflegesoftware-Entwickler) — Abruf der Daten per API.

Produktionsadresse: <https://catalog.c3po42.de>

---

## 1. Überblick

Der Katalog-Service stellt drei Datenfamilien zentral bereit:

| Datenfamilie | Quelle | Umfang |
|---|---|---|
| **SGB XI Leistungskataloge** | Rahmenverträge §75 SGB XI | 16 Bundesländer, LK 1–27 |
| **§302 HKP-Positionsnummern** | GKV-Spitzenverband (PDF) | 1293 Codes, bundeseinheitlich |
| **GKV-Kostenträger-Stammdaten** | gkv-datenaustausch.de (EDIFACT KOTR) | ~1900 Einträge, SGB V + SGB XI getrennt |

Zugriff auf zwei Wegen:

- **Public API** (`/catalogs/v1/**`) — ohne Key, abwärtskompatibel zum alten Static-JSON-Server.
- **Tenant API** (`/api/v1/tenant/**`) — mit API-Key, feature-gated über Subscription.

Die Admin-Oberfläche läuft unter `/` und verwendet JWT-Login (Rollen ADMIN / REDAKTEUR / VIEWER).

---

## 2. Erste Schritte (Admin)

### 2.1 Anmelden

1. `https://catalog.c3po42.de/` im Browser öffnen.
2. Mit dem Admin-Konto einloggen (Standard: `admin` / `admin`, in Produktion ändern).
3. Das Token bleibt 8 Stunden gültig — danach neu einloggen.

### 2.2 Oberfläche im Überblick

| Bereich | Funktion |
|---|---|
| **Kataloge** | SGB V/XI Kataloge pro Bundesland anlegen und pflegen |
| **Leistungen** | Leistungskomplexe eines Katalogs einsehen (nur Leseansicht; Pflege via API) |
| **Kostenträger** | ~1900 GKV-Kostenträger durchsuchen, VKG-Verknüpfungen einsehen |
| **GKV-Import** | EDIFACT-KOTR-Dateien vom GKV-Server ziehen oder manuell hochladen |
| **HKP-Positionen** | §302 Positionsnummern vom GKV-Spitzenverband importieren (PDF) |
| **Tenants** | Kunden anlegen, Keys rotieren, Subscriptions verwalten |
| **Audit-Log** | Nachvollziehen, welcher Tenant wann welchen Endpoint aufgerufen hat |

---

## 3. Tenants verwalten

Ein Tenant ist ein zahlender Kunde mit eigenem API-Key und Abo-Tarif.

### 3.1 Neuen Tenant anlegen

1. Admin-UI → **Tenants** → **+ Neuer Tenant**.
2. Felder ausfüllen:
   - **Name** (z. B. `Pflegedienst Sonnenschein`)
   - **Kontaktmail** für Rechnungen und Benachrichtigungen
   - **Tarif** (Basic / Premium / Enterprise)
3. Klick auf **Anlegen**.
4. Der API-Key wird **einmalig** im Dialog angezeigt — jetzt kopieren und sicher weitergeben. Danach ist nur noch der Prefix sichtbar.

> **Wichtig:** Wer den Key verliert, muss ihn rotieren. Der Klartext wird nirgends gespeichert — nur ein bcrypt-Hash.

### 3.2 Key rotieren

Tenant auswählen → **Key rotieren**. Der alte Key wird ungültig, ein neuer erzeugt. Den neuen Key wieder einmalig im Dialog zeigen.

### 3.3 Subscription ändern

Subscription bestimmt welche Features der Tenant nutzen darf:

| Feature-Flag | Bedeutung |
|---|---|
| `sgb_xi` | SGB XI Leistungskataloge |
| `sgb_v` | SGB V HKP-Katalog |
| `kostentraeger` | GKV-Kostenträger-API |
| `api` | Tenant-API allgemein |
| `csv` | CSV-Export auf `leistungen` |
| `webhook` | Webhook-Benachrichtigung bei Datenupdate (Enterprise) |
| `history` | Historische Versionen abrufen (Enterprise) |

Features werden als Komma-Liste auf der Subscription gespeichert. Tarif-Presets:

- **Basic:** `sgb_xi,sgb_v`
- **Premium:** `sgb_xi,sgb_v,kostentraeger,api,csv`
- **Enterprise:** `sgb_xi,sgb_v,kostentraeger,api,csv,webhook,history`

---

## 4. Kataloge pflegen

### 4.1 Neuen SGB XI Katalog anlegen

1. Admin-UI → **Kataloge** → **+ Neuer Katalog**.
2. Felder:
   - **SGB** = `XI`
   - **Bundesland** = `TH`, `NRW`, `BY`, …
   - **Version** = YYYY-MM-DD (Gültigkeitsbeginn)
3. **Anlegen**.
4. Leistungen werden per API nachgepflegt:
   ```bash
   curl -X POST https://catalog.c3po42.de/api/v1/admin/leistungen \
        -H "Authorization: Bearer <admin-jwt>" \
        -H "Content-Type: application/json" \
        -d '{
          "katalog_id": 42,
          "code": "LK01",
          "bezeichnung": "Grundpflege klein",
          "punkte": 120,
          "zeit_minuten": 10
        }'
   ```

### 4.2 §302 Positionsnummern aktualisieren

Das bundeseinheitliche Positionsnummernverzeichnis kommt vom GKV-Spitzenverband als PDF. Es wird etwa 2–4× im Jahr aktualisiert.

1. Admin-UI → **GKV-Import** → Karte **HKP-Positionsnummern**.
2. **Jetzt live importieren** — holt das aktuelle PDF vom Portal, parst mit pdfplumber, legt einen Katalog `sgb=V, bundesland=BUND, version=YYYY-MM-DD` an.
3. Alternativ: **Eigenes PDF hochladen** für den Fall, dass sich die URL am Portal geändert hat.

> **Preise** stehen **nicht** im GKV-Dokument — die sind zwischen Pflegedienst und Kasse verhandelt und müssen in der jeweiligen Fachanwendung (z. B. PflegeFlow) als Vergütungsvereinbarung gepflegt werden.

---

## 5. GKV-Kostenträger importieren

Die EDIFACT-KOTR-Dateien (`*.ke0`) werden monatlich aktualisiert und enthalten Kostenträger mit DFU-Verbindungen und VKG-Verknüpfungen zu Annahmestellen.

### 5.1 Automatik-Import

1. Admin-UI → **GKV-Import** → **Alle 12 Dateien importieren**.
2. Dauer: 15–30 Sekunden.
3. Ergebnis wird pro Datei angezeigt (`neu`, `aktualisiert`, `unverändert`).

Zwei Quellen werden abgezogen:

- **SGB V** — `gkv-datenaustausch.de/.../sonstige_leistungserbringer/kostentraegerdateien_sle/`
- **SGB XI** — `gkv-datenaustausch.de/.../pflege/kostentraegerdateien_pflege/`

Jeweils 6 Dateien: AOK, BKK, IKK, Ersatzkassen, Knappschaft, Landwirtschaft.

### 5.2 Manueller Upload

Wenn der GKV-Server gerade nicht erreichbar ist oder eine Testdatei eingespielt werden soll: **Datei hochladen** → Verfahren wählen → **Importieren**.

### 5.3 Eindeutigkeit

Dieselbe IK kann in SGB V und SGB XI unterschiedliche Annahmestellen haben — deshalb ist der eindeutige Schlüssel `(IK, quelle_verfahren)`, **nicht** nur IK.

---

## 6. API nutzen (Integratoren)

### 6.1 Public API — ohne Key

Für Bestandsintegrationen, die gegen den alten Static-JSON-Server gebaut wurden.

```bash
# Manifest mit allen Katalogen + SHA256
curl https://catalog.c3po42.de/catalogs/v1/index.json

# SGB XI Thüringen
curl https://catalog.c3po42.de/catalogs/v1/xi/TH.json

# SGB V HKP (bundesweit)
curl https://catalog.c3po42.de/catalogs/v1/v/BUND.json
```

> **Byte-Stabilität:** Die ausgelieferten Bytes sind **identisch** mit denen, die ins SHA256-Manifest gehasht wurden. Clients können den Hash verifizieren und mitcachen.

### 6.2 Tenant API — mit Key

Key-Übergabe wahlweise per:

- `X-API-Key: prefix.secret`
- `Authorization: ApiKey prefix.secret`

```bash
# Wer bin ich, was darf ich?
curl -H "X-API-Key: pfl_abc.xyz" \
     https://catalog.c3po42.de/api/v1/tenant/me

# Kataloge filtern
curl -H "X-API-Key: pfl_abc.xyz" \
     "https://catalog.c3po42.de/api/v1/tenant/kataloge?sgb=XI&bundesland=TH"

# Leistungen als CSV (Feature csv nötig)
curl -H "X-API-Key: pfl_abc.xyz" \
     "https://catalog.c3po42.de/api/v1/tenant/leistungen?sgb=V&as_csv=true" \
     -o hkp.csv

# Kostenträger suchen (Feature kostentraeger nötig)
curl -H "X-API-Key: pfl_abc.xyz" \
     "https://catalog.c3po42.de/api/v1/tenant/kostentraeger?search=AOK&verfahren=SGB_V"

# Einzel-Kostenträger inkl. VKG-Verknüpfungen
curl -H "X-API-Key: pfl_abc.xyz" \
     "https://catalog.c3po42.de/api/v1/tenant/kostentraeger/107815005?verfahren=SGB_V"
```

### 6.3 Fehlerantworten

| HTTP | Ursache |
|---|---|
| `401` | Kein oder ungültiger Key |
| `402` | Subscription abgelaufen oder inaktiv |
| `403` | Feature nicht im Abo enthalten |
| `404` | Katalog / Kostenträger nicht gefunden |
| `429` | Rate-Limit überschritten (Enterprise: höher) |

Fehler kommen als JSON: `{"detail": "Feature 'csv' not in subscription"}`.

### 6.4 Empfohlene Sync-Reihenfolge für Konsumenten

Wer sowohl Kostenträger als auch Abrechnungsstellen (VKG) nutzt:

1. **Zuerst** Kostenträger pro Verfahren synchronisieren (SGB_V, SGB_XI).
2. **Danach** Abrechnungsstellen / VKG-Beziehungen laden — sie setzen auf den Kostenträgern als Default auf (`Kostentraeger.dta_annahmestelle_ik`).

Datenart-Mapping für DTA:

- `SGB_V` → Datenart `21` (§302 SLLA, häusliche Krankenpflege)
- `SGB_XI` → Datenart `26` (§105 PLAA, Pflege)

---

## 7. Auto-Update

Der Katalog-Service hat den Standard-Update-Mechanismus aller c3po42-Projekte:

- `GET /api/version` — liefert Name und Version
- `GET /api/update/check` — prüft gegen `downloads.c3po42.de/katalog-service/version.json`
- `POST /api/update/install` — installiert die Update-ZIP

Update-Endpoints sind **vor** dem Static-Mount registriert, damit sie nicht von der SPA überschrieben werden.

---

## 8. Audit-Log

Jeder Tenant-Zugriff wird protokolliert:

- **Timestamp**, **Tenant**, **Key-Prefix**, **Endpoint**, **Methode**, **HTTP-Status**
- Admin-UI → **Audit-Log** mit Filter nach Tenant und Zeitraum.
- Export als CSV möglich (Admin-Rolle).

---

## 9. Troubleshooting

| Problem | Ursache / Lösung |
|---|---|
| **401 auf Tenant-Endpoint** | Key falsch oder rotiert — im Admin-UI prüfen |
| **403 auf `?as_csv=true`** | Feature `csv` fehlt im Abo — Subscription upgraden |
| **Kataloge leer nach Deploy** | JSON-Migration nicht gelaufen — `logs/app.log` prüfen, ggf. `journalctl -u catalog-service` |
| **GKV-Import bricht ab** | GKV-Portal oft träge — erneut versuchen; manueller Upload als Fallback |
| **SHA256 stimmt nicht** | Bug-Report an andre@astockma.de — sollte **nicht** passieren, das Manifest wird aus denselben Bytes gehasht |
| **Admin-Login fehlgeschlagen** | Passwort zurücksetzen via SSH: `sudo -u ubuntu python /opt/katalog-service/backend/reset_admin.py` |

Logs auf dem VPS:

```bash
sudo journalctl -u catalog-service -n 100 --no-pager
```

---

## 10. Kontakt

Fragen, Fehler, Feature-Wünsche: **andre@astockma.de**