BreakPilot Developer Portal

Übersicht

Die Consent Management API ermöglicht die vollständige Verwaltung von Nutzereinwilligungen (Art. 6 Abs. 1a, Art. 7 DSGVO), rechtlichen Dokumenten (Art. 13/14 DSGVO) und Cookie-Banner-Konfigurationen (TTDSG § 25).

Tenant-ID erforderlich

Alle Endpoints erfordern den Header X-Tenant-ID mit Ihrer Tenant-ID. Ohne diesen Header erhalten Sie einen 400-Fehler.

Consent Management

Verwalten Sie Einwilligungsnachweise granular nach Nutzer und Datenpunkt. Jede Einwilligung wird mit vollständiger Änderungshistorie protokolliert.

GET /einwilligungen/consents

Gibt eine paginierte Liste aller Einwilligungen zurück.

Query-Parameter

Parameter	Type	Required	Description
`limit`	`integer`	No	Einträge pro Seite (Default: 50, Max: 500)
`offset`	`integer`	No	Startposition für Pagination (Default: 0)
`user_id`	`string`	No	Filtert nach Nutzer-ID
`data_point_id`	`string`	No	Filtert nach Datenpunkt-ID
`granted`	`boolean`	No	Filtert nach Einwilligungsstatus (true/false)

cURL

curl -X GET "https://api.breakpilot.io/sdk/v1/einwilligungen/consents?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: your-tenant-id"

Response (200)

{
  "total": 1234,
  "offset": 0,
  "limit": 50,
  "consents": [
    {
      "id": "uuid",
      "tenant_id": "your-tenant-id",
      "user_id": "nutzer@beispiel.de",
      "data_point_id": "dp_analytics",
      "granted": true,
      "granted_at": "2024-01-15T10:30:00Z",
      "revoked_at": null,
      "consent_version": "v1.2",
      "source": "web_banner",
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "created_at": "2024-01-15T10:30:00Z",
      "history": [
        {
          "id": "uuid",
          "action": "granted",
          "consent_version": "v1.2",
          "ip_address": "192.168.1.1",
          "user_agent": "Mozilla/5.0...",
          "source": "web_banner",
          "created_at": "2024-01-15T10:30:00Z"
        }
      ]
    }
  ]
}

GET/einwilligungen/consents

Consent-Liste mit Pagination und Filtern

POST /einwilligungen/consents

Erfasst eine neue Einwilligung. Erstellt automatisch einen History-Eintrag mit action="granted".

Parameter	Type	Required	Description
`user_id`	`string`	Yes	Nutzer-ID oder E-Mail
`data_point_id`	`string`	Yes	ID des Datenpunkts (z.B. dp_analytics)
`granted`	`boolean`	Yes	true = Einwilligung erteilt
`consent_version`	`string`	No	Version der Datenschutzerklärung (Default: 1.0)
`source`	`string`	No	Quelle der Einwilligung (z.B. web_banner, api)
`ip_address`	`string`	No	IP-Adresse des Nutzers (IPv4/IPv6)
`user_agent`	`string`	No	Browser/Client User-Agent

cURL

curl -X POST "https://api.breakpilot.io/sdk/v1/einwilligungen/consents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "nutzer@beispiel.de",
    "data_point_id": "dp_analytics",
    "granted": true,
    "consent_version": "v1.2",
    "source": "web_banner",
    "ip_address": "192.168.1.1"
  }'

Response (201)

{
  "success": true,
  "id": "uuid",
  "user_id": "nutzer@beispiel.de",
  "data_point_id": "dp_analytics",
  "granted": true,
  "granted_at": "2024-01-15T10:30:00Z"
}

POST/einwilligungen/consents

Neue Einwilligung erfassen (erstellt automatisch History-Eintrag)

PUT /einwilligungen/consents/{id}/revoke

Widerruft eine aktive Einwilligung. Setzt revoked_at auf den aktuellen Zeitstempel und erstellt einen History-Eintrag mit action="revoked".

Nicht rückgängig machbar

Ein Widerruf kann nicht rückgängig gemacht werden. Für eine neue Einwilligung muss ein neuer POST-Request gesendet werden.

cURL

curl -X PUT "https://api.breakpilot.io/sdk/v1/einwilligungen/consents/CONSENT_ID/revoke" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: your-tenant-id"

Response (200)

{
  "success": true,
  "id": "uuid",
  "revoked_at": "2024-02-01T14:00:00Z"
}

PUT/einwilligungen/consents/{id}/revoke

Einwilligung widerrufen (setzt revoked_at, erstellt History-Eintrag)

GET /einwilligungen/consents/{id}/history

Gibt die vollständige Änderungshistorie einer Einwilligung zurück. Alle Aktionen (granted, revoked, version_update, renewed) werden chronologisch aufgelistet.

cURL

curl -X GET "https://api.breakpilot.io/sdk/v1/einwilligungen/consents/CONSENT_ID/history" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: your-tenant-id"

Response (200)

