Zugriff auf CuraGo-Daten inkl. Caching-Protokoll für Third-Party Apps

---

1. Allgemeines

In der folgenden Kurzanleitung wird grob skizziert, wie eine Third-Party-App mit dem CuraGo-Server kommunizieren sollte.

Für detailliertere Angaben ist die OpenAPI-Dokumentation heranzuziehen:

https://docs.curasoft.dev/cura-go.de

Da sehr große Datenmengen entstehen können, wird hier explizit auf die Kommunikation mit dem Server inklusive Caching-Protokoll eingegangen.

---

2. Authentifizierung

Die Authentifizierung besteht aus zwei Informationen:

• API-Key: Erlaubt den Serverzugriff.
• ACCESS-Key: Erlaubt den Datenzugriff.

Der API-Key wird von CuraSoft zur Verfügung gestellt.
Der ACCESS-Key wird vom Kunden / Pflegedienst / Leistungserbringer zur Verfügung gestellt.

Diese beiden Keys werden beim Authentifizieren im Header mitgeschickt.

Nachdem man sich erfolgreich authentifiziert hat, erhält man ein Bearer-Token, welches bei allen weiteren Requests im Auth-Header mitgeschickt werden muss.
Das Bearer-Token ist ein JWT (JSON Web Token).

Wichtig in diesem JWT ist der Claim adk (AppDataKey).
Das ist der Datenschlüssel zum Entschlüsseln sensibler Daten. Dieser AppDataKey ist zusätzlich mit dem ACCESS-Key verschlüsselt.

Request

Route

GET /auth/v3/app

Header

X-API-KEY: <api_key>
X-ACCESS-KEY: <access_key>

Response

<bearer>

---

3. Device registrieren

Damit der Server ein effizientes Daten-Caching betreiben kann, gibt es das sogenannte Device-Token.

Mit diesem Device-Token kann der Server eindeutig erkennen, welche Datensätze beim Client gelöscht, geändert oder neu angelegt werden müssen.

Das Device muss nur einmalig registriert werden.

Im Body wird ein JSON-Objekt mit Informationen über die Client-Anwendung mitgeschickt.

Request

Route

POST /api/v3/device/create

Header

Authorization: Bearer <bearer>

Body

{
  "caption": "Fancy 3rd Party App",
  "version": "1.0.0"
}

Response

<device_token>

---

4. Abfragen von Daten

Das Abfragen von Daten erfolgt immer in drei Schritten:

1. Den Server nach Neuerungen fragen
   /api/v3/data/status
2. Daten herunterladen
   /api/v3/rest/{model}
3. Daten bestätigen
   /api/v3/rest/{model}/ack
/api/v3/rest/{model}/cleanup

---

4.1 Den Server nach Neuerungen fragen

Das Device-Token vom Client und die jeweiligen Ressourcen, die abgefragt werden sollen, werden hier im JSON-Objekt mit übergeben.

Request

Route

POST /api/v3/data/status

Header

Authorization: Bearer <bearer>

Body

{
  "jobs": [
    {
      "token": "<device_token>",
      "models": [
        "Patient",
        "Mitarbeiter"
      ]
    }
  ]
}

Response

Body

[
  {
    "model": "Patient",
    "cleanup_ids": "1,4..10,12",
    "count_download": 4
  },
  {
    "model": "Mitarbeiter",
    "cleanup_ids": "",
    "count_download": 100
  }
]

Bedeutung der Response-Felder

Feld	Beschreibung
cleanup_ids	Alle IDs, die veraltet sind und beim Client gelöscht werden können. Aufeinanderfolgende IDs werden mit .. abgekürzt.
count_download	Anzahl der Datensätze, die neu sind oder sich geändert haben.

---

4.2 Daten herunterladen

Beim Herunterladen der eigentlichen Daten ist es zwingend notwendig, dass alle IDs aus den Datensätzen, die vom Server ausgeliefert werden, lokal beim Client gespeichert werden.

Nur so kann eine fehlerfreie Kommunikation mit dem Server erreicht werden.

Request

Route

GET /api/v3/rest/{model}

Header

Authorization: Bearer <bearer>

Pfad-Parameter

{model}: z. B. Patient oder Mitarbeiter

Query-Parameter

token: <device_token>

Response

Body

[
  { "..": ".." },
  { "..": ".." }
]

Der Server liefert maximal 2000 Datensätze auf einmal aus.

Nachdem diese Datensätze bestätigt wurden, kann die nächste Abfrage erfolgen.
Das passiert so oft, bis der Server keine Datensätze mehr ausliefert.

---

4.3 Daten bestätigen

Nachdem Datensätze heruntergeladen und gespeichert wurden, muss dies beim Server bestätigt werden.
Dadurch wird der Datensatz bis zur nächsten Änderung nicht erneut ausgeliefert.

Hier gibt es zwei Requests:

• Bestätigen neuer bzw. geänderter Daten
• Bestätigen von Daten, die lokal gelöscht wurden

Request: Neuerungen und Änderungen bestätigen

Route

POST /api/v3/rest/{model}/ack

Header

Authorization: Bearer <bearer>

Pfad-Parameter

{model}: z. B. Patient oder Mitarbeiter

Body

{
  "token": "<device_token>",
  "ids": "1,4..10,12"
}

Request: Löschen bestätigen

Route

POST /api/v3/rest/{model}/cleanup

Header

Authorization: Bearer <bearer>

Pfad-Parameter

{model}: z. B. Patient oder Mitarbeiter

Body

{
  "token": "<device_token>",
  "ids": "1,4..10,12"
}

---

5. Entschlüsseln von Daten

Sensible Daten liegen nur im verschlüsselten Format vor.

Dazu gehören zum Beispiel:

• Patienten- und Mitarbeiternamen
• Texte, Bilder und Sprachnachrichten der Übergabebucheinträge

Diese Daten sind mit dem sogenannten DataKey verschlüsselt.

Den DataKey kann man aus dem adk-Claim im JWT extrahieren.
Dieser ist allerdings zusätzlich mit dem ACCESS-Key verschlüsselt.

Alle Daten sind mit dem Verschlüsselungsverfahren AES-256 verschlüsselt.

CuraSoft stellt Codebeispiele zum Entschlüsseln der Daten zur Verfügung.