tencent cloud

Tencent Healthcare Data Services

DocumentationTencent Healthcare Data ServicesAPI DocumentationCalling Methods

Calling Methods

Download
Focus Mode
Font Size
Last updated: 2026-08-28 16:06:54
AI-Translated
This document describes the general invocation method for the platform's FHIR Restful APIs, covering the request structure, common parameters, API authentication, and response format. Before accessing FHIR resource APIs, the caller must first obtain an AccessToken using an API key and signature mechanism, and then access the business APIs using the Bearer Token method.

Request Structure

The platform invocation process is divided into two phases:
Call the authentication service to obtain an AccessToken using an API Key, a timestamp, and a signature.
When accessing FHIR Restful APIs, include the access token via the Authorization: Bearer <AccessToken> header.

Authentication Service Request Structure

Request Method:
POST /cmd/GetAccessToken HTTP/1.1
Host: <FHIR_SERVICE_HOST>
Content-Type: application/json
Note:
<FHIR_SERVICE_HOST> is the domain name for accessing the authentication service. Refer to the instance access information in the Tencent Healthcare Data Services console or the service access address provided by the deployment party.
The <FHIR_SERVICE_HOST> in the example is a placeholder. Replace it with an actual accessible domain name when making calls, and do not use the placeholder directly to send requests.
Request Body Structure:
{
  "header": {
    "version": "v0.1",
    "flag": 0
  },
  "body": {
    "seq": 0,
    "cmd": "",
    "token": "",
    "traceid": "",
    "client": {
      "platform": 0,
      "env": "",
      "isTourist": 0,
      "product": 0
    },
    "payload": {
      "timestamp": 1730000000000,
      "apiKey": "<API_KEY>",
      "signature": "<SIGNATURE>",
      "scopes": [],
      "context": {}
    }
  }
}
Note:
timestamp is a millisecond-level Unix timestamp.
signature is a signature value calculated based on the API Secret.
scopes and context are extension fields and can be passed in based on the actual authorization scenario.

FHIR Restful Request Structure

The request method varies depending on the API's capabilities. Common methods are as follows:
POST: Creates a resource or submits a Bundle transaction/batch request.
GET: Reads resources, reads historical versions, and performs searches.
PUT: Updates the complete resource content.
PATCH: Updates partial fields.
DELETE: Deletes the specified resource.
General Request Example:
GET /INSTANCE_ID/fhir/Patient/199963 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json
Here, HOSTNAME is the FHIR service access domain name, and INSTANCE_ID is the FHIR service instance ID. Obtain them from the instance access information in the Tencent Healthcare Data Services console, or refer to the service access address provided by the deployment party.
The request URL typically follows the format below:
Resource Read/Write: [baseUrl]/[resourceType] or [baseUrl]/[resourceType]/[id]
Historical Version Read: [baseUrl]/[resourceType]/[id]/_history/[versionId]
Search: [baseUrl]/[resourceType]?[searchParams]
Retrieve Complete Patient Information: [baseUrl]/Patient/[id]/$everything
Bundle Transaction/Batch Processing: [baseUrl]

Common parameter

Common Parameters for Authentication Requests

Parameter Name
Type
Required
Description
header.version
String
Yes
Request protocol version. Example: v0.1.
header.flag
Integer
Yes
Request flag. Example: 0.
body.seq
Integer
Yes
Request sequence number. Example: 0.
body.cmd
String
No
Reserved command field
body.token
String
No
Reserved token field. It is usually empty when AccessToken is obtained.
body.traceid
String
No
Request trace ID
body.client.platform
Integer
No
Client platform identifier
body.client.env
String
No
Calling environment identifier
body.client.isTourist
Integer
No
Tourist identifier
body.client.product
Integer
No
Product identifier
body.payload.timestamp
Integer
Yes
Millisecond-level timestamp. The server allows a time window of 3600000 milliseconds (1 hour) before and after the request arrival time at the server. Requests outside this window are rejected.
body.payload.apiKey
String
Yes
API Keys
body.payload.signature
String
Yes
Signature value
body.payload.scopes
Array
Conditionally Required
The requested permission scope. It is required when Informed Consent Access Control is enabled, and must contain at least one actor/<ResourceType>/<ID> (for example, "actor/Practitioner/P001"). Otherwise, accessing the FHIR API returns a 401 error (the scope field is missing in Claims). It can be left empty ([]) when not enabled.
body.payload.context
Object
No
Context extension parameters

Common Parameters for FHIR Requests

Parameter Name
Type
Required
Description
Host
String
Yes
The FHIR service access domain name, for example, HOSTNAME. Obtain it from the instance access information in the Tencent Healthcare Data Services console, or use the service access address provided by the deployment party.
Authorization
String
Yes
The access token, in the format Bearer <AccessToken>
Content-Type
String
No
The type of the request body. Write-type requests typically use application/fhir+json; Patch requests typically use application/json-patch+json.
Accept
String
No
The response format. It is recommended to use application/fhir+json.
resourceType
String
Depends on the API
The FHIR resource type, such as Patient, Observation, Encounter
id
String
Depends on the API
The unique identifier for a resource
searchParams
Query String
No
Search parameters, used to filter the result set
versionId
String
No
The historical version ID, used in scenarios such as vRead

API authentication

The platform employs a token-based authentication method that relies on API Key, API Secret, and a signature mechanism. The caller must first request an AccessToken from the authentication service and then access the FHIR APIs by including this token.

Authentication Process

