# BI-API-Referenz

Die BI-API (Business Intelligence) ermoeglicht den Zugriff auf Submission-Daten fuer externe Analysetools wie Power BI, Tableau oder Excel.

## Authentifizierung

Alle BI-API-Endpunkte erfordern:
1. **Sanctum Bearer-Token** mit der Ability `bi:read`
2. **Plan-Feature** `bi_api` muss aktiv sein (ab Professional-Plan)

### Token erstellen

1. Admin-Bereich → API-Tokens
2. Neuen Token mit Ability `bi:read` erstellen
3. Token sicher speichern (wird nur einmal angezeigt)

### Request-Header

```
Authorization: Bearer 1|abc123def456...
```

## Endpunkte

Alle Endpunkte haben den Prefix `/api/bi/`.

---

### GET /bi/templates

Discovery-Endpunkt: Listet alle aktiven Templates.

**Response:**

```json
{
  "templates": [
    {
      "slug": "schnell",
      "title": "Schnellmeldung",
      "description": "Anonyme Kurzerfassung eines Vorfalls"
    },
    {
      "slug": "ausfuehrlich",
      "title": "Ausfuehrliche Meldung",
      "description": "Detaillierte Erfassung mit allen Feldern"
    }
  ]
}
```

---

### GET /bi/{templateSlug}/felder

Metadaten-Endpunkt: Listet alle abfragbaren Felder eines Templates mit verfuegbaren Filtern und Endpunkten.

**Response:**

```json
{
  "template": "schnell",
  "felder": [
    {
      "slug": "gewalt_art",
      "label": "Art der Gewalt",
      "type": "select",
      "is_json_array": false,
      "options": ["koerperlich", "verbal", "sexuell"],
      "block": "Gewaltart",
      "endpoint": "/bi/schnell/stats/feld/gewalt_art"
    },
    {
      "slug": "beteiligte",
      "label": "Beteiligte Personen",
      "type": "checkbox-group",
      "is_json_array": true,
      "options": ["Patient", "Angehoerige", "Personal"],
      "block": "Beteiligte",
      "endpoint": "/bi/schnell/stats/feld/beteiligte"
    }
  ],
  "filter": [
    { "param": "von", "type": "date", "description": "Start-Datum (YYYY-MM-DD)" },
    { "param": "bis", "type": "date", "description": "End-Datum (YYYY-MM-DD)" },
    { "param": "gewalt_art", "type": "string", "description": "Filter nach Art der Gewalt" }
  ],
  "feste_endpunkte": [
    { "path": "/bi/schnell/daten", "description": "Alle Eintraege (paginiert)" },
    { "path": "/bi/schnell/stats/uebersicht", "description": "Uebersichtsstatistiken" },
    { "path": "/bi/schnell/stats/zeitverlauf", "description": "Zeitverlauf (monatlich)" }
  ]
}
```

---

### GET /bi/{templateSlug}/daten

Paginierte Rohdaten aller Submissions eines Templates.

**Query-Parameter:**

| Parameter | Typ | Default | Beschreibung |
|-----------|-----|---------|--------------|
| `pro_seite` | integer | 100 | Eintraege pro Seite (max. 500) |
| `page` | integer | 1 | Seitennummer |
| `von` | date | - | Start-Datum (YYYY-MM-DD) |
| `bis` | date | - | End-Datum (YYYY-MM-DD) |
| `{feldSlug}` | string | - | Dynamischer Filter nach Feldwert |

**Response:**

```json
{
  "current_page": 1,
  "data": [
    {
      "id": 42,
      "template_slug": "schnell",
      "data": { "gewalt_art": "verbal", "bundesland": "Bayern", ... },
      "created_at": "2026-03-15T10:30:00.000000Z",
      "updated_at": "2026-03-15T10:30:00.000000Z"
    }
  ],
  "last_page": 5,
  "per_page": 100,
  "total": 487
}
```

---

### GET /bi/{templateSlug}/stats/uebersicht

Uebersichtsstatistiken fuer ein Template.

**Query-Parameter:** `von`, `bis`, dynamische Feld-Filter.

**Response:**

