RideVerse

PARTNER-API · STAND 14. NOVEMBER 2026

Entwickler-Dokumentation

1. Beta ohne Schlüssel

POST https://cellystudio.de/api/rideverse/beta mit Content-Type: application/json. Beispiel: {"operation":"alert","data":{}}. Erlaubte Operationen: status, profile, inviteContact, startRide, finishRide, alert, position, stop. Das Datenobjekt muss leer sein. Es gibt keine echte Anmeldung und keine nutzbare Firebase-Nutzersitzung in der Beta.

Alle Beta-Antworten tragen environment: beta, simulation: true, persisted: false, notificationsSent: 0 und realAlarm: false. „alert“ liefert nur einen simulierten Countdown; es wird kein zeitgesteuerter echter Alarm angelegt. Die zurückgegebene Beispielposition 0,0 ist keine Ortung. Ein Aufruf verändert keinen dauerhaften Zustand.

2. App anmelden

Registriere App- und Entwicklerdaten, eine App-Webseite, Datenschutz-URL, Plattformen und einen YouTube-Testvideolink. Der Code an deine Kontakt-E-Mail gilt zehn Minuten und erlaubt höchstens fünf Fehlversuche. Standardmäßig sind drei Code-Anforderungen je E-Mail und UTC-Tag sowie zwanzig je Server-IP und UTC-Tag möglich. Nach Bestätigung wird dein Antrag zentral zur persönlichen Prüfung gespeichert.

3. Testvideo und Freigabe

Zeige die Einrichtung mit Beispieldaten, Einwilligung, Kontaktbestätigung, Alarm und Abbruch, Standortfreigabe, Fehlerfälle und Branding. Falls deine App automatische Erkennung anbietet, zeige sie im Testmodus. Lade das Video bei YouTube öffentlich oder nicht gelistet hoch und reiche den einzelnen Videolink ein. Nur der Studioinhaber kann den Link über unseren Prüfbereich abrufen.

Nach Freigabe folgt die Zugangsmail automatisch. Der Abruflink ist 72 Stunden gültig und wird erst durch den bewussten Abruf auf der Seite verbraucht. Speichere Partner-ID und Server-Schlüssel sicher. Ein erneuter Abruflink kann durch den Inhaber versandt werden; dabei wird der produktive Schlüssel nicht stillschweigend verändert.

4. Produktive Serveranbindung

Produktiv-Endpunkt: POST https://cellystudio.de/api/rideverse/partner. Installiere den bereitgestellten Node.js-Server-Client in deinem Backend und übergib endpoint, partnerId und serverKey aus sicheren Server-Umgebungsvariablen. Der Client verwendet X-RV-App, X-RV-Timestamp, X-RV-Nonce und X-RV-Signature; der kanonische Signaturpfad bleibt /v1/safety. Die Signatur bindet den unveränderten JSON-Inhalt und schützt gegen Wiederholungen. Der geheime Schlüssel gehört nie in die mobile App oder einen Browser-Build.

5. Nutzer und Notfallkontakte

Die derzeitige produktive API registriert über registerEmail und verifyRegistration separate, partnergebundene Notfallkonten. Nutze dafür eine eigene benannte Firebase-Instanz, damit die Anmeldung deiner Host-App erhalten bleibt. Außer den Registrierungsschritten verlangen produktive Aktionen zusätzlich das Firebase ID Token des betroffenen Nutzers als Bearer-Token. Notfallpass, Kontakte, Einwilligungen und Alarmstatus werden zentral bei RideVerse verwaltet.

Bestehende RideVerse-Konten verknüpfst du mit registerEmail und dem Feld linkExisting: true. Der Code geht an die E-Mail-Adresse des Kontos; nach verifyRegistration erhält deine App eine Sitzung für dieses Konto. Notfallpass und Kontakte bleiben bei RideVerse, deine App erhält sie nicht. Eine produktive Integration muss die Einwilligungs- und gegebenenfalls Sorgeberechtigten-Freigaben des vorhandenen Systems beachten. Die Freunde-Karte ist nicht Teil der Partner-API.

6. Verfügbare Operationen und Dateien

Die produktive API bietet status, profile, guardian, inviteContact, removeContact, preferences, vehicle, startRide, finishRide, alert, position, stop und deleteAccount, nach gesonderter Freigabe außerdem relayRegisterKey, relayUnregisterKeys und relay (Abschnitt 8). E-Mail-Bestätigung: registerEmail und verifyRegistration. Briefbestätigung ist nicht mehr erforderlich. Eine neue API-Anmeldung erstellt kein öffentliches Community-Profil.

