The TI smartcards contain user certificates and secrets for authorization and electronic signature operations. To provide a two-factor-authorization smartcards also require their user to enter personal PIN codes for certain operations. All card operations can be executed via the telematik API.
All card operations can be executed via the telematik API.
GetCards is a GET request returning all cards currently available in the connected card readers.
Example: request for all cards in all connected card readers
In order to return cards from a specific card terminal only the request can be extended by the IP address of the card terminal. The card terminal IP address can be set in the card terminal settings by the system administrator.
Example: request for all cards in all connected card reader with IP address 172.20.129.41
GetCards returns an XML data set with all cards found in all card readers connected. For each card the card handle is returned which is to be used for identifying the card in further requests.
GetPINStatus is a GET request returning the current status of all pins of all cards in all card terminals. This requests fetches all cards and then requires each card to return its PIN status. Processing time of this request depends on the number of terminals connected.
Example: GetPINStatus request
In order to get the PIN status of all cards from a specific card terminal only the request can be extended by the IP address of the card terminal.
Example of a GetPINStatus by IP request for card terminal with IP address 172.20.129.41
GetPINStatus returns a XML data set including the PIN status for each card (PIN.SMC or PIN.HBA).
- VERIFIED - this card has been confirmed by a user PIN entry and may be used for operations
- VERIFIABLE, NOT VERIFIED - confirmation is pending, user must enter the PIN in order to use the card for operations
- TRANSPORT_PIN, EMPTY_PIN - card has not been initialized yet, a new PIN must be set by user
- REJECTED - a wrong PIN was entered
- BLOCKED, NOWBLOCKED, WASBLOCKED - wrong PIN has been entered too many times, card has been blocked and must be verified using the PUK
For further information see gematik Implementierungsleitfaden für Primärsysteme
In order to activate a card the user must enter the card PIN at the card terminal keyboard. This must be triggered by a verifyPIN request sent to the card terminal which then will prompt the user for PIN entry. The request may be sent without the card terminal IP address given which would prompt all connected card terminals for PIN entry, but it is recommended to include the IP address of the card terminal in order to minimize the user effort.
After successful execution the request returns the XML data object with all cards and their PIN status as described in GetPINStatus.