Anbindung der Partnersysteme ohne DCC
Bitte registrieren Sie sich unter nachfolgender E-Mail-Adresse: cwa-onboarding-schnittstelle@t-systems.com
- Vorbereitung
- Onboarding-Prozess
- Entwicklung QR-Code & Backend-Integration
- Datenschutzhinweise
- Ende zu Ende Test mit App
- Abnahmetest und Freischaltung
Voraussetzung für die Integration der Corona-Warn-App sind
- Implementierung eines Corona-Warn-App QR-Codes (3 Varianten möglich) im Testprozess
- Implementierung einer Backend-Schnittstelle
- Bitte, beachten Sie unsere Datenschutzhinweise
Weiterführende Informationen dazu entnehmen Sie bitte der Präsentation.
Sie finden eine passende Vertragsvorlage auf der Seite Vertragsabschluss. Dieser muss unterschrieben vorliegen, damit der Onboarding-Prozess fortgesetzt werden kann.
Nach dem Eingang des unterschiebenen Vertrags erhalten Sie zusätzlich ein Formular mit unseren Nutzungsbedingungen für die API (Test-Result-Server). Der Test-Result-Server nutzt eine zertifikat-basierte Authentifizierung. Senden Sie uns das unterschriebene Formular zurück; danach wird Ihnen ein Zugangszertifikat für unsere Testumgebung (WRU) zugeschickt. Der Zugang zur Produktivumgebung wird nach einem erfolgreichen Abnahmetest freigeschaltet.
Diese Beschreibung gilt für den Fall, dass die zu testende Person eine Einwilligung zur Weitergabe der persönlichen Daten an die Corona-Warn-App gegeben hat. Die Variante ohne Einwilligung wird unten beschrieben. Beachten Sie, dass die Einwilligungen des zu Testenden zur Nutzung der Corona-Warn-App sowie zur Weitergabe der persönlichen Daten an die Corona-Warn-App in Ihrer Software gespeichert werden müssen.
Für die Weitergabe der Daten zu einem Schnelltest an die Corona-Warn-App müssen Sie zuerst ein JSON-Objekt erstellen. Die Struktur des JSON-Objekts setzt sich aus den folgenden Attributen zusammen:
| Name | Wert |
|---|---|
| fn | Vorname, UTF-8, maximale Länge 80 Zeichen |
| ln | Nachname, UTF-8, maximale Länge 80 Zeichen |
| dob | Geburtsdatum im Format YYYY-MM-DD mit fester Länge von 10 Zeichen (Beispiel: 2000-01-01) |
| testid | generierte UUID Typ 4 oder eine eigene ID* |
| timestamp | Test-Datum/Uhrzeit im Unix Epoch Timestamp Format (Sekunden) |
| salt | Generierte 128-Bit Zufallszahl in Hexadezimal-Darstellung, nur mit Großbuchstaben und fester Breite von 32 Stellen** |
| hash | SHA256-Hashwert für alle anderen Attribute des Objekts*** |
* Für das Attribut testid empfehlen wir eine UUID Typ 4 generierte Zeichenkette. Sie können stattdessen Ihre eigene Bezeichnung verwenden, die Sie als Zeichenkette in JSON behandeln. Diese ID dient der Identifikation eines Testvorgangs und nicht des Antigen-Test-Herstellers. Die maximale Länge des Attributs beträgt 36 Zeichen.
** Das Attribut salt muss durch einen kryptografisch sicheren Zufallsgenerator erzeugt werden (dafür gibt es in jeder Programmiersprache Bibliotheken). Dieser Wert muss bei jedem Testvorgang neu generiert werden.
*** In den Präsentationen als CWA Test ID bezeichnet. Nutzen Sie bitte für den Hash-Wert nur den Lower-Case.
Beispiel:
{
"fn": "Erika",
"ln": "Mustermann",
"dob": "1990-12-23",
"timestamp": 1618386548,
"testid": "52cddd8e-ff32-4478-af64-cb867cea1db5",
"salt": "759F8FF3554F0E1BBF6EFF8DE298D9E9",
"hash": "67a50cba5952bf4f6c7eca896c0030516ab2f228f157237712e52d66489d9960"
}
Für die Erzeugung des SHA256-Hashwerts nutzen Sie eine Zeichenkette, die nach dem folgenden Muster aufgebaut ist:
[dob]#[fn]#[ln]#[timestamp]#[testid]#[salt]
Oder für das obige JSON-Objekt:
1990-12-23#Erika#Mustermann#1618386548#52cddd8e-ff32-4478-af64-cb867cea1db5#759F8FF3554F0E1BBF6EFF8DE298D9E9
Daraus resultiert sich ein SHA256-Hashwert:
67a50cba5952bf4f6c7eca896c0030516ab2f228f157237712e52d66489d9960
Dieser Hashwert soll Ihre Software zusammen mit den persönlichen Daten so lange speichern, bis das Testergebnis bekannt ist und an den Test-Result-Server übermittelt ist. Der Test-Result-Server identifiziert ein Testergebnis über diesen Hashwert, speichert jedoch keine persönlichen Daten. Zunächst erstellen Sie einen Link für die Übergabe des JSON-Objekts an die Corona-Warn-App. Nutzer, die die Corona-Warn-App nicht auf Ihrem Mobilgerät installiert haben, werden durch diesen Link auf Google Play / App Store weitergeleitet. Nutzer, die die App bereits haben, bekommen die Daten zum Schnelltest direkt in die Corona-Warn-App übergeben.
Zuerst muss das JSON-Objekt in base64url-Form umgewandelt und nach dem Hashtag-Zeichen platziert werden.
Input für das Base64 Encoding:
{ "fn": "Erika", "ln": "Mustermann", "dob": "1990-12-23", "timestamp": 1618386548, "testid": "52cddd8e-ff32-4478-af64-cb867cea1db5", "salt": "759F8FF3554F0E1BBF6EFF8DE298D9E9", "hash": "67a50cba5952bf4f6c7eca896c0030516ab2f228f157237712e52d66489d9960" }
Aufbau des Links:
https://s.coronawarn.app?v=1#[base64url-coded JSON-Object]
Oder für das Beispiel:
https://s.coronawarn.app?v=1#eyAiZm4iOiAiRXJpa2EiLCAibG4iOiAiTXVzdGVybWFubiIsICJkb2IiOiAiMTk5MC0xMi0yMyIsICJ0aW1lc3RhbXAiOiAxNjE4Mzg2NTQ4LCAidGVzdGlkIjogIjUyY2RkZDhlLWZmMzItNDQ3OC1hZjY0LWNiODY3Y2VhMWRiNSIsICJzYWx0IjogIjc1OUY4RkYzNTU0RjBFMUJCRjZFRkY4REUyOThEOUU5IiwgImhhc2giOiAiNjdhNTBjYmE1OTUyYmY0ZjZjN2VjYTg5NmMwMDMwNTE2YWIyZjIyOGYxNTcyMzc3MTJlNTJkNjY0ODlkOTk2MCIgfQ
Anschließend erstellen Sie einen QR-Code aus dieser URL. Die base64url-kodierte Daten kommen nach dem Hashtag und gelangen dadurch nicht ins Netzwerk.
Für die Erzeugung des SHA256-Hashwerts nutzen Sie folgende Zeichenkette:
[timestamp]#[salt]
Oder für das obige JSON-Objekt:
1618386548#759F8FF3554F0E1BBF6EFF8DE298D9E9
Daraus resultiert sich ein SHA256-Hashwert:
80232838046d2a65ab1b7a1be3dd1250ba9c91c969476c093bc34001ef460af8
Im zu übermittelnden JSON-Objekt sind nicht alle Daten präsent: persönliche Daten (Vorname, Nachname, Geburtsdatum, Test-ID) werden nicht inkludiert:
{
"timestamp": 1618386548,
"salt": "759F8FF3554F0E1BBF6EFF8DE298D9E9",
"hash": "80232838046d2a65ab1b7a1be3dd1250ba9c91c969476c093bc34001ef460af8"
}
Mit diesem Objekt erstellen Sie eine base64url-kodierte Zeichenkette für die URL sowie den QR-Code.
Link für Corona-Warn-App:
https://s.coronawarn.app?v=1#eyAidGltZXN0YW1wIjogMTYxODM4NjU0OCwgInNhbHQiOiAiNzU5RjhGRjM1NTRGMEUxQkJGNkVGRjhERTI5OEQ5RTkiLCAiaGFzaCI6ICI4MDIzMjgzODA0NmQyYTY1YWIxYjdhMWJlM2RkMTI1MGJhOWM5MWM5Njk0NzZjMDkzYmMzNDAwMWVmNDYwYWY4IiB9
Erstellen sie aus dieser URL einen QR-Code für die Corona-Warn-App:
Eine Beispielimplementierung in php ist hier zu finden: quicktest_upload.php
Nachdem ein Schnelltest erstellt wurde, können Sie das Testergebnis für den Test an den Test-Result-Server per POST-Aufruf übermitteln. Ein solches Ergebnis setzt sich aus folgenden Attributen zusammen:
| Name | Wert |
|---|---|
| id | SHA256-Hashwert aus dem JSON-Objekt des QR-Codes |
| result | Testergebnis: Wertebereich 6 bis 8 |
| sc | Zeitpunkt der Probenentnahme in unix epoch format UTC (Sekunden) |
Wertetabelle für Testergebnisse:
| Name | Wert |
|---|---|
| 6 | negativ |
| 7 | positiv |
| 8 | ungültig |
Der Status ungültig kann auf positiv / negativ geändert werden, falls der Schnelltest nach einer unklaren Statusanzeige einen eindeutigen Wert geliefert hat. Die quicktest-openapi.json erlaubt den Wert 5 für den Status pending. Dieser Wert soll aktuell nicht genutzt werden.
Der Server nimmt Testergebnisse als JSON-Array entgegen. Damit können Sie mehrere vorliegende Testergebnisse in einem REST-Aufruf setzen. Oder als JSON-Objekt:
{
"testResults":
[
{
"id": "67a50cba5952bf4f6c7eca896c0030516ab2f228f157237712e52d66489d9960",
"result": 6,
"sc": 1625125748
}
]
}
Die aktuelle Open-API-Beschreibung des Test-Result-Servers finden Sie separat in der Datei quicktest-openapi.json.
Damit die Testergebnisse Ihrer Probanden an die Corona-Warn-App übertragen werden dürfen, sind vom Partner Datenschutzhinweise und entsprechende Einwilligungen des Probanden im Prozess zu integrieren. Entsprechende Texte erhalten Sie mit der Anlage 3 (Anlage 3 herunterladen) zum Vertrag.
Dabei sind sowohl für die pseudonymisierten als auch die personalisierte Übermittlung eine Einwilligung zu integrieren. Bitte beachten Sie dabei, dass die Einwilligungstexte 1:1 so übernommen werden müssen wie der Anlage 3 (Anlage 3 herunterladen) beschrieben.
Der Datenschutzhinweis des RKIs muss jedem Probanden zur Verfügung gestellt werden. Wie das im Einzelnen geschieht, obliegt Ihrer Verantwortung. Bitte beachten Sie auch, dass Sie für die rechtlich korrekte Bereitstellung der Einwilligungserklärung und Datenschutzerklärung, insbesondere in Testzentren vor Ort, verantwortlich sind.
Es ist wichtig jedem Probanden klar verständlich zu machen, dass er personifizierte, anonymisierte oder keine Daten an seine Corona-Warn-App übertragen kann, d.h. dass der Proband die freie Auswahl in seiner Entscheidung haben muss. Um mit der freien Wahl entscheiden zu können, muss der Benutzer alle drei Optionen und alle Einwilligungstexten gleichzeitig sehen, keiner der Optionen darf vorausgewählt werden. Hier muss der Text des RKI im Wortlaut übernommen werden. Dieser befindet sich auf Seite 2 der Anlage 3 (Anlage 3 herunterladen).
Bei der Anmeldung vor Ort sollen die Anforderungen in Papierform umgesetzt werden, die Einwilligungserklärung soll vom Probanden untergeschrieben und im Testzentrum archiviert werden. Auch hier gilt wieder, das die Auskunftspflicht beim Betreiber liegt.
Für den Fall einer Terminbuchung über ein Online-Buchungsportal, müssen die oben beschriebenen Inhalte in den Formularen dargestellt werden. In diesem Fall kann man den letzten Satz in beiden Einwilligungstexten anpassen. Ein Beispiel dazu:
Wichtiger Hinweis: Nutzen Sie keine realen personenbezogenen Daten und Gesundheitsdaten, sondern fiktive Daten. Momentan sind Tests mit einer Beta-Version der Corona-Warn-App nur in iOS möglich.
Sie erhalten den Zugang zu einer Testversion der Corona-Warn-App über iOS-App Testflight. Hierzu benötigen wir die Apple-IDs der Tester. Bitte senden Sie die Apple-IDs an das Postfach cwa-onboarding-schnittstelle@t-systems.com. Sobald Sie eingerichtet sind, erhalten Sie eine Einladung über Testflight. Bitte beachten Sie, dass die über die Testumgebung hinterlegten Testergebnisse ausschließlich über diese Testversion der App abgerufen werden können.
Sobald Ihre eigenen Ende-zu-Ende-Tests erfolgreich durchgeführt wurden, kontaktieren Sie den Ansprechpartner, der sie schon jetzt betreut. Sollten Sie noch keinen direkten Ansprechpartner kennen, dann informieren Sie uns über ihren gewünschten Abnahmetest über das Postfach cwa-onboarding-schnittstelle@t-systems.com. Nach einem erfolgreichen Abnahmetest erhalten Sie den Zugang zum Produktivsystem. Eine Checkliste zum Abnahmetest finden sie auf dieser Seite.