tencent cloud

Tencent Healthcare Data Services

문서Tencent Healthcare Data ServicesAPI DocumentationBundle Request APIsPlaceholder ID and Reference

Placeholder ID and Reference

Download
포커스 모드
폰트 크기
마지막 업데이트 시간: 2026-08-28 16:06:55
AI 번역

API Description

This function is used to establish reference relationships between resources that have not yet been assigned formal resource IDs within the same Bundle transaction. When a client does not know the final ID of a target resource before submission, it can assign a temporary placeholder ID to the resource and then use this placeholder to complete the resource reference within the same Bundle.
When processing a transaction, the server resolves placeholder IDs to actual resource IDs and automatically updates the relevant reference relationships.

Input parameters

Parameter Name
Type
Required
Description
HTTP Method
String
Yes
Fixed to POST.
URL
String
Yes
The Bundle submission URL, usually [baseUrl].
Authorization
String
Yes
The authentication token, in the format Bearer <AccessToken>. The AccessToken is obtained via the GetAccessToken API in Calling Methods (or via the GetWebAccessToken API in the instance console scenario).
Content-Type
String
Yes
The MIME type of the request body, with application/fhir+json as an example.
Request Body
JSON Object
Yes
A transaction Bundle containing placeholder IDs and reference relationships.
Request URL Example:
https://HOSTNAME/INSTANCE_ID/fhir
Request Body Main Field Descriptions:
Field
Type
Required
Description
entry[].fullUrl
String
No
A placeholder ID, typically in the format urn:uuid:{uuid}. It must be filled in when the entry needs to be referenced by other entries within the same Bundle; it can be omitted when only creating a resource without being referenced.
entry[].resource
Object
Yes
The corresponding resource content.
entry[].resource.subject.reference
String
No
A placeholder reference pointing to other entries.
entry[].request.method
String
Yes
The request method for the entry, with POST as an example.
entry[].request.url
String
Yes
The target resource path for the entry.
Note:
Placeholder IDs must be randomly generated by the client.
Placeholder IDs are used only within the current Bundle to establish reference relationships.
After the transaction is processed, the server assigns a formal ID to the newly created resource and updates the references.

Output Parameters

Upon a successful API call, the HTTP status code 200 OK or 201 Created is typically returned. The response headers contain the content type and request trace information, and the response body is usually a result Bundle that includes the resource location after actual write operations and the processing status.
Response Header Example Description:
Parameter Name
Type
Description
Status Code
Integer
Returns 200 OK or 201 Created when successful.
Content-Type
String
The MIME type of the response body, typically application/fhir+json.
x-request-id
String
Request trace ID.
Key Response Body Field Descriptions:
Field
Type
Description
resourceType
String
Returns the resource type, which is fixed as Bundle.
id
String
The unique ID of the response Bundle, generated by the server.
type
String
The type of the response Bundle, which is fixed as transaction-response.
link
Array
Navigation links, containing a self link that points to the current request address.
link[].relation
String
The type of link relation, usually self.
link[].url
String
The URL corresponding to the link.
entry
Array
Execution results of the entries.
entry[].response.status
String
The execution status of the entry, such as 201 Created.
entry[].response.location
String
The actual location of the newly created resource.
entry[].response.etag
String
Resource version identifier.
entry[].response.lastModified
String
Last modification time of the resource.
entry[].response.outcome
Object
Details of the entry execution outcome, which is the OperationOutcome resource and contains execution status information.

Examples

Request Example

POST /INSTANCE_ID/fhir HTTP/1.1
Host: HOSTNAME
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/fhir+json
{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:e16eac01-a5ee-4904-b1c8-f4bd56e338d5",
      "resource": {
        "resourceType": "Patient",
        "identifier": [
          {
            "system": "http://acme.org/mrns",
            "value": "013872"
          }
        ],
        "name": [
          {
            "family": "Simpson",
            "given": [
              "Homer"
            ]
          }
        ],
        "gender": "male"
      },
      "request": {
        "method": "POST",
        "url": "Patient"
      }
    },
    {
      "fullUrl": "urn:uuid:499733fe-7ced-4d15-81ce-8a433a1fb71e",
      "resource": {
        "resourceType": "Condition",
        "clinicalStatus": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
              "code": "active"
            }
          ]
        },
        "verificationStatus": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
              "code": "confirmed"
            }
          ]
        },
        "category": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/condition-category",
                "code": "problem-list-item",
                "display": "Problem List Item"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "59621000",
              "display": "Essential hypertension"
            }
          ]
        },
        "subject": {
          "reference": "urn:uuid:e16eac01-a5ee-4904-b1c8-f4bd56e338d5"
        }
      },
      "request": {
        "method": "POST",
        "url": "Condition"
      }
    }
  ]
}

Response Example

HTTP/1.1 200 OK
Content-Type: application/fhir+json;charset=UTF-8
Location: https://HOSTNAME/INSTANCE_ID/fhir/Bundle/bundle-response-id
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Bundle/bundle-response-id
x-request-id: <REQUEST_ID>
{
  "resourceType": "Bundle",
  "id": "bundle-response-id",
  "type": "transaction-response",
  "link": [
    {
      "relation": "self",
      "url": "https://HOSTNAME/INSTANCE_ID/fhir"
    }
  ],
  "entry": [
    {
      "response": {
        "status": "201 Created",
        "location": "Patient/patient-resource-id/_history/1",
        "etag": "1",
        "lastModified": "2022-02-23T10:00:00.000+08:00",
        "outcome": {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "information",
              "code": "informational",
              "details": {
                "coding": [
                  {
                    "system": "https://hapifhir.io/fhir/CodeSystem/hapi-fhir-storage-response-code",
                    "code": "SUCCESSFUL_CREATE",
                    "display": "Create succeeded."
                  }
                ]
              },
              "diagnostics": "Successfully created resource \\"Patient/patient-resource-id/_history/1\\"."
            }
          ]
        }
      }
    },
    {
      "response": {
        "status": "201 Created",
        "location": "Condition/condition-resource-id/_history/1",
        "etag": "1",
        "lastModified": "2022-02-23T10:00:00.000+08:00",
        "outcome": {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "information",
              "code": "informational",
              "details": {
                "coding": [
                  {
                    "system": "https://hapifhir.io/fhir/CodeSystem/hapi-fhir-storage-response-code",
                    "code": "SUCCESSFUL_CREATE",
                    "display": "Create succeeded."
                  }
                ]
              },
              "diagnostics": "Successfully created resource \\"Condition/condition-resource-id/_history/1\\"."
            }
          ]
        }
      }
    }
  ]
}

Error Codes

Common error codes are listed below. For more error codes, see Error Codes.
Error Code
Description
400 Bad Request
Placeholder ID format is incorrect, or the reference path is invalid.
401 Unauthorized
Not authenticated, and valid credentials are missing.
403 Forbidden
Authenticated but not authorized to perform Bundle operations.
409 Conflict
Reference relationship conflict or resource state conflict
422 Unprocessable Entity
The Bundle syntax is correct, but it fails business or rule validation.
500 Internal Server Error
Internal server processing exception

이전 주제: Bundling Multiple Associated Resources다음 주제: Condition Creation

도움말 및 지원

문제 해결에 도움이 되었나요?

피드백