The caller holds the API Key and API Secret corresponding to the service.
The caller generates a millisecond-level timestamp timestamp.
The caller generates the signature using a signature algorithm.
The caller submits the apiKey, timestamp, and signature to the authentication API.
The authentication service validates the signature and timestamp.
Upon successful validation, a JWT-based AccessToken is returned.
When accessing FHIR Restful APIs, the caller includes the token via the Authorization request header.
Upon receiving a request, the FHIR service validates the AccessToken.
If the validation passes, the business result is returned; if it fails, access is denied.

Signature algorithm

Signature Original Text Concatenation Method:
message = apiKey + timestamp
Signature Algorithm:
signature = HMAC-SHA256(apiSecret, message)
Note:
The message is encoded using UTF-8.
timestamp is a millisecond-level timestamp.
The signature result is represented as a hexadecimal string.
The sample code explicitly returns an uppercase hexadecimal string. During validation, the server is case-insensitive to the signature.

Timestamp Verification Rules

The server validates whether the request timestamp falls within the allowed timeout window. The current allowed window is 3600000 milliseconds (1 hour) before and after the request arrival time at the server:
If timestamp > server current time + 3600000, the request will be rejected.
If timestamp < server current time - 3600000, the request will be rejected.
Typical failure scenarios are as follows:
signTime is timed out
signature is invalid

Access Token Usage

After obtaining the AccessToken, the caller must place it in the HTTP Header when accessing the FHIR API:
Authorization: Bearer <AccessToken>
Field descriptions are as follows:
Header Key:Authorization
Header Value: Bearer <space><AccessToken>

Sample Code

Signature-based method for obtaining an access_token.
import hashlib
import hmac
import time
from typing import Optional

import requests


def sign(api_key: str, api_secret: str, sign_time: int) -> str:
    Signature

    Args:
        api_key: API Key
        api_secret: Secret corresponding to the API Key
        sign_time: Signature time (in milliseconds)

    Returns:
        Signature string (uppercase hexadecimal)
    """
    message = f"{api_key}{sign_time}".encode("utf-8")
    h = hmac.new(api_secret.encode("utf-8"), message, hashlib.sha256)
    return h.hexdigest().upper()


# Signature Verification Logic (For Local Self-Testing)
def check_signature(api_key: str, api_secret: str, signature: str, sign_time: int, timeout: int) -> Optional[str]:
    Verify Signature

    Args:
        api_key: API Key
        api_secret: Secret corresponding to the API Key
        signature: Signature string
        sign_time: Signature time (in milliseconds)
        timeout: Timeout duration (in milliseconds)

    Returns:
        A value of None indicates successful validation; otherwise, an error message is returned.
    """
    now_time = int(time.time() * 1000)  # Current time (in milliseconds)

    if sign_time > now_time + timeout or sign_time < now_time - timeout:
        return "signTime is timed out"

    calculated_sign = sign(api_key, api_secret, sign_time)
    if signature.upper() != calculated_sign.upper():
        return "signature is invalid"

    return None


def request_auth_server(api_key: str, api_secret: str) -> Optional[str]:
    sign_time = int(time.time() * 1000)
    signature = sign(api_key, api_secret, sign_time)

    rsp = requests.post(
        # Replace <FHIR_SERVICE_HOST> with the actual authentication service access domain name
        url="https://<FHIR_SERVICE_HOST>/cmd/GetAccessToken",
        json={
            "header": {
                "version": "v0.1",
                "flag": 0,
            },
            "body": {
                "seq": 0,
                "cmd": "",
                "token": "",
                "traceid": "",
                "client": {
                    "platform": 0,
                    "env": "",
                    "isTourist": 0,
                    "product": 0,
                },
                "payload": {
                    "timestamp": sign_time,
                    "apiKey": api_key,
                    "signature": signature,
                    "scopes": [],
                    "context": {},
                },
            },
        },
        timeout=10,
    )

    if rsp.status_code != 200:
        return None

    data = rsp.json()
    if data.get("retcode", 0) != 0:
        return None

    payload = data.get("payload") or {}
    return payload.get("accessToken")


if __name__ == "__main__":
    key = "<KEY>"
    secret = "<SECRET>"
    token = request_auth_server(key, secret)
    print(token)

Returned Result

Authentication API Returned Result

Upon a successful authentication API call, the returned result contains an accessToken. The caller should securely store this token and use it in subsequent FHIR requests. A sample of the returned result is as follows:
{
  "payload": {
    "accessToken": "<ACCESS_TOKEN>"
  }
}
If the authentication API call fails, the following situations may occur:
The HTTP status code is not 200.
The accessToken is not returned in the response.
Signature validation failed or the timestamp is invalid.

FHIR API Returned Result

FHIR API responses adhere to the standard FHIR resource structure, and the returned content varies across different API scenarios:
APIs for resource creation, update, and read: Typically return the corresponding resource content.
Search APIs: Typically return a Bundle.
Deletion APIs: Typically return an OperationOutcome or a status result.
Transaction/Batch APIs: Typically return a Bundle.
Common response headers include:
Parameter Name
Description
Status Code
HTTP status code, used to identify the request processing result.
ETag
Resource version identifier
Location / Content-Location
Access address for the resource or its historical versions

Returned Result Processing

For write-type APIs, it is recommended to determine whether the write operation was successful by checking the Status Code, ETag, and Location.
For search APIs, it is recommended to prioritize parsing Bundle.entry, Bundle.total, and Bundle.link.
For deletion and exception scenarios, it is recommended to pinpoint the specific cause by examining the OperationOutcome or the error response body.

Previous Topic: API OverviewNext Topic: Creating

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback