This API defines an interface between a client (i.e. application which has access to a smartcard of type eHC (electronic Health Card = eGK = elektronische Gesundheitskarte) on one side and a server (i.e. application of type eHealth-CardLink) on the other side.
Websocket Server
Send Session Information for the opened connection to the client (app)
Available only on servers:
Accepts the following message:
sessionStatus message
{
"messageId": "44a4e8f5-6aeb-4380-9a8d-b355b7f62b52",
"type": "sessionStatus",
"webSocketId": "dac7e9b3-2446-4b3c-9b67-dd8cfabffb4d",
"phoneRegistered": false
}
Receive request SMS Code for the opened connection from the client (app)
Available only on servers:
Accepts the following message:
Request SMS code validation for a given phone number
requestSMSCode message
{
"messageId": "e9a148b9-e70a-498e-af0e-358c8226cae8",
"type": "requestSMSCode",
"phoneNumber": "+49 (175) 142 126 92"
}
Send request SMS Code Response for the opened connection to the client (app)
Available only on servers:
Accepts the following message:
Response for requesting an SMS code validation for a given phone number
requestSMSCodeResponse message
{
"messageId": "3257f31c-89c7-4d96-9e0f-11c7d79e0b6e",
"correlationId": "e9a148b9-e70a-498e-af0e-358c8226cae8",
"type": "requestSMSCodeResponse",
"resultCode": "SUCCESS"
}
requestSMSCodeResponse message
{
"messageId": "3257f31c-89c7-4d96-9e0f-11c7d79e0b6e",
"correlationId": "e9a148b9-e70a-498e-af0e-358c8226cae8",
"type": "requestSMSCodeResponse",
"resultCode": "NUMBER_FROM_WRONG_COUNTRY",
"errorMessage": "The provided number is not from Germany"
}
Receive confirm SMS Code for the opened connection from the client (app)
Available only on servers:
Accepts the following message:
Confirm SMS code validation for a given phone number
confirmSMSCode message
{
"messageId": "b82c6017-430c-48e0-a002-a92fb0e18b14",
"type": "confirmSMSCode",
"smsCode": 123456
}
Send confirm SMS Code Response for the opened connection to the client (app)
Available only on servers:
Accepts the following message:
Response for confirming an SMS code for a given phone number
confirmSMSCodeResponse message
{
"messageId": "c8163bf7-9f67-4b62-97e5-83129bda4422",
"correlationId": "b82c6017-430c-48e0-a002-a92fb0e18b14",
"type": "confirmSMSCodeResponse",
"resultCode": "SUCCESS"
}
confirmSMSCodeResponse message
{
"messageId": "c8163bf7-9f67-4b62-97e5-83129bda4422",
"correlationId": "b82c6017-430c-48e0-a002-a92fb0e18b14",
"type": "confirmSMSCodeResponse",
"resultCode": "TAN_RETRY_LIMIT_EXCEEDED",
"errorMessage": "The SMS code has been entered wrong too many times"
}
Send ICCSN Reassignment for the opened connection to the client (app)
Available only on servers:
Accepts the following message:
Notification for the user that the previously paired Phone Number is used with a new eGK. This message is correlated to the registerEGK message.
ICCSNReassignment message
{
"messageId": "559ebb3e-f215-4836-8a65-6f83e531d568",
"correlationId": "f1f7bdb6-7562-4152-b636-9f75ca5fb7b1",
"type": "ICCSNReassignment"
}
Receive eGK message from client (app)
Available only on servers:
Accepts the following message:
registerEGK message
{
"messageId": "f1f7bdb6-7562-4152-b636-9f75ca5fb7b1",
"cardSessionId": "3509584a-04e7-4756-bab0-0da4a84d0c12",
"type": "registerEGK",
"gdo": "WgqAJ2iBGZmZloNp",
"atr": "4BECAggJAgMAgAICAggJAgIICV9SDIBmBURFRytEc5Yh4NADBAQB0hBERUlGWDUyRjRHREpNAQAA0xBERUcrRFMzN09TR0syAQAA1BBERUcrRFMzN0dLVjAzAQAA1QMEBAHWEERFRytEQ0IyQ1RHMDEBAADXEERFRytEUERQU19fX18BBgA=",
"cardVersion": "7yvAAwIAAMEDBAUBwhBERUcrRFMzN0dLVjAzAQAAxAMBAADFAwIAAMcDAQAA",
"x509AuthRSA": "MIIE8zCCA9ugAwIBAgIDLJx\\/MA0GCSqGSIb3DQEBCwUAMIGsMQswCQYDVQQGEwJERTEzMDEGA1UECgwqQXRvcyBJbmZvcm1hdGlvbiBUZWNobm9sb2d5IEdtYkggTk9ULVZBTElEMUUwQwYDVQQLDDxFbGVrdHJvbmlzY2hlIEdlc3VuZGhlaXRza2FydGUtQ0EgZGVyIFRlbGVtYXRpa2luZnJhc3RydWt0dXIxITAfBgNVBAMMGEFUT1MuRUdLLUNBMjA2IFRFU1QtT05MWTAeFw0yMzA0MjAxMTM3NDBaFw0yODA0MjAxMTM3NDBaMIGRMQswCQYDVQQGEwJERTEfMB0GA1UECgwWQU9LIEJhZGVuLVfDvHJ0dGVtYmVyZzESMBAGA1UECwwJMTA4MDE4MDA3MRMwEQYDVQQLDApUMDQ5OTA0NzI3MQ8wDQYDVQQEDAZEZXBqcGkxDzANBgNVBCoMBkthZ3V4aTEWMBQGA1UEAwwNRGVwanBpIEthZ3V4aTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJW2sUoHHvBAwkInDOuVTVyd8LDCGANsODfgW+k9ZognXZbzzYlYOxBp2\\/MAwCFvL084J2ISdRo3aADMssKe\\/nhGj16e+86PNNNIHgyD+7MC13BSCc9Bavce6RNy3pTwtkz9MMv01M65gshHww7P5bfrHgA75B4mQQ9ajXUAlBoMBju6aNAeRcfrriXJMxZVbuLaAayVYXIugRcP3E5iIPXNFh573LeYFfB1ZENkT\\/hPHt+16hGrQyu3zC8Kd7jEbiJP\\/xO2rUWmt77uGMMs2rbFfhAHmV\\/hDOM4gCBPX9AAPNmIA2TDM2JW4WUNdA+xFYlrmYlE4ak0XT2sX9YDYBsCAwEAAaOCATUwggExMB0GA1UdDgQWBBSdKMTFoCOE\\/Rl6KuDss6TatyM4wDAOBgNVHQ8BAf8EBAMCB4AwDAYDVR0TAQH\\/BAIwADBRBgNVHSAESjBIMAkGByqCFABMBEYwOwYIKoIUAEwEgSMwLzAtBggrBgEFBQcCARYhaHR0cDovL3d3dy5nZW1hdGlrLmRlL2dvL3BvbGljaWVzMDcGCCsGAQUFBwEBBCswKTAnBggrBgEFBQcwAYYbaHR0cDovL29jc3AuZWdrLXRlc3QtdHNwLmRlMB8GA1UdIwQYMBaAFLAkydaZxJA2LjQV1dzKPM7xauP\\/MBMGA1UdJQQMMAoGCCsGAQUFBwMCMDAGBSskCAMDBCcwJTAjMCEwHzAdMBAMDlZlcnNpY2hlcnRlLy1yMAkGByqCFABMBDEwDQYJKoZIhvcNAQELBQADggEBAC5lsm+8lGg8l7ff0pHNmFiUjioipYHqL1XIxric8YYJV9AOIjLo+QSsGBKnoXM1OCQBZ2SsZDHq10w3djTvoC+HGybqGEuVpImeQEfpG2ZNfLeHgipxc67f1zr1D4gshcJEmb3HbL+a3IQWYW5cTuvllc1COS9\\/DgxGqr8xtKI6+Za1k9fvKnSJeQqx0MvvPn+f4peyezWgBaYpakwsihf8qdcQtBdv\\/I3cJcYzAwi3A4NxmZmNKe2iNVAwJhxf4MARsAYUgs4bt4W3GhXGyvpuEQoKIJos+6ldKUofuqpcD\\/94lVTDH+3fyyk1gSvvxwWal2XFWaTbIy0NrB7NcK0=",
"x509AuthECC": "MIIDaDCCAw6gAwIBAgIDL9AHMAoGCCqGSM49BAMCMIGsMQswCQYDVQQGEwJERTEzMDEGA1UECgwqQXRvcyBJbmZvcm1hdGlvbiBUZWNobm9sb2d5IEdtYkggTk9ULVZBTElEMUUwQwYDVQQLDDxFbGVrdHJvbmlzY2hlIEdlc3VuZGhlaXRza2FydGUtQ0EgZGVyIFRlbGVtYXRpa2luZnJhc3RydWt0dXIxITAfBgNVBAMMGEFUT1MuRUdLLUNBMjA1IFRFU1QtT05MWTAeFw0yMzA0MjAxMTM4MDNaFw0yODA0MjAxMTM4MDNaMIGRMQswCQYDVQQGEwJERTEfMB0GA1UECgwWQU9LIEJhZGVuLVfDvHJ0dGVtYmVyZzESMBAGA1UECwwJMTA4MDE4MDA3MRMwEQYDVQQLDApUMDQ5OTA0NzI3MQ8wDQYDVQQEDAZEZXBqcGkxDzANBgNVBCoMBkthZ3V4aTEWMBQGA1UEAwwNRGVwanBpIEthZ3V4aTBaMBQGByqGSM49AgEGCSskAwMCCAEBBwNCAARG\\/zHjer2JVpNi8fGLw1TY8UV0jC5OIy3EbPSKYzEY4wj1wu1Uxmz0qhAvuCTTm9dHOakL52PtwiV4\\/FB0\\/TuOo4IBNTCCATEwHQYDVR0OBBYEFJSkc+7NAvhG3r3+nyGfd7G4MfDeMA4GA1UdDwEB\\/wQEAwIHgDAMBgNVHRMBAf8EAjAAMFEGA1UdIARKMEgwCQYHKoIUAEwERjA7BggqghQATASBIzAvMC0GCCsGAQUFBwIBFiFodHRwOi8vd3d3LmdlbWF0aWsuZGUvZ28vcG9saWNpZXMwNwYIKwYBBQUHAQEEKzApMCcGCCsGAQUFBzABhhtodHRwOi8vb2NzcC5lZ2stdGVzdC10c3AuZGUwHwYDVR0jBBgwFoAURqP5XidowY\\/nZ0xQaiQfG21t9lwwEwYDVR0lBAwwCgYIKwYBBQUHAwIwMAYFKyQIAwMEJzAlMCMwITAfMB0wEAwOVmVyc2ljaGVydGUvLXIwCQYHKoIUAEwEMTAKBggqhkjOPQQDAgNIADBFAiEAhYTKDwLokoIlbKQy9thUIDv\\/CrY5iDHISeTy8sA5FYwCIDxpbggG3wO7wY\\/E2\\/ZP9af3jP2YroCBqQUATqsnaFef",
"cvcAuth": "fyGB2n9OgZNfKQFwQghERUFUWBYCIX9JSwYGKyQDBQMBhkEEIX4kJxFM3ncGzbBV+TZfdzUHlS\\/\\/OAYnrLLNtHgGKo4SbohQIub0eJ6484BhkT0akp68+388VX97n01Gqu+7Sl8gDAAJgCdogRmZmZaDaX9MEwYIKoIUAEwEgRhTBwAAAAAAAABfJQYCAwAEAgBfJAYCCAAEAgBfN0CK7Ifm998wVduqvBm03qgkdorMRtkxS\\/E91Qg5a6Xy\\/IccOE5Er12C4FLS8BF+7cpj2aV5PzJm1B0uW7XRK\\/Xj",
"cvcCA": "fyGB2H9OgZFfKQFwQghERUdYWIYCIH9JTQYIKoZIzj0EAwKGQQRj3tNdi\\/J0Zsxh+SkGS5Duab\\/mFnzcJuXWoCV7bXO8N6kx5iq1XxHnvSp7hIzi0Eo97jpFpBkl8dVnURuAfEK3XyAIREVBVFgWAiF\\/TBMGCCqCFABMBIEYUweAAAAAAAAAXyUGAgEAAgEHXyQGAgkAAgEGXzdAe4\\/gFwTxqg8I9W4qgjVp\\/98bF2Djo4Z\\/\\/wdaRx14lYhu2YFdlH+pZpbrphKeRELUBfjtIdE53Z2w1dIP2G6KUw=="
}
Send eGK finished message to client (app)
Available only on servers:
Accepts the following message:
registerEGKFinish message
{
"messageId": "47f9fd9e-a893-4245-a15b-54fcaf08b157",
"correlationId": "f1f7bdb6-7562-4152-b636-9f75ca5fb7b1",
"cardSessionId": "3509584a-04e7-4756-bab0-0da4a84d0c12",
"type": "registerEGKFinish",
"removeCard": true
}
Send APDU to app (INTERNAL AUTHENTICATE)
Available only on servers:
Accepts the following message:
sendAPDU message
{
"messageId": "ecc801d7-63d4-4f35-8ece-7b0f6309d2f0",
"cardSessionId": "3509584a-04e7-4756-bab0-0da4a84d0c12",
"type": "sendAPDU",
"apdu": "AIgAABiAJ2iBGZmZloNpD7bD27Eh0y1kmUtD3tkA"
}
INTERNAL AUTHENTICATE response
Available only on servers:
Accepts the following message:
sendAPDUResponse message
{
"messageId": "02774740-35dc-460a-b7dc-b5d076b382c3",
"correlationId": "ecc801d7-63d4-4f35-8ece-7b0f6309d2f0",
"cardSessionId": "3509584a-04e7-4756-bab0-0da4a84d0c12",
"type": "sendAPDUResponse",
"responseApdu": "kbNAK4xv4nyvwEO4fwgmZmnFnwGSb2+WDftJq2Sus0lwx5rQUQ9tq0Q1qKwlyjxpaAL0CSJ1gWRVQkfVzoYxxZAA"
}
Error in the course of card plugging or ReadVSD
Available only on servers:
Accepts the following message:
tasklist Error message example
{
"messageId": "54200292-c442-4b1a-a1c1-83cfb596b72c",
"correlationId": "f1f7bdb6-7562-4152-b636-9f75ca5fb7b1",
"cardSessionId": "3509584a-04e7-4756-bab0-0da4a84d0c12",
"type": "tasklistError",
"status": 500,
"tiStatus": 500,
"errorMessage": "ReadVSD Error"
}
eH-CL encountered an error
Available only on servers:
Accepts the following message:
generic Error message example
{
"messageId": "54200292-c442-4b1a-a1c1-83cfb596b72c",
"correlationId": "f1f7bdb6-7562-4152-b636-9f75ca5fb7b1",
"type": "genericError",
"errorCode": "INVALID_MESSAGE_DATA",
"errorMessage": "Received payload is missing field XYZ."
}
Status about the (re-)established session
Request SMS code validation for a given phone number
Response for requesting an SMS code validation for a given phone number
Confirm SMS code validation for a given phone number
Response for confirming an SMS code for a given phone number
Notification for the user that the previously paired Phone Number is used with a new eGK. This message is correlated to the registerEGK message.
Finish message for eGK registration
APDU from card to processing component
Error retrieving PN
Identifier for the established web socket connection
Card session identifier
Message identifier
Message identifier
Base type for error messages
Base type for error messages
Session Information object
Request SMS Code Payload object
Request SMS Code Payload Response object
Confirm SMS Code Payload object
Confirm SMS Code Payload Response object
ICCSN Reassignment object, indicating to the user, that the ICCSN-Phone association has changed.
Registration message type containing eGK data.
Conclusion message type of the eGK registration.
Type for sending an APDU to the card
Type for receiving a Response APDU from the card