Developer Portal|AI Compliance SDK
SDK DashboardGitHub

DSFA API

Datenschutz-Folgenabschätzung (Art. 35 DSGVO) verwalten

Übersicht

Die DSFA API ermöglicht die vollständige Verwaltung von Datenschutz-Folgenabschätzungen gemäß Art. 35 DSGVO. Alle DSFAs werden backend-persistent gespeichert und mit vollständigem Audit-Trail protokolliert.

Wann ist eine DSFA Pflicht?

Eine DSFA ist zwingend erforderlich bei voraussichtlich hohem Risiko für Betroffene: automatisierte Entscheidungen / Profiling, umfangreiche Verarbeitung sensibler Daten, systematische Überwachung öffentlicher Bereiche oder KI-Hochrisiko-Systeme (EU AI Act).

Tenant-ID

Alle Endpoints akzeptieren tenant_id als Query-Parameter. Ohne Angabe wird default als Tenant-ID verwendet.

GET /dsfa

Gibt eine gefilterte Liste aller DSFAs für einen Tenant zurück.

Query-Parameter

ParameterTypeRequiredDescription
tenant_idstringNoTenant-ID (Default: "default")
statusstringNoFilter: draft | in-review | approved | needs-update
risk_levelstringNoFilter: low | medium | high | critical
skipintegerNoOffset für Pagination (Default: 0)
limitintegerNoMax. Einträge (Default: 100, Max: 500)
cURL
curl -X GET "https://api.breakpilot.io/sdk/v1/dsfa?tenant_id=mein-tenant&status=in-review" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response (200)
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tenant_id": "mein-tenant",
    "title": "DSFA - Bewerber-Management-System",
    "description": "KI-gestütztes Bewerber-Screening",
    "status": "in-review",
    "risk_level": "high",
    "processing_activity": "Automatisierte Bewertung von Bewerbungen",
    "data_categories": ["Kontaktdaten", "Beruflicher Werdegang"],
    "recipients": ["HR-Abteilung"],
    "measures": ["Verschlüsselung", "Menschliche Prüfung"],
    "approved_by": null,
    "approved_at": null,
    "created_by": "admin",
    "created_at": "2026-03-04T10:00:00",
    "updated_at": "2026-03-04T10:00:00"
  }
]

POST /dsfa

Erstellt eine neue DSFA. Gibt HTTP 201 mit dem erstellten Datensatz zurück.

cURL
curl -X POST "https://api.breakpilot.io/sdk/v1/dsfa?tenant_id=mein-tenant" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "DSFA - Video-Überwachung Büro",
    "description": "Videoüberwachung zu Sicherheitszwecken",
    "status": "draft",
    "risk_level": "medium",
    "processing_activity": "Videoüberwachung im Eingangsbereich",
    "data_categories": ["Bilddaten", "Bewegungsdaten"],
    "recipients": ["Sicherheitsdienst"],
    "measures": ["Löschfristen 72h", "Hinweisschilder", "Zugangsbeschränkung"],
    "created_by": "dsb@beispiel.de"
  }'
Response (201)
{
  "id": "7b3a1c9d-4e2f-4a8b-9c1d-5f6a7b8c9d0e",
  "tenant_id": "mein-tenant",
  "title": "DSFA - Video-Überwachung Büro",
  "status": "draft",
  "risk_level": "medium",
  "data_categories": ["Bilddaten", "Bewegungsdaten"],
  "measures": ["Löschfristen 72h", "Hinweisschilder", "Zugangsbeschränkung"],
  "created_at": "2026-03-04T12:00:00",
  "updated_at": "2026-03-04T12:00:00"
}

Validierung

status muss einer der Werte draft, in-review, approved, needs-update sein.risk_level muss low, medium, high oder critical sein. Ungültige Werte → HTTP 422.

GET /dsfa/{id}

Gibt eine einzelne DSFA anhand ihrer UUID zurück.

cURL
curl -X GET "https://api.breakpilot.io/sdk/v1/dsfa/7b3a1c9d-4e2f-4a8b-9c1d-5f6a7b8c9d0e?tenant_id=mein-tenant" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT /dsfa/{id}

Aktualisiert eine DSFA. Alle Felder sind optional (Partial Update mit exclude_none). Nur gesetzte Felder werden überschrieben.

cURL
curl -X PUT "https://api.breakpilot.io/sdk/v1/dsfa/7b3a1c9d?tenant_id=mein-tenant" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "measures": ["Löschfristen 72h", "Hinweisschilder", "Biometrischer Zugang"],
    "risk_level": "high"
  }'

PATCH /dsfa/{id}/status

Schnell-Statuswechsel ohne vollständiges Update. Bei Status approved wird approved_at automatisch gesetzt.

Request Body

ParameterTypeRequiredDescription
statusstringYesNeuer Status: draft | in-review | approved | needs-update
approved_bystringNoName/E-Mail des Genehmigers (empfohlen bei status=approved)
cURL
curl -X PATCH "https://api.breakpilot.io/sdk/v1/dsfa/7b3a1c9d/status?tenant_id=mein-tenant" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved",
    "approved_by": "Max Mustermann (DSB)"
  }'

DELETE /dsfa/{id}

Löscht eine DSFA gemäß Art. 17 DSGVO. Die Löschung wird im Audit-Log protokolliert.

cURL
curl -X DELETE "https://api.breakpilot.io/sdk/v1/dsfa/7b3a1c9d?tenant_id=mein-tenant" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response (200)
{
  "success": true,
  "message": "DSFA 7b3a1c9d gelöscht"
}

GET /dsfa/stats

Gibt Zähler nach Status und Risiko-Level zurück.

cURL
curl -X GET "https://api.breakpilot.io/sdk/v1/dsfa/stats?tenant_id=mein-tenant" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response (200)
{
  "total": 5,
  "by_status": {
    "draft": 2,
    "in-review": 1,
    "approved": 2
  },
  "by_risk_level": {
    "low": 1,
    "medium": 2,
    "high": 2
  },
  "draft_count": 2,
  "in_review_count": 1,
  "approved_count": 2,
  "needs_update_count": 0
}

GET /dsfa/audit-log

Gibt den vollständigen Audit-Trail aller DSFA-Aktionen zurück.

Query-Parameter

ParameterTypeRequiredDescription
tenant_idstringNoTenant-ID
limitintegerNoMax. Einträge (Default: 50, Max: 500)
offsetintegerNoStartposition
Response (200)
[
  {
    "id": "uuid",
    "tenant_id": "mein-tenant",
    "dsfa_id": "7b3a1c9d-...",
    "action": "STATUS_CHANGE",
    "changed_by": "system",
    "old_values": { "status": "in-review" },
    "new_values": { "status": "approved" },
    "created_at": "2026-03-04T12:30:00"
  }
]

Audit-Aktionen

Folgende Aktionen werden protokolliert: CREATE, UPDATE, DELETE, STATUS_CHANGE.

Alle Endpoints im Überblick

GET/dsfa

Liste aller DSFAs (Filter: status, risk_level)

POST/dsfa

Neue DSFA anlegen → 201

GET/dsfa/stats

Statistiken nach Status und Risiko

GET/dsfa/audit-log

Audit-Trail aller Aktionen

GET/dsfa/{id}

Einzelne DSFA abrufen

PUT/dsfa/{id}

DSFA aktualisieren (inkl. ai_use_case_modules)

DELETE/dsfa/{id}

DSFA löschen (Art. 17 DSGVO)

PATCH/dsfa/{id}/status

Schnell-Statuswechsel

Section 8: KI-Anwendungsfälle

Section 8 ist ein optionaler modularer Anhang zur DSFA für KI-spezifische Verarbeitungen. Die Module werden im Feld ai_use_case_modules (JSONB-Array) gespeichert und über den normalen PUT /dsfa/{id} Endpoint aktualisiert.

KI-Modul-Typen

Unterstützte Typen: chatbot_nlp, recommendation, adm_scoring, video_image, biometrics, iot_sensors, generative_ai, custom

KI-Modul hinzufügen

# KI-Modul zu bestehender DSFA hinzufügen
curl -sk -X PUT 'https://macmini:8002/api/v1/dsfa/{id}' \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: default' \
  -d '{
    "ai_use_case_modules": [
      {
        "id": "uuid-generated",
        "use_case_type": "generative_ai",
        "name": "GPT-Assistent Kundenservice",
        "model_description": "LLM-basierter Chatbot mit RAG für FAQ-Beantwortung",
        "model_type": "GPT-4o",
        "provider": "OpenAI",
        "third_country_transfer": true,
        "provider_country": "USA",
        "input_data_categories": ["Anfragetexte", "Kundennummer"],
        "output_data_categories": ["Antworttext"],
        "involves_special_categories": false,
        "data_subjects": ["Kunden"],
        "processing_purpose": "Automatisierte Beantwortung von Kundenanfragen",
        "legal_basis": "Art. 6 Abs. 1 lit. b DSGVO (Vertragserfüllung)",
        "art22_assessment": { "applies": false, "safeguards": [] },
        "risk_criteria": [
          { "id": "adm_profiling", "applies": false, "severity": "high" }
        ],
        "ai_act_risk_class": "limited",
        "ai_act_justification": "Chatbot mit Transparenzpflicht nach Art. 52 AI Act",
        "risks": [],
        "mitigations": [],
        "privacy_by_design_measures": [
          { "category": "data_minimisation", "description": "Nur notwendige Daten", "implemented": true }
        ],
        "review_triggers": [
          { "type": "model_update", "description": "Bei Modell-Wechsel", "monitoring_interval": "monatlich" }
        ]
      }
    ]
  }'

TypeScript-Typen

import type { AIUseCaseModule, AIUseCaseType, AIActRiskClass } from '@breakpilot/compliance-sdk'

// Modul erstellen
const module: AIUseCaseModule = {
  id: crypto.randomUUID(),
  use_case_type: 'generative_ai',
  name: 'Mein KI-System',
  model_description: 'Beschreibung...',
  third_country_transfer: false,
  input_data_categories: ['Nutzertexte'],
  output_data_categories: ['Antwort'],
  involves_special_categories: false,
  data_subjects: ['Endnutzer'],
  processing_purpose: 'Kundensupport',
  legal_basis: 'Art. 6 Abs. 1 lit. b DSGVO',
  art22_assessment: { applies: false, safeguards: [] },
  risk_criteria: [],
  ai_act_risk_class: 'limited',
  wp248_criteria_met: ['K4', 'K8'],
  risks: [],
  mitigations: [],
  privacy_by_design_measures: [],
  review_triggers: [],
  created_at: new Date().toISOString(),
  updated_at: new Date().toISOString(),
}