API-Referenz

Vollständige REST API-Dokumentation mit Beispielen für alle Endpoints von Barefoot CMP.

Base URL

https://cmp.barefoot-performance.com/v1

Alle API-Requests verwenden diese Base URL als Prefix. Beispiel: GET https://cmp.barefoot-performance.com/v1/config/bf_a1b2c3d4

Allgemeine Informationen

Eigenschaft Wert
Format JSON (Content-Type: application/json)
CORS Global aktiviert (*) für Banner-Requests
Rate Limiting (Paid) 1.000 Requests / Minute
Rate Limiting (Free) 100 Requests / Minute
Encoding UTF-8
Versionierung Über URL-Pfad (/v1/)

Endpoint-Typen

Die API unterscheidet zwischen zwei Typen von Endpoints:

  • Öffentliche Endpoints – Kein Auth erforderlich. Werden vom Banner und öffentlichen Integrationen verwendet (Config, Consent, Geo, Banner-Script).
  • Authentifizierte Endpoints – Erfordern einen gültigen Supabase JWT im Authorization-Header. Werden vom Dashboard und API-Integrationen verwendet (Instanzen, Cookies, Scanner, Billing).

Authentifizierung

So autorisierst du API-Requests an geschützte Endpoints.

JWT-basierte Authentifizierung

Barefoot CMP verwendet Supabase JWT-Tokens für die Authentifizierung. Der Token wird beim Login im Dashboard automatisch generiert und muss bei allen authentifizierten Requests im Authorization-Header mitgeschickt werden.

Authorization: Bearer <your-jwt-token>

Token erhalten

Nach dem Login im Dashboard ist der JWT über Supabase Auth verfügbar. Für programmatischen Zugriff:

JavaScript // Nach Login über Supabase Auth const { data: { session } } = await supabase.auth.getSession(); const token = session.access_token; // Request mit JWT-Token const response = await fetch('https://cmp.barefoot-performance.com/v1/instances', { headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }); const instances = await response.json();

Curl-Beispiel

Bash curl -X GET https://cmp.barefoot-performance.com/v1/instances \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json"

Auth-Config Endpoint

Die Supabase-Verbindungsdaten für Client-seitige Auth können über diesen öffentlichen Endpoint abgerufen werden:

GET /v1/auth/config Öffentlich

Gibt die Supabase-Konfiguration zurück, die für Client-seitige Authentifizierung benötigt wird.

Response:

JSON { "supabaseUrl": "https://xxxxx.supabase.co", "supabaseAnonKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "cmpBaseUrl": "https://cmp.barefoot-performance.com" }

Wichtig: JWT-Tokens haben eine begrenzte Gültigkeit. Supabase erneuert Tokens automatisch. Bei manuellen API-Aufrufen stelle sicher, dass du immer einen aktuellen Token verwendest.

Instanzen

CRUD-Endpoints für CMP-Instanzen (Websites). Alle Endpoints erfordern Authentifizierung.

POST /v1/instances Auth erforderlich

Erstellt eine neue CMP-Instanz für eine Website. Generiert automatisch eine eindeutige CMP-ID im Format bf_XXXXXXXX.

Request-Body:

JSON { "domain": "example.com", "language": "de", "primaryColor": "#2563eb", "position": "bottom", "theme": "light" }

Body-Parameter:

Parameter Typ Status Beschreibung
domain string Erforderlich Domain der Website (ohne https://)
language string Optional Standardsprache (de, en, etc.). Standard: de
primaryColor string Optional Primärfarbe als Hex-Code. Standard: #2563eb
position string Optional Banner-Position (bottom, top). Standard: bottom
theme string Optional Design-Theme (light, dark). Standard: light

Response (201 Created):

JSON { "id": "bf_x7k9m2p4", "domain": "example.com", "language": "de", "primaryColor": "#2563eb", "position": "bottom", "theme": "light", "embedCode": "<script src=\"https://cmp.barefoot-performance.com/v1/loader.js?id=bf_x7k9m2p4\" defer></script>", "createdAt": "2025-02-10T14:30:00Z" }
GET /v1/instances Auth erforderlich

Listet alle CMP-Instanzen des authentifizierten Benutzers auf.

Beispiel-Request:

Bash curl https://cmp.barefoot-performance.com/v1/instances \ -H "Authorization: Bearer <token>"

Response (200 OK):

JSON [ { "id": "bf_x7k9m2p4", "domain": "example.com", "language": "de", "primaryColor": "#2563eb", "position": "bottom", "theme": "light", "createdAt": "2025-02-10T14:30:00Z" }, { "id": "bf_r3t5w8a1", "domain": "shop.example.com", "language": "en", "primaryColor": "#10b981", "position": "bottom", "theme": "dark", "createdAt": "2025-01-20T09:15:00Z" } ]
PUT /v1/instances/:id/config Auth erforderlich

Aktualisiert die Konfiguration einer bestehenden CMP-Instanz. Es müssen nur die zu ändernden Felder mitgeschickt werden (Partial Update).

Request-Body (nur geänderte Felder):

JSON { "primaryColor": "#10b981", "position": "top", "theme": "dark", "showFloatingButton": false }

Beispiel-Request:

Bash curl -X PUT https://cmp.barefoot-performance.com/v1/instances/bf_x7k9m2p4/config \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"primaryColor": "#10b981", "theme": "dark"}'

Response (200 OK):

JSON { "success": true, "instance": { "id": "bf_x7k9m2p4", "domain": "example.com", "primaryColor": "#10b981", "theme": "dark", // ... alle Felder } }
DELETE /v1/instances/:id Auth erforderlich

Löscht eine CMP-Instanz und alle zugehörigen Daten (Consent-Logs, Cookie-Deklarationen, Scan-Ergebnisse).

Achtung: Diese Aktion kann nicht rückgängig gemacht werden! Alle Consent-Logs, Cookie-Deklarationen und Scan-Ergebnisse werden unwiderruflich gelöscht.

Beispiel-Request:

Bash curl -X DELETE https://cmp.barefoot-performance.com/v1/instances/bf_x7k9m2p4 \ -H "Authorization: Bearer <token>"

Response (200 OK):

JSON { "success": true, "message": "Instance bf_x7k9m2p4 and all associated data deleted" }

Scanner

Cookie-Scanner Endpoints zum automatischen Erkennen von Cookies und Trackern auf Websites.

POST /v1/instances/:id/scan/start Auth erforderlich

Startet einen neuen Cookie-Scan für die Website der Instanz. Der Scan läuft asynchron im Hintergrund. Verwendet Puppeteer (wenn verfügbar) oder HTTP-Fallback.

Beispiel-Request:

Bash curl -X POST https://cmp.barefoot-performance.com/v1/instances/bf_a1b2c3d4/scan/start \ -H "Authorization: Bearer <token>"

Response (202 Accepted):

JSON { "success": true, "scanId": "scan_a1b2c3d4-e5f6-7890", "status": "scanning" }

Hinweis: Ein Scan dauert je nach Größe der Website 10-60 Sekunden. Verwende den GET-Endpoint, um den Status und die Ergebnisse abzufragen.

GET /v1/instances/:id/scan Auth erforderlich

Gibt die Ergebnisse des letzten Scans zurück. Zeigt gefundene Cookies, Tracker und den Status.

Beispiel-Request:

Bash curl https://cmp.barefoot-performance.com/v1/instances/bf_a1b2c3d4/scan \ -H "Authorization: Bearer <token>"

Response (200 OK):

JSON { "status": "completed", "scanId": "scan_a1b2c3d4-e5f6-7890", "timestamp": "2025-02-10T03:00:00Z", "duration": 23500, "foundCookies": [ { "name": "_ga", "provider": "Google", "category": "analytics", "purpose": "Google Analytics – Besucher-Unterscheidung", "expiry": "2 Jahre" }, { "name": "_fbp", "provider": "Facebook", "category": "marketing", "purpose": "Facebook Pixel – Retargeting", "expiry": "3 Monate" } ], "foundTrackers": [ "Google Analytics", "Facebook Pixel", "Google Tag Manager" ], "summary": { "totalCookies": 8, "necessary": 2, "analytics": 3, "marketing": 2, "functional": 1 } }

Mögliche Status-Werte:

Status Beschreibung
pending Scan ist in der Warteschlange
scanning Scan läuft aktuell
completed Scan erfolgreich abgeschlossen
failed Scan fehlgeschlagen (z.B. Website nicht erreichbar)
GET /v1/scan/scheduled Intern / Cron

Wöchentlicher Cron-Job Endpoint für geplante Scans. Wird automatisch jeden Montag um 03:00 UTC durch Vercel Cron ausgeführt. Erfordert den X-API-Key-Header zur Autorisierung.

Cron-Schedule: 0 3 * * 1 (Montag 03:00 UTC)

Erforderlicher Header:

HTTP X-API-Key: <SCAN_API_KEY>

Hinweis: Dieser Endpoint ist nur für interne Verwendung durch Vercel Cron Jobs vorgesehen. Der SCAN_API_KEY wird als Environment Variable konfiguriert.

Policy-Generator

Automatische Cookie-Richtlinien-Generierung für Kunden-Websites.

GET /v1/instances/:id/policy Auth erforderlich

Generiert eine vollständige HTML-Cookie-Richtlinie basierend auf den Cookie-Deklarationen der Instanz. Kann direkt als eigenständige Seite verwendet werden.

Beispiel-Request:

Bash curl https://cmp.barefoot-performance.com/v1/instances/bf_a1b2c3d4/policy \ -H "Authorization: Bearer <token>"

Response: Vollständiges HTML-Dokument mit Cookie-Richtlinie (Content-Type: text/html).

GET /v1/instances/:id/policy/data Auth erforderlich

Gibt die Policy-Daten als strukturiertes JSON zurück. Ideal für eigene Darstellungen und Custom-Templates.

Response (200 OK):

JSON { "domain": "example.com", "generatedAt": "2025-02-10T12:00:00Z", "sections": [ { "title": "Was sind Cookies?", "content": "Cookies sind kleine Textdateien..." }, { "title": "Welche Cookies verwenden wir?", "content": "Wir verwenden folgende Kategorien..." } ], "cookiesByCategory": { "necessary": [...], "analytics": [...], "marketing": [...], "functional": [...] }, "legalTexts": { "consentInfo": "Gemäß DSGVO Art. 7...", "rightsInfo": "Sie haben das Recht..." } }
GET /v1/instances/:id/policy/embed Auth erforderlich

Gibt ein einbettbares JavaScript-Snippet zurück, das die Cookie-Richtlinie in eine bestehende Seite (z.B. die Datenschutzseite des Kunden) integriert.

Response: JavaScript-Code (Content-Type: application/javascript), der in die Datenschutzseite eingebunden werden kann:

HTML <!-- In der Datenschutzseite einbinden: --> <div id="barefoot-cookie-policy"></div> <script src="https://cmp.barefoot-performance.com/v1/instances/bf_a1b2c3d4/policy/embed"></script>

Billing

Stripe-basierte Zahlungsabwicklung für Plan-Upgrades und Abonnementverwaltung.

POST /v1/billing/create-checkout Auth erforderlich

Erstellt eine Stripe Checkout Session für ein Plan-Upgrade. Der Benutzer wird zur Stripe-Zahlungsseite weitergeleitet.

Request-Body:

JSON { "plan": "pro" }

Body-Parameter:

Parameter Typ Status Beschreibung
plan string Erforderlich pro (9 EUR/Monat) oder agency (49 EUR/Monat)

Response (200 OK):

JSON { "url": "https://checkout.stripe.com/c/pay/cs_test_..." }

JavaScript-Beispiel:

JavaScript // Checkout starten und Benutzer weiterleiten const response = await fetch('/v1/billing/create-checkout', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ plan: 'pro' }) }); const { url } = await response.json(); window.location.href = url;
POST /v1/billing/create-portal Auth erforderlich

Erstellt eine Stripe Customer Portal Session zur Verwaltung des bestehenden Abonnements (Kündigung, Zahlungsmethode ändern, Rechnungen einsehen).

Response (200 OK):

JSON { "url": "https://billing.stripe.com/p/session/..." }
POST /v1/billing/webhook Intern / Stripe

Stripe Webhook Endpoint für automatische Verarbeitung von Zahlungsevents. Wird von Stripe aufgerufen und validiert die Signatur mit dem Webhook Secret.

Verarbeitete Events:

Event Aktion
checkout.session.completed Plan-Upgrade wird aktiviert, Profil aktualisiert
customer.subscription.updated Plan-Änderung wird übernommen
customer.subscription.deleted Downgrade auf Free-Plan

Hinweis: Dieser Endpoint ist ausschließlich für Stripe Webhooks vorgesehen. Die Webhook-Signatur wird automatisch validiert. Manuelle Aufrufe werden abgelehnt.

Fehlerbehandlung

Fehlerformate, HTTP-Status-Codes und Rate Limiting der API.

Fehler-Format

Alle API-Fehler werden in einem einheitlichen JSON-Format zurückgegeben:

JSON { "error": "Beschreibung des Fehlers" }

Beispiel – Fehlende CMP-ID:

HTTP 400 { "error": "Missing required parameter: cmpId" }

Beispiel – Ungültiger Token:

HTTP 401 { "error": "Invalid or expired JWT token" }

HTTP-Status-Codes

Status Bedeutung Beispiel
200 Erfolg Request erfolgreich verarbeitet
201 Erstellt Neue Ressource erstellt (Instanz, Cookie, Consent)
400 Ungültige Anfrage Fehlende oder ungültige Parameter
401 Nicht autorisiert Fehlender oder ungültiger JWT-Token
403 Verboten Kein Zugriff auf diese Ressource (z.B. fremde Instanz)
404 Nicht gefunden Instanz oder Ressource existiert nicht
429 Rate Limit Zu viele Requests pro Minute
500 Server-Fehler Interner Fehler – bitte Support kontaktieren
503 Nicht verfügbar Service temporär nicht erreichbar (Wartung)

Rate Limiting

Die API begrenzt die Anzahl der Requests pro Minute pro IP-Adresse:

Plan Limit
Free 100 Requests / Minute
Pro / Agency 1.000 Requests / Minute

Rate-Limit-Header:

Jede API-Response enthält Header mit Informationen zum aktuellen Rate-Limit-Status:

HTTP Headers X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 987 X-RateLimit-Reset: 1707566400
Header Beschreibung
X-RateLimit-Limit Maximale Anzahl Requests pro Minute
X-RateLimit-Remaining Verbleibende Requests im aktuellen Zeitfenster
X-RateLimit-Reset Unix-Timestamp, wann das Limit zurückgesetzt wird

Retry-After bei 429

Wenn das Rate Limit überschritten wird, enthält die Response einen Retry-After-Header:

HTTP 429 HTTP/1.1 429 Too Many Requests Retry-After: 30 Content-Type: application/json { "error": "Rate limit exceeded. Please retry after 30 seconds." }

Best Practice: Implementiere exponentielles Backoff bei 429-Responses:

JavaScript async function fetchWithRetry(url, options, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { const response = await fetch(url, options); if (response.status === 429) { const retryAfter = response.headers.get('Retry-After') || 30; console.log(`Rate limited. Waiting ${retryAfter}s...`); await new Promise(r => setTimeout(r, retryAfter * 1000)); continue; } return response; } throw new Error('Max retries exceeded'); }

Support

Bei Fragen zur API oder technischen Problemen: