> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanova.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API für Browser-Ereignisse — POST /ct

> Referenz zum Endpunkt für Browser-Ereignisse, über den das Scanova-Browser-SDK Seitenaufrufe, Klicks und eigene Ereignisse aus dem Browser des Nutzers sendet.

Der Endpunkt `/ct` nimmt die Browser-Ereignisse des Scanova-Browser-SDK entgegen. In der Regel rufen Sie ihn nicht selbst auf — das übernimmt das SDK. Diese Seite beschreibt das Anfrageformat für eigene Anbindungen und zur Fehlersuche.

**Basis-URL:** `https://t.scanova.io`

## Endpunkt

```
POST https://t.scanova.io/ct
```

Ein Authentifizierungs-Header ist nicht nötig. Anfragen werden geprüft, indem der Header `Origin` oder `Referer` gegen die Liste **Allowed Domains** der Website abgeglichen wird.

## Anfrage

**Header:**

```http theme={null}
Content-Type: application/json
Origin: https://yoursite.com
```

**Anfragetext:**

```json theme={null}
{
  "event_id": "f9ac7db6-f900-4d8e-8918-c846834195a8",
  "site_id": "YOUR_SITE_ID",
  "event_type": "cta_click",
  "scan_session_id": "7ad26d4f-3181-4ef8-b6ca-b8f59499dd43",
  "web_session_id": "2d0c328a-01d0-4010-85f4-f327130d1bd4",
  "visitor_id": "363fe851-7d8f-4090-902f-0f5a462829f5",
  "page_url": "https://yoursite.com/pricing",
  "referrer": "https://yoursite.com/",
  "timestamp": "2026-05-13T10:00:00.000Z",
  "device": {
    "user_agent": "Mozilla/5.0 ...",
    "screen_width": 1440,
    "screen_height": 900,
    "language": "en-US"
  },
  "metadata": {
    "button_text": "Start Free Trial",
    "section": "pricing"
  }
}
```

## Felder

| Feld              | Typ               | Pflicht | Beschreibung                                                   |
| ----------------- | ----------------- | ------- | -------------------------------------------------------------- |
| `site_id`         | Zeichenkette      | Ja      | ID der Tracking-Website                                        |
| `event_type`      | Zeichenkette      | Ja      | Name des Ereignisses in snake\_case                            |
| `event_id`        | UUID-Zeichenkette | Nein    | ID zur Dublettenerkennung. Ohne Angabe automatisch erzeugt.    |
| `scan_session_id` | UUID-Zeichenkette | Nein    | Zuordnungs-ID des QR-Code-Scans                                |
| `web_session_id`  | UUID-Zeichenkette | Nein    | Sitzungs-ID im Browser (Zeitfenster von 30 Minuten)            |
| `visitor_id`      | UUID-Zeichenkette | Nein    | Dauerhafte Besucher-ID (Cookie mit einem Jahr Laufzeit)        |
| `page_url`        | Zeichenkette      | Nein    | URL der aktuellen Seite                                        |
| `referrer`        | Zeichenkette      | Nein    | Verweisende URL                                                |
| `timestamp`       | ISO 8601          | Nein    | Zeitpunkt des Ereignisses. Standard ist der Eingangszeitpunkt. |
| `device`          | Objekt            | Nein    | User-Agent, Bildschirmmaße, Sprache                            |
| `metadata`        | Objekt            | Nein    | Eigene Daten. Höchstens 10 KB, fünf Ebenen tief.               |
| `consent`         | Zeichenkette      | Nein    | `granted`, `denied` oder `pending`                             |

## Antwort

**Erfolg (`200`):**

```json theme={null}
{
  "event_id": "f9ac7db6-f900-4d8e-8918-c846834195a8"
}
```

**Fehlerantworten:**

| Status | Ursache                                                                             |
| ------ | ----------------------------------------------------------------------------------- |
| `400`  | Ein Pflichtfeld fehlt oder die `site_id` ist ungültig                               |
| `403`  | `Origin` bzw. `Referer` der Anfrage stehen nicht in den Allowed Domains der Website |
| `413`  | Die Nutzdaten überschreiten die Größengrenze                                        |
| `422`  | Validierungsfehler in einem Feld                                                    |
| `429`  | Ratengrenze überschritten (100 Anfragen pro Minute und IP-Adresse)                  |

## CORS

Der Endpunkt `/ct` unterstützt CORS. Browser-Anfragen von freigegebenen Domains sind erlaubt, und zwar mit:

```
Access-Control-Allow-Origin: <origin>
Access-Control-Allow-Methods: POST, OPTIONS
```

Preflight-Anfragen (`OPTIONS`) liefern `204` samt der passenden CORS-Header.

## Batch-Endpunkt

Um mehrere Browser-Ereignisse in einer Anfrage zu senden:

```
POST https://t.scanova.io/collect/batch
```

Der Anfragetext umschließt ein Array:

```json theme={null}
{
  "events": [
    { "site_id": "...", "event_type": "pageview", ... },
    { "site_id": "...", "event_type": "scroll", "metadata": { "scroll_depth": 25 } }
  ]
}
```

Bis zu 100 Ereignisse je Stapelanfrage.