# CookieSnitch

> DSGVO-Erstprüfung einer Website: CookieSnitch besucht sie wie ein Erstbesucher ohne Einwilligung und meldet Drittanbieter, Cookies, Cookie-Banner, Impressum, Datenschutzerklärung und Technik. Ergebnis: Bericht als JSON (API), HTML und PDF. Keine Rechtsberatung.

Basis-URL: https://cookiesnitch.de
OpenAPI 3.1: https://cookiesnitch.de/openapi.json

## Ablauf

1. POST /api/scans mit JSON {"url": "beispiel.de"} → 202 {"id", "status"}
2. GET /api/scans/:id?wait=60 → antwortet, sobald status "done" oder "error" ist, spätestens nach 60 s mit dem aktuellen Stand. Bei "queued"/"running" erneut aufrufen.
3. Bei status "done" steht der Bericht im Feld "report" (verdict "rot"|"gelb"|"grün", counts, findings, hosts, cookies, …). report.fatal = true: Startseite nicht erreichbar, kein Befund.

## Endpunkte

- POST /api/scans – Prüfung starten. Header Content-Type: application/json. Body {"url": string, "public"?: boolean}. public (Standard true): Scan erscheint in „Letzte Prüfungen“ und in GET /api/scans; false: nicht gelistet, ID mit 128 Bit Zufall, abrufbar für jeden, der die ID kennt.
- GET /api/scans/:id – Stand und Bericht: {id, input, host, status: "queued"|"running"|"done"|"error", verdict, fatal, scannedAt, createdAt, counts, error, progress, report?}. Optional ?wait=<0–60> Sekunden (ganze Zahl).
- DELETE /api/scans/:id – nur mit dem Schlüssel, mit dem der Scan gestartet wurde → 204.
- GET /api/scans – öffentliche Scans (ohne Bericht).
- GET /api/credits – {credits: number|null (null ohne Schlüssel), freeRemaining, freeLimit, resetAt}.
- Bericht für Menschen: https://cookiesnitch.de/scans/:id (HTML), https://cookiesnitch.de/scans/:id/report.pdf (PDF).

## Kosten

- 3 Prüfungen gratis je IP-Adresse in rollierenden 30 Tagen.
- Danach 1 Credit je Prüfung. Credits verfallen nie. Pakete: 10 Credits = 5 €, 50 Credits = 19 €, 200 Credits = 49 €. Kauf im Browser unter https://cookiesnitch.de/credits; danach zeigt die Seite den Schlüssel (cc_…).
- Schlüssel mitsenden: Header Authorization: Bearer cc_… . Erst wird das Gratis-Kontingent der IP verbraucht, dann Credits.
- Endet ein Scan mit status "error" oder report.fatal = true, kommt der Gratis-Versuch bzw. Credit zurück.

## Fehlercodes (Body {"error": "…"})

- 400 ungültige URL, private/interne Adresse, public kein Boolean, ungültige Scan-ID oder wait nicht 0–60
- 401 unbekannter Schlüssel (Authorization: Bearer)
- 402 Gratis-Kontingent und Credits aufgebraucht: {"error", "buyUrl", "freeRemaining": 0, "resetAt"}; Credits kaufen unter buyUrl
- 403 Anfrage aus dem Browser einer fremden Seite, oder DELETE ohne den Schlüssel des Erstellers
- 404 Scan nicht gefunden
- 409 DELETE während der Scan läuft
- 413 Body zu groß (höchstens 16 KB)
- 415 Body ist kein JSON
- 429 Warteschlange voll, in ein paar Minuten erneut versuchen

## Beispiel

curl -s -X POST https://cookiesnitch.de/api/scans -H 'Content-Type: application/json' -H 'Authorization: Bearer cc_…' -d '{"url": "beispiel.de", "public": false}'
curl -s 'https://cookiesnitch.de/api/scans/<id>?wait=60'

Ohne Schlüssel die Zeile Authorization weglassen (Gratis-Kontingent).