eforms.cloud – BI-API Dokumentation

Inhaltsverzeichnis

Was ist die BI-API?
API-Token erstellen
Authentifizierung
BI-Endpoints
Filter-Parameter
Token-Verwaltung (Admin-API)
Verbindung mit Power BI
Verbindung mit Tableau
Sicherheit & Best Practices

1. Was ist die BI-API?

Die BI-API stellt speziell aufbereitete Statistik-Endpunkte bereit, die fuer die Anbindung an Business-Intelligence-Tools optimiert sind. Die Daten werden als flache JSON-Strukturen geliefert, die sich direkt in Tools wie Power BI, Tableau oder Excel importieren lassen.

Basis-URL: https://ihre-domain.de/api/bi/

Funktionsumfang:

Paginierte Rohdaten aller Submissions (JSONB) mit flexiblen Filtern
Metadaten-Endpunkt: verfuegbare Felder und Filter automatisch ermitteln
Aggregierte Statistiken (Gesamtzahlen, Monatstrends, Top-Werte)
Zeitreihen-Daten fuer Diagramme
Dynamische Aufschluesselungen nach jedem konfigurierten Select- oder Checkbox-Feld
Tokenbasierte Authentifizierung mit eingeschraenkten Rechten

2. API-Token erstellen

Fuer den Zugriff auf die BI-API wird ein spezieller API-Token benoetigt. Dieser wird von einem Admin-Benutzer erstellt und hat ausschliesslich Lesezugriff auf die BI-Endpunkte.

Schritt 1: Als Admin einloggen

curl -X POST https://ihre-domain.de/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@beispiel.de", "password": "IhrPasswort"}'

Antwort:

{
  "token": "1|admin-token-hier...",
  "user": { "id": 1, "name": "Admin", "email": "admin@beispiel.de" }
}

Schritt 2: BI-Token erstellen

curl -X POST https://ihre-domain.de/api/admin/tokens \
  -H "Authorization: Bearer 1|admin-token-hier..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Power BI Dashboard", "expires_at": "2027-12-31T23:59:59Z"}'

Antwort:

{
  "token": "2|bi-token-hier-sicher-aufbewahren...",
  "name": "Power BI Dashboard",
  "abilities": ["bi:read"],
  "expires_at": "2027-12-31T23:59:59.000000Z",
  "created_at": "2026-03-19T12:00:00.000000Z"
}

Wichtig: Der Token wird nur einmalig bei der Erstellung im Klartext angezeigt. Bewahren Sie ihn sicher auf! Er kann nicht erneut abgerufen werden.

3. Authentifizierung

Alle BI-Endpunkte erfordern einen gueltigen Bearer-Token im Authorization-Header:

Authorization: Bearer 2|bi-token-hier...

Der Token muss die Berechtigung bi:read besitzen. Admin-Tokens (mit Wildcard-Berechtigung *) funktionieren ebenfalls.

Fehler-Codes

HTTP-Code	Bedeutung
`401`	Kein Token oder ungueltiger Token
`403`	Token hat keine `bi:read` Berechtigung
`200`	Erfolgreiche Anfrage

4. BI-Endpoints

Die BI-API arbeitet dynamisch: Die verfuegbaren Feld-Endpunkte werden automatisch aus den konfigurierten Formular-Bloecken abgeleitet. Ueber den Metadaten-Endpunkt lassen sich alle aktuellen Endpunkte und Filter programmatisch abrufen.

Metadaten (Feld-Discovery)

Methode	Endpunkt	Beschreibung
GET	`/api/bi/felder`	Verfuegbare Templates, abfragbare Felder und Filter-Parameter

Optionaler Parameter: template (Template-Slug) – schraenkt die Felder auf ein bestimmtes Formular-Template ein.

Feste Endpunkte

Methode	Endpunkt	Beschreibung
GET	`/api/bi/daten`	Alle Eintraege (paginiert, JSONB-Rohdaten)
GET	`/api/bi/stats/uebersicht`	Gesamtzahlen, Monatstrends und Top-Werte
GET	`/api/bi/stats/zeitverlauf`	Monatliche Zeitreihe

Parameter fuer /bi/daten: pro_seite (Standard: 100, Max: 500), page

Parameter fuer /bi/stats/zeitverlauf: monate (Standard: 12)

Dynamische Feld-Endpunkte

Methode	Endpunkt	Beschreibung
GET	`/api/bi/stats/feld/{feldSlug}`	Aufschluesselung nach einem bestimmten Feld (GROUP BY)

Welche Feld-Slugs verfuegbar sind, haengt von den konfigurierten Formular-Bloecken ab. Felder vom Typ select und checkbox-group werden automatisch als abfragbar erkannt. Die vollstaendige Liste ist ueber /api/bi/felder abrufbar.

Tipp: In der Admin-Oberflaeche unter API-Token Verwaltung werden alle aktuellen Endpunkte inklusive kopierbarer URLs angezeigt.

Beispiel-Antworten

GET /api/bi/felder

{
  "templates": [
    { "slug": "meldung", "title": "Meldung", "description": "..." }
  ],
  "feste_endpunkte": [
    { "path": "/bi/daten", "description": "Alle Eintraege (paginiert)" },
    { "path": "/bi/stats/uebersicht", "description": "Uebersichtsstatistiken" },
    { "path": "/bi/stats/zeitverlauf", "description": "Zeitverlauf (monatlich)" }
  ],
  "felder": [
    {
      "slug": "ereignisort",
      "label": "Ereignisort",
      "type": "select",
      "is_json_array": false,
      "block": "Allgemeine Angaben",
      "endpoint": "/bi/stats/feld/ereignisort"
    },
    {
      "slug": "gewaltarten",
      "label": "Gewaltarten",
      "type": "checkbox-group",
      "is_json_array": true,
      "block": "Gewalt-Details",
      "endpoint": "/bi/stats/feld/gewaltarten"
    }
  ],
  "filter": [
    { "param": "von", "type": "date", "description": "Start-Datum (YYYY-MM-DD)" },
    { "param": "bis", "type": "date", "description": "End-Datum (YYYY-MM-DD)" },
    { "param": "template", "type": "string", "description": "Filter nach Template-Slug" },
    { "param": "ereignisort", "type": "string", "description": "Filter nach Ereignisort" }
  ]
}

GET /api/bi/stats/uebersicht

{
  "gesamt": 142,
  "diesen_monat": 12,
  "letzten_monat": 8,
  "top_werte": {
    "ereignisort": { "label": "Ereignisort", "wert": "Station" },
    "einrichtungsart": { "label": "Einrichtungsart", "wert": "Krankenhaus" }
  }
}

Zeitverlauf

Methode	Endpunkt	Beschreibung
GET	`/api/bi/stats/zeitverlauf`	Monatliche Zeitreihe (konfigurierbarer Zeitraum)

Parameter: monate (Standard: 12)

curl "https://ihre-domain.de/api/bi/stats/zeitverlauf?monate=6" \
  -H "Authorization: Bearer 2|bi-token..."

Antwort:

{
  "zeitraum_monate": 6,
  "daten": [
    { "monat": "2025-10", "anzahl": 15 },
    { "monat": "2025-11", "anzahl": 22 },
    { "monat": "2025-12", "anzahl": 18 },
    { "monat": "2026-01", "anzahl": 25 },
    { "monat": "2026-02", "anzahl": 8 },
    { "monat": "2026-03", "anzahl": 12 }
  ]
}

GET /api/bi/stats/feld/ereignisort

{
  "feld": "ereignisort",
  "label": "Ereignisort",
  "daten": [
    { "bezeichnung": "Station", "anzahl": 35 },
    { "bezeichnung": "OP-Saal", "anzahl": 28 },
    { "bezeichnung": "Notaufnahme", "anzahl": 19 }
  ]
}

GET /api/bi/daten?pro_seite=2

{
  "data": [
    {
      "id": 1,
      "template_slug": "meldung",
      "data": { "ereignisort": "Station", "gewaltarten": ["Verbal", "Koerperlich"], ... },
      "created_at": "2026-03-15T10:30:00Z"
    }
  ],
  "current_page": 1,
  "last_page": 71,
  "per_page": 2,
  "total": 142
}

Weitere Beispiele:

# Nach Bundesland
curl "https://ihre-domain.de/api/bi/stats/feld/bundesland" \
  -H "Authorization: Bearer 2|bi-token..."

# Nach Einrichtungsart
curl "https://ihre-domain.de/api/bi/stats/feld/einrichtungsart" \
  -H "Authorization: Bearer 2|bi-token..."

# Nach Berufsgruppe, gefiltert auf Bayern
curl "https://ihre-domain.de/api/bi/stats/feld/berufsgruppe?bundesland=Bayern" \
  -H "Authorization: Bearer 2|bi-token..."

Hinweis: Falls ein Feld nicht abfragbar ist, liefert der Endpunkt 404 mit einer erklaerenden Fehlermeldung.

5. Filter-Parameter

Alle BI-Endpunkte unterstuetzen optionale Filter-Parameter. Neben den festen Filtern stehen auch alle skalaren Select-Felder als dynamische Filter zur Verfuegung. Die verfuegbaren Filter sind ueber /api/bi/felder abrufbar.

Feste Filter

Parameter	Typ	Beschreibung	Beispiel
`von`	Datum	Startdatum (YYYY-MM-DD, inklusiv)	`2025-01-01`
`bis`	Datum	Enddatum (YYYY-MM-DD, inklusiv)	`2025-12-31`
`template`	String	Nach Formular-Template filtern	`meldung`
`monate`	Zahl	Zeitraum fuer Zeitverlauf (nur bei `/stats/zeitverlauf`)	`6`
`pro_seite`	Zahl	Eintraege pro Seite (nur bei `/daten`, Max: 500)	`50`

Dynamische Feld-Filter

Jedes skalare Select-Feld (nicht checkbox-group) kann als Query-Parameter verwendet werden. Welche Felder verfuegbar sind, zeigt der /api/bi/felder-Endpunkt unter filter.

Beispiel mit Filtern:

curl "https://ihre-domain.de/api/bi/stats/uebersicht?von=2025-01-01&bis=2025-12-31&ereignisort=Station" \
  -H "Authorization: Bearer 2|bi-token..."

Hinweis: Filter werden auf alle Endpunkte angewendet – sowohl auf /bi/daten als auch auf /bi/stats/*.

6. Token-Verwaltung (Admin-API)

Admins koennen BI-Tokens ueber die folgenden Endpunkte verwalten. Dafuer wird ein Admin-Token (Login-Token) benoetigt.

Methode	Endpunkt	Beschreibung
GET	`/api/admin/tokens`	Alle Tokens auflisten
POST	`/api/admin/tokens`	Neuen BI-Token erstellen
DELETE	`/api/admin/tokens/{id}`	Token widerrufen

Token erstellen

curl -X POST https://ihre-domain.de/api/admin/tokens \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mein BI-Dashboard",
    "expires_at": "2027-12-31T23:59:59Z"
  }'

Das Feld expires_at ist optional. Ohne Angabe ist der Token unbegrenzt gueltig.

Alle Tokens auflisten

curl https://ihre-domain.de/api/admin/tokens \
  -H "Authorization: Bearer ADMIN_TOKEN"

Token widerrufen

curl -X DELETE https://ihre-domain.de/api/admin/tokens/5 \
  -H "Authorization: Bearer ADMIN_TOKEN"

7. Verbindung mit Power BI

Schritt 1: Web-Datenquelle einrichten

Power BI Desktop oeffnen
Daten abrufen → Web auswaehlen
Erweitert anklicken
URL eintragen: https://ihre-domain.de/api/bi/stats/zeitverlauf
HTTP-Header hinzufuegen:
- Name: Authorization
- Wert: Bearer 2|ihr-bi-token...
Mit OK bestaetigen

Schritt 2: Daten transformieren

Im Power Query Editor die JSON-Antwort in eine Tabelle umwandeln
Das Feld daten expandieren (Liste → Tabelle)
Spalten wie monat und anzahl konfigurieren
Schliessen & Laden auswaehlen

Schritt 3: Mehrere Endpunkte kombinieren

Wiederholen Sie den Vorgang fuer jeden Endpunkt, den Sie nutzen moechten:

/api/bi/stats/feld/{feldSlug} fuer Aufschluesselungen (z. B. Tortendiagramme)
/api/bi/stats/uebersicht fuer KPI-Kacheln
/api/bi/stats/zeitverlauf fuer Zeitreihen-Diagramme
/api/bi/daten fuer Detailtabellen
/api/bi/felder fuer dynamische Feld-Discovery

Welche Feld-Slugs verfuegbar sind, erfahren Sie ueber /api/bi/felder.

Tipp: Richten Sie einen geplanten Aktualisierungszeitplan ein, damit Ihr Dashboard automatisch aktuelle Daten abruft.

8. Verbindung mit Tableau

Option A: Web Data Connector

Tableau Desktop oeffnen
Verbinden → Web Data Connector
Eigenen WDC erstellen oder einen generischen JSON-WDC verwenden
API-URL und Bearer-Token konfigurieren

Option B: Python/TabPy Integration

import requests
import pandas as pd

headers = {"Authorization": "Bearer 2|ihr-bi-token..."}
url = "https://ihre-domain.de/api/bi/stats/zeitverlauf?monate=12"

# Oder dynamisch: alle verfuegbaren Felder ermitteln
# felder_url = "https://ihre-domain.de/api/bi/felder"
# felder = requests.get(felder_url, headers=headers).json()
# for feld in felder["felder"]:
#     stats = requests.get(f"https://ihre-domain.de/api{feld['endpoint']}", headers=headers)

response = requests.get(url, headers=headers)
data = response.json()

df = pd.DataFrame(data["daten"])
print(df)

Option C: Hyper API / Automatisierter Export

Fuer automatisierte Tableau-Dashboards koennen Sie die API-Daten per Skript in eine Hyper-Datei schreiben und in Tableau Server/Cloud hochladen.

9. Sicherheit & Best Practices

Token-Rotation: Erstellen Sie regelmaessig neue Tokens und widerrufen Sie alte.
Ablaufdatum setzen: Verwenden Sie expires_at um Tokens zeitlich zu begrenzen.
Minimale Rechte: BI-Tokens haben nur bi:read-Berechtigung und koennen keine Daten aendern oder Admin-Funktionen nutzen.
HTTPS verwenden: Senden Sie Tokens niemals ueber unverschluesselte HTTP-Verbindungen.
Token sicher speichern: Speichern Sie Tokens in sicheren Umgebungsvariablen oder Credential-Managern, nicht im Klartext in Skripten.
Zugriff ueberwachen: Pruefen Sie regelmaessig die Token-Liste und entfernen Sie nicht mehr benoetigte Tokens.

Achtung: Teilen Sie Tokens nicht per E-Mail oder Chat. Nutzen Sie sichere Kanaele zur Weitergabe.