Der Server-Client und das Web-Widget sind Vorlagen. Das Widget trägt „Powered by RideVerse“ und benötigt die sichere Verbindung zum eigenen Backend. Sensorerkennung und Hintergrundbetrieb gehören in die jeweilige App. Es gibt derzeit kein veröffentlichtes natives Android- oder iOS-SDK.

7. Fristen und Verhalten beim Alarm

alert startet einen Countdown von 60 Sekunden; mit automatic: true (von deiner App erkannter Sturz) sind es 30 Sekunden. Der Server gibt die Frist vor und meldet sie in der Antwort (incidentId, dispatchAt, endsAt); zeige den Countdown trotzdem sofort lokal an. Kommt der Alarm wegen fehlendem Netz verspätet an, sende localElapsedMs mit (bereits lokal abgelaufene Millisekunden), dann rechnet der Server sie an. stop vor Ablauf bricht ab, verspätete Antworten eines abgebrochenen Alarms sind ungültig. Nach Ablauf werden die bestätigten Kontakte benachrichtigt; die Standortfreigabe für sie endet nach 120 Minuten. Je Konto ist höchstens ein Alarm gleichzeitig aktiv, ein erneutes alert liefert denselben Alarm.

8. Offline-Netz: Notrufe ohne Empfang über andere Apps weiterleiten

Ja, unterschiedliche Apps können sich gegenseitig helfen. Bluetooth LE ist nicht an eine App gebunden: Jede App, die den RideVerse-Dienst sucht, findet Notrufpakete jeder anderen App, die ihn anbietet – also auch die RideVerse-App und deine App untereinander. Hat ein Handy keinen Empfang, stellt es nach abgelaufenem Countdown ein verschlüsseltes Paket per Bluetooth bereit. Handys in der Nähe reichen es unverändert weiter, bis eines mit Empfang es an RideVerse übergibt. RideVerse prüft Signatur, Alter und Einmaligkeit und löst den Alarm des Absenders aus. Weiterleitende Apps können weder Inhalt noch Absender noch Standort lesen und erfahren nicht, ob ein Alarm angenommen wurde.

Freigabe: Die Operationen relayRegisterKey, relayUnregisterKeys und relay gibt der Inhaber je Partner-App gesondert frei (zusätzlich zur normalen Freigabe). Zeige die Weiterleitung im Testvideo. Jede Operation braucht wie alle anderen die Sitzung der betroffenen Person.

Absender: Erzeuge auf dem Gerät einen P-256-Schlüssel im sicheren Schlüsselspeicher und melde den öffentlichen Teil (65 Byte unkomprimiert, Base64) mit relayRegisterKey {publicKey} an. Die Antwort enthält keyId, serverPublicKey (Base64) und ttlSeconds (1800). Höchstens drei Schlüssel je Konto; relayUnregisterKeys löscht alle und macht alte Pakete wertlos. Ohne Netz baust du nach abgelaufenem Countdown ein 171-Byte-Paket exakt nach der Referenz unten und erneuerst es alle 20 Minuten mit frischem Standort.

Bluetooth: Verbindbar werben mit dem Dienst 7d3a0001-5c1e-4b0e-9f6a-526964657273, ohne Gerätenamen. Die lesbare Eigenschaft 7d3a0002-5c1e-4b0e-9f6a-526964657273 enthält 1 Byte Anzahl und danach bis zu 2 Pakete à 171 Byte (MTU 512 anfordern). Suche mit einem Filter auf diesen Dienst, verbinde kurz, lies die Eigenschaft und trenne wieder.

Weiterleiten: Empfangene Pakete unverändert speichern (höchstens 6, jedes nur einmal, verwerfen nach 30 Minuten), bei Netz über dein Backend mit relay {packet} (Base64) hochladen. Die Antwort ist immer {accepted: true}. Ohne eigenes Netz darfst du empfangene Pakete selbst wieder bereitstellen (Mehrsprung). Je Person sind 60 Weiterleitungen am Tag möglich.

Plattformen: Android ab 12 braucht BLUETOOTH_SCAN (neverForLocation), BLUETOOTH_CONNECT und BLUETOOTH_ADVERTISE; Werbung und Suche laufen zuverlässig in einem Vordergrunddienst mit sichtbarer Benachrichtigung. iOS braucht CoreBluetooth mit den Hintergrundmodi bluetooth-central und bluetooth-peripheral. Im Hintergrund wirbt iOS den Dienst nur eingeschränkt, Android-Geräte finden ein iPhone dann meist nicht; während der Countdown-Bildschirm offen ist, funktioniert es. Reichweite typischerweise 10 bis 50 Meter, im Freien mehr. Die Weiterleitung ist eine zusätzliche Hilfe ohne Garantie und kein Ersatz für den Notruf 112.

