# HTTP-API

Trackdolphin ist API-first, und zwar wörtlich: Das Dashboard ruft dieselben
Endpunkte auf, die auch dir offenstehen. Es gibt keine Fähigkeit, die nur die
Oberfläche kann.

Daraus folgt der Rest: [MCP-Server](/docs/mcp.md) und
[Kommandozeile](/docs/cli.md) leiten ihre Werkzeuge und Befehle aus der
OpenAPI-Beschreibung ab. Was die API kann, können sie — ohne dass jemand eine
zweite Liste pflegt.

## Beschreibung

- **OpenAPI:** `https://api.trackdolphin.com/api/openapi.json`
- **Zum Blättern:** `https://api.trackdolphin.com/api/docs`

## Anmeldung

Ein API-Schlüssel aus dem Dashboard unter *Einstellungen → API & MCP*:

```bash
curl https://api.trackdolphin.com/api/shops \
  -H "Authorization: Bearer td_live_…"
```

Der Schlüssel gehört zur Organisation, nicht zu einer Person — ein
Automatismus soll nicht stillstehen, weil jemand das Unternehmen verlässt.
Gespeichert wird nur der Hash; der Klartext erscheint genau einmal.

> **Wichtig:** Ein API-Schlüssel kann keine neuen Schlüssel ausstellen. Sonst
> könnte ein Zugang, der nur lesen sollte, sich beliebig viele Nachfolger
> anlegen — und ein Widerruf wäre wertlos.

## Die wichtigsten Endpunkte

| Zweck | Aufruf |
|---|---|
| Shops auflisten | `GET /api/shops` |
| Läuft das Tracking? | `GET /api/shops/{shopId}/health` |
| Kennzahlen | `GET /api/shops/{shopId}/kpis` |
| Kanäle | `GET /api/shops/{shopId}/channels?days=30` |
| Beste Seiten | `GET /api/shops/{shopId}/pages` |
| Kauftrichter | `GET /api/shops/{shopId}/funnel` |
| Stand der Einrichtung | `GET /api/shops/{shopId}/onboarding` |
| Historienimport starten | `POST /api/shops/{shopId}/import` |
| Erkennungsquote | `GET /api/shops/{shopId}/import` |

Jeder Shop gehört zu einer Organisation. Ein fremder Shop antwortet mit `403`,
nicht mit Daten.

## Events senden

Events gehen nicht an die API, sondern an den Collector — einen eigenen Dienst
am Rand des Netzes, damit ein Ausfall der Verwaltung keine Events kostet:

```bash
curl -X POST https://td.meinshop.de/collect \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "order_1042",
    "shop_id": "shop_meinshop_de_ab12cd",
    "type": "purchase",
    "value": 119.90,
    "currency": "EUR",
    "em": "…sha256 der E-Mail…"
  }'
```

`em` und `ph` **müssen** bereits gehasht ankommen. Klartext wird mit `400`
abgewiesen — siehe [Match-Qualität](/docs/matching.md).

Schlüssel erstellst und widerrufst du im Dashboard, siehe
[Einstellungen — API & MCP](/docs/app-einstellungen-api-mcp.md).