[
  {
    "id": "uuid",
    "consent_id": "uuid",
    "action": "granted",
    "consent_version": "v1.0",
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "source": "web_banner",
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "uuid",
    "consent_id": "uuid",
    "action": "revoked",
    "consent_version": "v1.0",
    "ip_address": null,
    "user_agent": null,
    "source": null,
    "created_at": "2024-02-01T14:00:00Z"
  }
]

GET/einwilligungen/consents/{id}/history

Änderungshistorie einer Einwilligung (chronologisch, älteste zuerst)

GET /einwilligungen/consents/stats

Gibt Statistiken über alle Einwilligungen des Tenants zurück.

Response (200)

{
  "total_consents": 1234,
  "active_consents": 1100,
  "revoked_consents": 134,
  "unique_users": 800,
  "conversion_rate": 89.2,
  "by_data_point": {
    "dp_analytics": { "total": 600, "active": 550, "revoked": 50 },
    "dp_marketing": { "total": 634, "active": 550, "revoked": 84 }
  }
}

GET/einwilligungen/consents/stats

Einwilligungs-Statistiken nach Datenpunkt und Nutzer

Legal Documents API

Verwalten Sie rechtliche Dokumente (Datenschutzerklärung, AGB, Cookie-Richtlinie, Impressum, AVV) mit vollständigem Versionierungs- und Freigabe-Workflow.

Proxy-Route

Frontend-Proxy: /api/admin/consent/* → backend:8002/api/compliance/legal-documents/*

GET /legal-documents/documents

Gibt alle rechtlichen Dokumente des Tenants zurück.

cURL

curl -X GET "https://api.breakpilot.io/sdk/v1/legal-documents/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: your-tenant-id"

GET/legal-documents/documents

Alle rechtlichen Dokumente (Filter: tenant_id, document_type, status)

POST /legal-documents/documents

Legt ein neues rechtliches Dokument an (initial als Entwurf).

Parameter	Type	Required	Description
`title`	`string`	Yes	Titel des Dokuments
`document_type`	`string`	Yes	privacy_policy \| terms \| cookie_policy \| imprint \| dpa
`language`	`string`	No	Sprache (Default: de)

POST/legal-documents/documents

Neues rechtliches Dokument anlegen (Status: draft)

GET /legal-documents/documents/{id}/versions

Gibt alle Versionen eines Dokuments zurück.

Array-Response

Dieser Endpoint gibt ein direktes JSON-Array zurück, nicht ein Objekt mit versions-Key. Frontend-Code mussArray.isArray(data) ? data : (data.versions || []) prüfen.

Response (200) — direktes Array

[
  {
    "id": "uuid",
    "document_id": "uuid",
    "version_number": 3,
    "title": "Datenschutzerklärung v3",
    "status": "published",
    "created_at": "2024-01-20T14:00:00Z",
    "published_at": "2024-01-21T09:00:00Z"
  }
]

GET/legal-documents/documents/{id}/versions

Alle Versionen eines Dokuments (gibt direktes Array zurück)

POST /legal-documents/versions/{id}/publish

Veröffentlicht eine freigegebene Version. Status muss "approved" sein.

POST/legal-documents/versions/{id}/publish

Freigegebene Version veröffentlichen (approved → published)

Cookie Banner API

Konfigurieren Sie den Cookie-Banner für Ihre Anwendung. Die Konfiguration wird in der Datenbank persistiert und überlebt Container-Neustarts.

GET /einwilligungen/cookies

Lädt die Cookie-Banner-Konfiguration des Tenants.

cURL

curl -X GET "https://api.breakpilot.io/sdk/v1/einwilligungen/cookies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: your-tenant-id"

Response (200)

{
  "tenant_id": "your-tenant-id",
  "categories": [
    {
      "id": "necessary",
      "name": "Notwendig",
      "isRequired": true,
      "defaultEnabled": true
    },
    {
      "id": "analytics",
      "name": "Analyse",
      "isRequired": false,
      "defaultEnabled": false
    }
  ],
  "config": {
    "position": "bottom",
    "style": "bar",
    "primaryColor": "#6366f1",
    "showDeclineAll": true,
    "showSettings": true,
    "banner_texts": {
      "title": "Wir verwenden Cookies",
      "description": "Wir nutzen Cookies, um unsere Website zu verbessern.",
      "privacyLink": "/datenschutz"
    }
  },
  "updated_at": "2024-01-15T10:30:00Z"
}

GET/einwilligungen/cookies

Cookie-Banner-Konfiguration laden (Kategorien + Config + Banner-Texte)

PUT /einwilligungen/cookies

Speichert die Cookie-Banner-Konfiguration (Upsert). Alle Felder werden vollständig überschrieben.

cURL

curl -X PUT "https://api.breakpilot.io/sdk/v1/einwilligungen/cookies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "categories": [
      { "id": "necessary", "name": "Notwendig", "isRequired": true, "defaultEnabled": true }
    ],
    "config": {
      "position": "bottom",
      "style": "bar",
      "primaryColor": "#6366f1",
      "banner_texts": {
        "title": "Wir verwenden Cookies",
        "description": "...",
        "privacyLink": "/datenschutz"
      }
    }
  }'

PUT/einwilligungen/cookies

Cookie-Banner-Konfiguration speichern (Upsert, inkl. Banner-Texte)