DATEYE

Ü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:

  1. 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).
  2. Auth: Jede folgende Anfrage trägt Authorization: Bearer <apiKey>.
  3. 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.
  4. 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.
  5. 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.