HIS incoming request handling
- Pedro Jose Sanchez Luling
The Linkcare platform supports not only initiating calls to an external HIS, but also handling incoming requests from it.
There is no predefined set of functions available for external HIS invocation; instead, the exposed functionality must be mutually agreed upon by Linkcare and the external HIS and implemented specifically for that integration.
The key elements when receiving an incoming requests from an external applications are:
Interoperability Private Key: This is a key generated by Linkcare for a specific HIS provider. This key should be stored in a secure place and should only be known by Linkcare and the HIS provider
Interoperability Application ID (APPID): Is a key that will be included in all requests along with other information to guarantee the authenticity and security of the communications.
REST Entrypoint
Currently only a REST entrypoint is available in Linkcare platform.
Entrypoint URL | /his_entrypoint/function_name Example: https://dev-api.linkcareapp.com/his_entrypoint/case_search function_name is the name of the function invoked by the external HIS |
|---|---|
Source code file | HISEntrypoint.php |
Authentication mechanism
The incoming REST request must include the 3 following custom headers:
HTTP Header | Comments |
|---|---|
| A key provided by Linkcare to each HIS provider |
| A Unix timestamp (number of seconds elapsed since 1970-01-01 UTC) |
| A hash generated from the APPID, timestamp and API Key |
The authenticity of the request is verified checking the digest provided in the HTTP Header. Since it is necessary the API Key (which is not included in the communication) to generate the digest, only a certified API provider will be able to invoke the Linkcare platform successfully.
The digest is generated using a SHA-256 algorithm on the concatenation of the API Key, APPID and timestamp.
The timestamp is used to allow communications generated only in a limited period of time. This ensures that even in the case that the communication is intercepted and a group of valid APPID, timestamp and digest are collected, they won’t be usable after the permitted window of time has passed.
Example:
API Key = KLSAD8AHJA7Y7AASD
APPID = 324KKJ2342
timestamp = 1652185806
digest = sha256(“KLSAD8AHJA7Y7AASD324KKJ23421652185806”) = fa3786cc7ee522f8cb724cc898b611f78657ac8b77ffcbb24b004aa84534892aThe following PHP code can be used to generate a digest to include in a request:
<?php
$APIKey = 'KLSAD8AHJA7Y7AASD';
$appId = '324KKJ2342';
$timestamp = time();
$digest = hash('sha256', $APIKey.$appId.$timestamp);
echo("Timestamp: $timestamp\n");
echo("digest: $digest\n");