```json
{
  "gesamt": 487,
  "diesen_monat": 34,
  "letzten_monat": 41,
  "top_werte": {
    "gewalt_art": {
      "label": "Art der Gewalt",
      "wert": "verbal"
    },
    "bundesland": {
      "label": "Bundesland",
      "wert": "Nordrhein-Westfalen"
    }
  }
}
```

`top_werte` enthaelt nur Felder mit `showAsChart: true` in der Block-Definition.

---

### GET /bi/{templateSlug}/stats/zeitverlauf

Monatliche Zeitreihe der Submissions.

**Query-Parameter:**

| Parameter | Typ | Default | Beschreibung |
|-----------|-----|---------|--------------|
| `monate` | integer | 12 | Zeitraum in Monaten |
| `von` | date | - | Start-Datum |
| `bis` | date | - | End-Datum |

**Response:**

```json
{
  "zeitraum_monate": 12,
  "daten": [
    { "monat": "2025-04", "anzahl": 23 },
    { "monat": "2025-05", "anzahl": 31 },
    { "monat": "2025-06", "anzahl": 28 }
  ]
}
```

---

### GET /bi/{templateSlug}/stats/feld/{feldSlug}

Haeufigkeitsverteilung fuer ein einzelnes Feld (GROUP BY).

**Query-Parameter:** `von`, `bis`, dynamische Feld-Filter.

**Response:**

```json
{
  "feld": "gewalt_art",
  "label": "Art der Gewalt",
  "daten": [
    { "bezeichnung": "verbal", "anzahl": 187 },
    { "bezeichnung": "koerperlich", "anzahl": 134 },
    { "bezeichnung": "sexuell", "anzahl": 42 }
  ]
}
```

Fuer JSONB-Array-Felder (z.B. `checkbox-group`) werden die einzelnen Array-Elemente via `jsonb_array_elements_text()` gezaehlt.

---

## Filter-System

Alle Statistik-Endpunkte unterstuetzen einheitliche Filter:

### Zeitfilter

```
GET /bi/schnell/stats/uebersicht?von=2025-01-01&bis=2025-12-31
```

- `von` - Inklusiv, ab Tagesbeginn
- `bis` - Inklusiv, bis Tagesende (23:59:59)

### Feld-Filter

Jedes Select-Feld (nicht Array) kann als Query-Parameter verwendet werden:

```
GET /bi/schnell/stats/zeitverlauf?bundesland=Bayern&gewalt_art=verbal
```

Filter werden als `data->>'{key}' = '{value}'` in SQL umgesetzt.

### Kombinierte Filter

Alle Filter koennen kombiniert werden:

```
GET /bi/schnell/daten?von=2025-06-01&bis=2025-06-30&bundesland=Bayern&pro_seite=50
```

## Use Cases

### Power BI

1. "Daten abrufen" → "Web"
2. URL: `https://instance.eforms.cloud/api/bi/schnell/daten?pro_seite=500`
3. Header: `Authorization: Bearer 1|token...`
4. Daten transformieren und visualisieren

### Tableau

1. "Web Data Connector" oder REST API Connector
2. Base URL + Bearer-Token konfigurieren
3. Endpunkte als Datenquellen einbinden

### Excel / Power Query

1. "Daten" → "Aus dem Web"
2. URL eingeben, Header setzen
3. JSON-Response in Tabelle umwandeln

### cURL-Beispiel

```bash
# Templates auflisten
curl -H "Authorization: Bearer 1|abc..." \
  https://instance.eforms.cloud/api/bi/templates

# Daten abrufen mit Filter
curl -H "Authorization: Bearer 1|abc..." \
  "https://instance.eforms.cloud/api/bi/schnell/daten?von=2025-01-01&pro_seite=100"

# Feld-Statistik
curl -H "Authorization: Bearer 1|abc..." \
  https://instance.eforms.cloud/api/bi/schnell/stats/feld/gewalt_art
```

## Admin: BI-Feld-Metadaten

Admins koennen unter `GET /api/admin/bi/felder` alle Templates mit ihren BI-Feldern einsehen. Dies wird im Admin-UI bei der Token-Erstellung angezeigt, um Nutzern die verfuegbaren Endpunkte zu zeigen.