ICS 35.240.99
L 65
National Standard of the People’s Republic of China
GB/T 38963-2020
Personal health information code — Application interface
个人健康信息码 个人健康信息码 应用接口 应用接口
(English Translation)
Issue date: 2020-04-29 Implementation date: 2020-04-29
Issued by the State Administration for Market Regulation
the Standardization Administration of the People's Republic of China
Contents
Foreword ................................ ................................ ................................ ............................... i
Introduction ................................ ................................ ................................ .......................... ii
1 Scope ................................ ................................ ................................ ............................. 1
2 Normative references ................................ ................................ ................................ ..... 1
3 Terms and definitions ................................ ................................ ................................ ..... 1
4 Abbreviations................................ ................................ ................................ .................. 1
5 Interface rules ................................ ................................ ................................ ................ 1
5.1 Interface mode ................................ ................................ ................................ ..... 1
5.2 Service type ................................ ................................ ................................ ......... 2
6 Interface description ................................ ................................ ................................ ....... 2
6.1 General ................................ ................................ ................................ ................ 2
6.2 Declaration of user health information ................................ ................................ . 3
6.3 User travel declaration interface ................................ ................................ .......... 5
6.4 User health information query ................................ ................................ ............. 6
6.5 Health code calling request interface ................................ ................................ .. 9
6.6 Query interface for generating health code ................................ ....................... 11
6.7 Query interface for verifying health code ................................ ........................... 12
6.8 Error correction interface of user health information ................................ ......... 14
7 Interface application ................................ ................................ ................................ ..... 15
7.1 Application Modes ................................ ................................ ............................. 16
7.2 Linking mode ................................ ................................ ................................ ...... 16
Annex A (informative) Operation instructions of BizExtData field in health code ........... 17
Annex B (informative) Description of interface return code ................................ ............ 18
Annex C (informative) Example of calling of health code generation and verification ... 20
Bibliography ................................ ................................ ................................ ....................... 21
i
ii
Introduction
In the process of preventing, controlling and eliminating the hazards of public health emergencies (such as pneumonia COVID-19 caused by novel coronavirus), it is necessary to collect, store and process personal health information for various management purposes, including:
—— Quickly obtain relevant information about personal health;
—— Collect relevant information about an epidemic or disease;
—— Manage personnel flow between different regions;
—— Mutual recognition of health information business level.
Since February 2020, in the process of prevention and control of COVID-19 epidemic and resumption of production, the epidemic prevention health information code provided by the National Integrated Online Government Service Platform (referred to as "integrated platform") and the "health code" used by some provinces (autonomous regions and municipalities) have become an important form of personal health information code, and become an effective way to quickly collect, store and process personal health information. In the practical application of personal health information codes, there are problems such as inconsistent code composition and data format, non-sharing of data and lack of mutual recognition mechanism, which bring inconveniences to the movement of people across regions. Therefore, from the current practice situation and long-term application needs, it is necessary to achieve consistent standards for personal health information codes. In addition to emergency response to public health emergencies, personal health information codes are equally applicable in the process of managing personal medical care, health care or other major public events.
For the specific matters specified in this standard, if there are other provisions in laws and regulations (such as Cybersecurity Law of the People's Republic of China and Law of the People's Republic of China on Prevention and Treatment of Infectious Diseases), these provisions shall be followed.
1
Personal health information code — Application interface
1 Scope
This standard specifies the interface rules, interface descriptions and interface applications of personal health service interfaces.
This standard is applicable to the design, development and system integration of personal health information related application systems.
2 Normative references
The following referenced documents are indispensable for the application of this standard. For dated reference, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
GB/T 2260
Codes for the administrative divisions of the People’s Republic of China
GB/T 38961-2020
Personal health information code — Reference model
3 Terms and definitions
For the purposes of this document, the terms and definitions given in GB/T 38961-2020 apply.
4 Abbreviations
For the purposes of this document, the following abbreviations apply.
HTTP: HyperText Transfer Protocol
JSON: JavaScript Object Notation
REST: Representational State Transfer
WEB: World Wide Web
5 Interface rules
5.1 Interface mode
2
The personal health information service system shall adopt the Web service conforming to the REST architecture principle when publishing services and receiving requests.
5.2 Service type
See Table 1 for description of service types related to health codes.
Table 1 Description of service type
No.
Service type
Service name
1
1000
Health code calling request interface
2
2000
Health code generation interface
3
3000
Health code verification interface
See Table 2 for the description of the verification mode in the health code generation interface.
Table 2 Description for the verification mode in the health code generation interface
No.
Code
Mode name
1
G100
Code generation of residential identity network identifier
2
G010
Code generation of web certificate data
See Table 3 for the description of the verification mode in the health code verification interface.
Table 3 Description of the verification mode in the verification interface
No.
Code
Mode name
1
V000
Business verification code
2
V033
Identity + business verification code
3
V034
Identity + portrait + business verification code
6 Interface description
6.1 General
See Table 4 for the interface types and descriptions.
3
Table 4 Interface types and descriptions
No.
Interface type
Interface description
1
User health information declaration interface
Upload health data information declared by users
2
User travel information declaration interface
Upload the data information of the user's travel within the specified time range (for example, 14 days)
3
User health information query interface
Query the personal health information and travel information of the user within a certain period of time. The default query period is the time specified by relevant departments (for example, 14 days)
4
Health code calling request interface
Before the client initiates a business application (such as code generation and code for verification, etc.) to the server, it needs to apply for session permission through this interface
5
Query interface for generating health code
Send code generation request to the background of the health code application system
6
Query interface for verifying health code
Send code verification request to the background of the health code application system
7
Error correction interface of user health information
Send a request for correcting relevant information to the background of the health code application system
6.2 Declaration of user health information
6.2.1 Calling mode
The user health information declaration interface shall be called through the Internet or the National E-Government Network.
6.2.2 Parameter requirements
See Table 5 for parameter requirements of user health information declaration interface.
Table 5 Parameter requirements of user health information declaration interface
Category
Parameter
Required or not
Data
Type
Description
Input parameter
AccountId
Yes
Character string
Authorized account
AccessToken
Yes
Character string
Access token
BizExtData
Yes
Character string
See Annex A for the values spliced according to the form determined in 4.2 of GB/T 38961-2020 and encrypted by key
Phone
No
Character string
Contact number (telephone number of direct relatives may be filled in)
21
Bibliography
[1] GB/T 38962-2020 Personal health information code — Data format
___________________________________________________ __________________________________ _________________ __________________________________ _________________ __________________________________
Foreword i
Introduction ii
1 Scope
2 Normative references
3 Terms and definitions
4 Abbreviations
5 Interface rules
5.1 Interface mode
5.2 Service type
6 Interface description
6.1 General
6.2 Declaration of user health information
6.3 User travel declaration interface
6.4 User health information query
6.5 Health code calling request interface
6.6 Query interface for generating health code
6.7 Query interface for verifying health code
6.8 Error correction interface of user health information
7 Interface application
7.1 Application Modes
7.2 Linking mode
Annex A (informative) Operation instructions of BizExtData field in health code
Annex B (informative) Description of interface return code
Annex C (informative) Example of calling of health code generation and verification
Bibliography
ICS 35.240.99
L 65
National Standard of the People’s Republic of China
GB/T 38963-2020
Personal health information code — Application interface
个人健康信息码 个人健康信息码 应用接口 应用接口
(English Translation)
Issue date: 2020-04-29 Implementation date: 2020-04-29
Issued by the State Administration for Market Regulation
the Standardization Administration of the People's Republic of China
Contents
Foreword ................................ ................................ ................................ ............................... i
Introduction ................................ ................................ ................................ .......................... ii
1 Scope ................................ ................................ ................................ ............................. 1
2 Normative references ................................ ................................ ................................ ..... 1
3 Terms and definitions ................................ ................................ ................................ ..... 1
4 Abbreviations................................ ................................ ................................ .................. 1
5 Interface rules ................................ ................................ ................................ ................ 1
5.1 Interface mode ................................ ................................ ................................ ..... 1
5.2 Service type ................................ ................................ ................................ ......... 2
6 Interface description ................................ ................................ ................................ ....... 2
6.1 General ................................ ................................ ................................ ................ 2
6.2 Declaration of user health information ................................ ................................ . 3
6.3 User travel declaration interface ................................ ................................ .......... 5
6.4 User health information query ................................ ................................ ............. 6
6.5 Health code calling request interface ................................ ................................ .. 9
6.6 Query interface for generating health code ................................ ....................... 11
6.7 Query interface for verifying health code ................................ ........................... 12
6.8 Error correction interface of user health information ................................ ......... 14
7 Interface application ................................ ................................ ................................ ..... 15
7.1 Application Modes ................................ ................................ ............................. 16
7.2 Linking mode ................................ ................................ ................................ ...... 16
Annex A (informative) Operation instructions of BizExtData field in health code ........... 17
Annex B (informative) Description of interface return code ................................ ............ 18
Annex C (informative) Example of calling of health code generation and verification ... 20
Bibliography ................................ ................................ ................................ ....................... 21
i
ii
Introduction
In the process of preventing, controlling and eliminating the hazards of public health emergencies (such as pneumonia COVID-19 caused by novel coronavirus), it is necessary to collect, store and process personal health information for various management purposes, including:
—— Quickly obtain relevant information about personal health;
—— Collect relevant information about an epidemic or disease;
—— Manage personnel flow between different regions;
—— Mutual recognition of health information business level.
Since February 2020, in the process of prevention and control of COVID-19 epidemic and resumption of production, the epidemic prevention health information code provided by the National Integrated Online Government Service Platform (referred to as "integrated platform") and the "health code" used by some provinces (autonomous regions and municipalities) have become an important form of personal health information code, and become an effective way to quickly collect, store and process personal health information. In the practical application of personal health information codes, there are problems such as inconsistent code composition and data format, non-sharing of data and lack of mutual recognition mechanism, which bring inconveniences to the movement of people across regions. Therefore, from the current practice situation and long-term application needs, it is necessary to achieve consistent standards for personal health information codes. In addition to emergency response to public health emergencies, personal health information codes are equally applicable in the process of managing personal medical care, health care or other major public events.
For the specific matters specified in this standard, if there are other provisions in laws and regulations (such as Cybersecurity Law of the People's Republic of China and Law of the People's Republic of China on Prevention and Treatment of Infectious Diseases), these provisions shall be followed.
1
Personal health information code — Application interface
1 Scope
This standard specifies the interface rules, interface descriptions and interface applications of personal health service interfaces.
This standard is applicable to the design, development and system integration of personal health information related application systems.
2 Normative references
The following referenced documents are indispensable for the application of this standard. For dated reference, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
GB/T 2260
Codes for the administrative divisions of the People’s Republic of China
GB/T 38961-2020
Personal health information code — Reference model
3 Terms and definitions
For the purposes of this document, the terms and definitions given in GB/T 38961-2020 apply.
4 Abbreviations
For the purposes of this document, the following abbreviations apply.
HTTP: HyperText Transfer Protocol
JSON: JavaScript Object Notation
REST: Representational State Transfer
WEB: World Wide Web
5 Interface rules
5.1 Interface mode
2
The personal health information service system shall adopt the Web service conforming to the REST architecture principle when publishing services and receiving requests.
5.2 Service type
See Table 1 for description of service types related to health codes.
Table 1 Description of service type
No.
Service type
Service name
1
1000
Health code calling request interface
2
2000
Health code generation interface
3
3000
Health code verification interface
See Table 2 for the description of the verification mode in the health code generation interface.
Table 2 Description for the verification mode in the health code generation interface
No.
Code
Mode name
1
G100
Code generation of residential identity network identifier
2
G010
Code generation of web certificate data
See Table 3 for the description of the verification mode in the health code verification interface.
Table 3 Description of the verification mode in the verification interface
No.
Code
Mode name
1
V000
Business verification code
2
V033
Identity + business verification code
3
V034
Identity + portrait + business verification code
6 Interface description
6.1 General
See Table 4 for the interface types and descriptions.
3
Table 4 Interface types and descriptions
No.
Interface type
Interface description
1
User health information declaration interface
Upload health data information declared by users
2
User travel information declaration interface
Upload the data information of the user's travel within the specified time range (for example, 14 days)
3
User health information query interface
Query the personal health information and travel information of the user within a certain period of time. The default query period is the time specified by relevant departments (for example, 14 days)
4
Health code calling request interface
Before the client initiates a business application (such as code generation and code for verification, etc.) to the server, it needs to apply for session permission through this interface
5
Query interface for generating health code
Send code generation request to the background of the health code application system
6
Query interface for verifying health code
Send code verification request to the background of the health code application system
7
Error correction interface of user health information
Send a request for correcting relevant information to the background of the health code application system
6.2 Declaration of user health information
6.2.1 Calling mode
The user health information declaration interface shall be called through the Internet or the National E-Government Network.
6.2.2 Parameter requirements
See Table 5 for parameter requirements of user health information declaration interface.
Table 5 Parameter requirements of user health information declaration interface
Category
Parameter
Required or not
Data
Type
Description
Input parameter
AccountId
Yes
Character string
Authorized account
AccessToken
Yes
Character string
Access token
BizExtData
Yes
Character string
See Annex A for the values spliced according to the form determined in 4.2 of GB/T 38961-2020 and encrypted by key
Phone
No
Character string
Contact number (telephone number of direct relatives may be filled in)
21
Bibliography
[1] GB/T 38962-2020 Personal health information code — Data format
___________________________________________________ __________________________________ _________________ __________________________________ _________________ __________________________________
Contents of GB/T 38963-2020
Foreword i
Introduction ii
1 Scope
2 Normative references
3 Terms and definitions
4 Abbreviations
5 Interface rules
5.1 Interface mode
5.2 Service type
6 Interface description
6.1 General
6.2 Declaration of user health information
6.3 User travel declaration interface
6.4 User health information query
6.5 Health code calling request interface
6.6 Query interface for generating health code
6.7 Query interface for verifying health code
6.8 Error correction interface of user health information
7 Interface application
7.1 Application Modes
7.2 Linking mode
Annex A (informative) Operation instructions of BizExtData field in health code
Annex B (informative) Description of interface return code
Annex C (informative) Example of calling of health code generation and verification
Bibliography