Referenz: rideverse-relay-reference.cjs (Paketformat, Kryptografie, Bluetooth-Wert; Node.js ohne Abhängigkeiten) und rideverse-relay-testvector.json (nur Testschlüssel). „node rideverse-relay-reference.cjs rideverse-relay-testvector.json“ muss „Testvektor OK“ ausgeben; baue deine Kotlin- oder Swift-Umsetzung so lange nach, bis sie denselben Testvektor öffnet.

rideverse-relay-reference.cjs ↓ · rideverse-relay-testvector.json ↓

9. Mit KI einbauen: Prompt zum Kopieren

Lässt du die Integration von einem KI-Assistenten schreiben? Gib ihm diesen Text zusammen mit den beiden Vorlagen und der Referenz. Prüfe das Ergebnis trotzdem selbst, besonders Countdown, Abbruch und dass kein Schlüssel in der App landet.

Du baust in meine App die RideVerse-Partner-API ein (SOS mit Countdown, Notfallkontakte) und optional die Offline-Weiterleitung per Bluetooth. Halte dich exakt an die Dokumentation https://cellystudio.de/rideverse/api/dokumentation und diese Regeln:

1. Sicherheit: Partner-ID und Server-Schlüssel liegen NUR auf meinem Backend (Umgebungsvariablen). Die App ruft mein Backend auf, mein Backend signiert jede Anfrage mit der Vorlage rideverse-partner-server.cjs (X-RV-App, X-RV-Timestamp, X-RV-Nonce, X-RV-Signature, Pfad /v1/safety) und sendet sie an POST https://cellystudio.de/api/rideverse/partner. Jede Nutzeraktion trägt zusätzlich das Firebase-ID-Token der Person als Bearer-Token.
2. Konten: registerEmail → verifyRegistration (eigene benannte Firebase-Instanz, damit meine Anmeldung erhalten bleibt). Bestehende RideVerse-Konten mit linkExisting: true.
3. SOS: alert startet den Countdown (60 s, mit automatic: true bei erkanntem Sturz 30 s). Zeige den Countdown sofort lokal mit großer Abbrechen-Schaltfläche; stop bricht ab und entwertet verspätete Antworten. Zeige „Kontakte benachrichtigt“ erst nach Bestätigung durch die API. position sendet während eines Alarms die aktuelle Position. Kein Ersatz für 112 – das muss sichtbar in der App stehen.
4. Einwilligung: Standort, Kontakte und Sturzerkennung erst nach ausdrücklicher Zustimmung; alles abschaltbar. Branding „Powered by RideVerse“ sichtbar.
5. Offline-Weiterleitung (nur wenn mein Partnerzugang dafür freigegeben ist): Gerät erzeugt einen P-256-Schlüssel im sicheren Schlüsselspeicher (Android Keystore / iOS Secure Enclave bzw. Keychain), meldet den öffentlichen Teil (65 Byte unkomprimiert, Base64) mit relayRegisterKey an und speichert keyId und serverPublicKey. Ohne Netz nach abgelaufenem Countdown ein 171-Byte-Paket exakt nach rideverse-relay-reference.cjs bauen und per Bluetooth LE bereitstellen: verbindbar werben mit Dienst 7d3a0001-5c1e-4b0e-9f6a-526964657273 ohne Gerätenamen, lesbare Eigenschaft 7d3a0002-5c1e-4b0e-9f6a-526964657273 mit 1 Byte Anzahl und bis zu 2 Paketen. Empfangene Pakete unverändert speichern (höchstens 6, höchstens 30 Minuten alt, jedes nur einmal), bei Netz über mein Backend mit relay hochladen und nie auswerten. Teste den Paketbau mit rideverse-relay-testvector.json, bis „Testvektor OK“ erscheint.
6. Plattform: Android 12+ BLUETOOTH_SCAN (neverForLocation), BLUETOOTH_CONNECT, BLUETOOTH_ADVERTISE, Werbung und Suche in einem Vordergrunddienst mit sichtbarer Benachrichtigung. iOS: CoreBluetooth mit den Hintergrundmodi bluetooth-central und bluetooth-peripheral; beachte, dass iOS im Hintergrund nur eingeschränkt wirbt.
7. Schreibe Tests für Paketbau, Countdown, Abbruch und Fehlerfälle. Erfinde keine Endpunkte oder Felder, die nicht in der Dokumentation stehen; frage nach, wenn etwas fehlt.