Überblick & Konzepte

Das Modell (in 60 Sekunden)

Das DATEYE Connector-Protokoll ist eine datenschutzfreundliche API, die jedes Backend implementieren kann, um biometrische Messungen vom DATEYE-Desktop-Client zu empfangen. myopia.kids ist die Referenzimplementierung — das Protokoll selbst ist generisch und produktneutral.

Der Ablauf funktioniert in fünf Schritten:

Onboarding: Die Praxis generiert einen Setup-Code (MK-XXXX-XXXX) im Portal. Der Client löst ihn via POST /setup/redeem ein und erhält einen API-Key, die Base-URL (host) und einen encryptionKey (ausschließlich für das DB-Passphrase-Backup verwendet).
Auth: Jede folgende Anfrage trägt Authorization: Bearer <apiKey>.
Import: Der Client sendet Messungen via POST /import. Er identifiziert Patienten ausschließlich durch ein devicePseudonym (ein stabiler, clientseitig berechneter HMAC-Hash) plus grobe Hinweise (Initialen, Geburtsmonat/-jahr) — keine PII.
Verknüpfung: Unbekannte Patienten landen in einer Warteschlange. Ein Mensch verknüpft sie im Portal mit einem echten Patientendatensatz (der Server kann das nicht automatisch — er hat keine PII). Nach der Verknüpfung merkt sich der Server das Mapping devicePseudonym → clientId.
Rückkanäle: Der Client fragt GET /practice/mappings ab (welche Pseudonyme jetzt verknüpft oder widerrufen sind) und GET /rejected-clients (welche Pseudonyme nicht mehr gesendet werden sollen).

Der Server erfährt nie wer der Patient ist — nur, dass „Pseudonym X” Messungen hat. Die Verknüpfung mit der Identität wird von einem Menschen im Portal vorgenommen und verbleibt dort.

Transport & Konventionen

Aspekt	Wert
Base-URL (Prod)	Eigene Domain (z. B. `https://myopia.kids` in der Referenzimplementierung)
Base-URL (Staging)	Eigene Staging-Domain (z. B. `https://dev.myopia.kids`)
Versionierung	Pfad-Präfix `/api/v1/`
Content-Type	`application/json` (Request & Response)
Auth	`Authorization: Bearer <apiKey>` (alternativ `X-API-Key: <apiKey>`)
Timestamps	ISO-8601 UTC (`2026-07-15T10:30:00.000Z`)
Erfolgs-Envelope	`{ "success": true, "data": { … } }`
Fehler-Envelope	`{ "success": false, "error": { "code": "…", "message": "…" } }`

Telemetrie-Header (optional, vom Client gesetzt, serverseitig am API-Key gespeichert):

Header	Bedeutung	Limit
`X-Hostname`	Rechnername der Installation	druckbare ASCII-Zeichen, ≤255
`X-DATEYE-Version`	Client-Version (semver)	≤32
`X-DATEYE-OS`	`windows` oder `macos` (Kleinbuchstaben)	—
`X-DATEYE-Edition`	Produktedition	≤32
`X-DATEYE-Canary-Consent`	`1`/`0` — Opt-in in den Canary-Update-Kanal	—

Rate-Limits (empfohlen 1:1 zu übernehmen, damit der Client identisch reagiert):

Authentifizierte Endpunkte: 120 Anfragen / 60 s pro API-Key (Sliding Window). Bei Überschreitung: 429 mit Header Retry-After: <seconds>.
POST /setup/redeem (unauthentifiziert): 10 Versuche / Stunde pro IP.