CATAGS
中国航空运输协会团体标准
T/CATAGS 82—2024
民航重大运输保障任务旅客行李信息交互
规范
Specification of Passenger Baggage Information Interaction for Major Civil Aviation
Transport Support Tasks
2024-11-5 发布 2024-11-5 实施
中国航空运输协会发布
前言
本文件按照GB/T 1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。
本文件由中国航空运输协会归口。
请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。
本文件起草单位：中国民航信息网络股份有限公司、上海民航华东凯亚系统集成有限公司、中国民航大学。
本文件主要起草人：耿思、智慧、孙琼巍、杨勃、于辉、潘乃槟、王道明、黄小东、马晓宁、洪泽琳、毛丹、刘王君、胡冰、黄泽滨、陈艳江、谢玲玉
民航重大运输保障任务旅客行李信息交互规范
1 范围
本文件规定了民航重大运输保障任务中各参与方系统需要与中国民航行李全流程跟踪系统公共信息平台进行旅客行李信息交互时应遵循的规范。
本文件适用于民航重大运输保障任务中参与旅客行李运输保障的机场、航空公司及其他相关单位。
2 规范性引用文件
本文件没有规范性引用文件。
3 术语和定义
本文件没有需要界定的术语和定义。
4 缩略语
下列缩略语适用于本文件。
BTS：中国民航行李全流程跟踪系统公共信息平台(Baggage Tracking System)
5 基本要求
在民航重大运输保障任务中，当参与保障的相关业务单位需要获取重大运输保障中旅客的行李信息时，则应向BTS进行所需旅客行李数据订阅，并通过交互接口获取订阅旅客对应的行李数据。
6 业务流程要求
民航重大运输保障任务中相关保障单位的业务系统应按如下流程与BTS进行旅客行李信息的订阅与获取：
图1 获取民航重大运输保障任务旅客行李信息流程
7 交互数据
7.1 数据说明
民航重大运输保障任务中的相关各保障单位业务系统与BTS进行交互的数据应至少包含旅客信息数据、旅客行李信息数据。
交互数据数据必要性应符合表1的要求。
表1 数据必要性
7.2 旅客信息
民航重大运输保障任务中的相关保障单位可通过8.7的旅客行李数据订阅接口向BTS订阅指定旅客的行李信息数据，每次订阅的旅客信息为一组旅客列表，列表中的每个旅客信息数据项包含的字段应符合表2的要求。
表2 旅客信息数据项
7.3 旅客行李信息
BTS根据民航重大运输保障任务中的相关保障单位的旅客行李信息订阅需求，基于旅客姓名及登记序号进行匹配，查找相关保障单位订阅旅客对应的行李信息，并通过8.7订阅旅客的行李数据推送接口将订阅旅客的行李信息推送给相关保障单位。每次推送的旅客行李数据按照航班维度，将该航班上匹配到的订阅方需要的旅客及其行李数据返回，每次推送的旅客行李信息为一组行李列表，列表中的每件旅客行李信息数据项包含的字段应符合表3的要求。
表3 旅客行李信息数据项
表3 旅客行李信息数据项(续)
8 交互接口
8.1 接口类型
民航重大运输保障任务中相关保障单位的业务系统与BTS通过接口方式进行数据交互时，应包括向BTS订阅旅客数据的接口与BTS向相关保障单位业务系统推送订阅旅客的行李数据接口。
8.2 格式要求
交互接口应采用Json格式，UTF-8编码。
8.3 通讯协议
民航重大运输保障任务中各参与方系统与BTS进行旅客行李信息交互传输时应采用HTTPS协议，数据发送采用POST方式。一般在POST方法BODY中，上传json格式或文本/字符串参数。为了支持该格式，调用者需要在HTTPS Header参变量Content-type设定为application/json。
8.4 数据安全
保障单位的系统与BTS采用HTTPS协议进行信息的交互，确保数据在传输过程中的安全性和完整性，防止数据被窃听或篡改。
BTS统一为保障单位的系统分配访问凭证(appid、appkey),保障单位系统访问BTS须使用规定的签名算法，具体的算法见附录。
8.5 请求说明
调用方发起请求时，应携带签名信息，同时在HTTPS 的Header中携带以下字段：
——Content-Type：标准字段，调用方发送的数据类型，如 application/json
——X-trust-signature-version：签名方案版本，如 1.0
——X-trust-appid：值为服务器分配的 appid，如 419313
——X-trust-timestamp：值为时间戳，如 1581664261
——X-trust-nonce：随机数，调用方需在每次请求时，使用不同的随机数，用于防重放，如
af0ifjsldkj，短时间内不允许重复
——Content-MD5-HEX：请求 Body 的 MD5 值的十六进制小写表示，长度为 32 位，如
1917b36f0a7f732f0ca0da0651d498e7
——Method：请求方法，请求时携带，如 GET 或 POST
8.6 返回结果状态码说明
返回结果状态码code说明如下：
——200 请求成功
——400 Bad Request(请求出现语法错误)，如参数不合法
——401 Unauthorized(访问被拒绝，客户试图未经授权访问受密码保护的资源)
——403 Forbidden(资源不可用，服务器正确解析客户的请求，但拒绝处理它)
——404 Not Found(无法找到指定位置的资源)
——405Method Not Allowed(请求方法(GET、POST、HEAD、DELETE、PUT、TREACE 等))对指
定的资源不适用
——406 Not Acceptable(指定的资源已经找到，但资源的类型和请求的类型不兼容)
——409 Conflict(指定的资源版本不匹配，或者资源重复，服务器拒绝创建)
——其它在接口的返回中进行说明
8.7 旅客行李数据订阅接口
8.7.1 场景描述
参与民航重大运输保障任务的相关保障单位通过该接口，向BTS发送需订阅行李数据的旅客信息，每次订阅的旅客信息为一组旅客列表，列表中的每个旅客信息数据项包含的字段应符合表2的要求，一次批量订阅的旅客应小于50人，如超过50人则需每50人一次调用该接口进行订阅。
8.7.2 接口定义
接口定义如下：
——接口名称：旅客行李数据订阅接口;
——Content-type：application/json;charset=UTF-8;
——调用方式：POST;
——请求参数：见表4;
——返回值：见表 5。
表4 旅客行李数据订阅接口请求参数表
表5 接口返回值表
示例：
(1)请求
请求的Header中包含的内容如下：
POST /**/**/btMessageSubscribe
"Content-MD5-HEX"："aaa",
"X-trust-signature-version"："1.0",
"X-trust-appid":"ads",
"X-trust-timestamp":"103345454643", "X-trust-nonce":"serexgt"
"X-trust-signature"："xxxxxx"
"Content-Type": application/json;charset=UTF-8请求的Body中包含的内容如下：
{
"PASSENGERS"：[{
"competitionCode":"WOG", "boardNo"："034",
"flightNo":"CA981",
"flightDate":"2021-05-12",
"passengerbagStatus":"add",
"familyName"："li",
"firstName"："ming",
"middleName"："",
"gender":"M"
},{
"competitionCode":"WOG",
"boardNo"："114",
"flightNo":"CA981",
"flightDate":"2021-05-12",
"passengerbagStatus":"add",
"familyName"："Wang",
"firstName"："dong",
"middleName"："",
"gender":"M"
},{
"competitionCode":"WOG",
"boardNo"："066",
"flightNo":"CA981",
"flightDate":"2021-05-12",
"passengerbagStatus":"del",
"familyName"："Zhang",
"firstName"："nan",
"middleName"："",
"gender":"F"
}]
}
(2)成功返回
返回的Header中包含的内容如下：
HTTPS/1.1 200 OK
Content-Type: application/json
返回的Body包含的内容如下：
{
"data":"发送成功", "code": "200"
}
(3)失败返回
返回的Header中包含的内容如下：
HTTPS/1.1 404 NotFound
Content-Type: application/json
返回的Body包含的内容如下：
{
"data":"错误信息",
"code": "404"
}
8.8 订阅旅客的行李数据推送接口
8.8.1 场景描述
BTS通过该接口，向参与民航重大运输保障任务的相关保障单位推送其订阅旅客的行李数据。每次推送的旅客行李数据以航班为维度，将该航班上匹配到的保障单位所订阅的旅客的行李数据返回，每次推送的旅客行李信息为一组行李列表，列表中的每件旅客行李信息数据项包含的字段应符合表3的要求。
8.8.2 接口定义
接口定义如下：
——接口名称：获取订阅旅客的行李数据接口;
——Content-type：application/json;charset=UTF-8;
——调用方式：POST;
——请求参数：见表6;
——返回值：见表 5。
表6 数据推送接口请求参数表
示例：
(1)请求
请求的Header中包含的内容如下：
POST /**/**/btMessagePublish
"Content-MD5-HEX"："aaa",
"X-trust-signature-version"："1.0",
"X-trust-appid":"ads",
"X-trust-timestamp":"103345454643",
"X-trust-nonce":"serexgt",
"X-trust-signature"："xxxxxx",
"Content-Type": application/json;charset=UTF-8请求的Body中包含的内容如下：
{
"flightDate":"2021-05-12",
"airline":"CA",
"flightNo":"981",
"baggages": [{
"competitionCode":"WOG",
"boardNo"："034",
"familyName"："li",
"firstName"："ming",
"middleName"："",
"oriEng":"JFK",
"desEng":"PEK",
"bagbagStatus":"add", //行李新增标识"bagQty":"2",
"wgtUnit":"kg",
"bagWgt":"45",
"dimension":"",
"bagNumber":"999345,999346"
},{
"competitionCode":"WOG",
"boardNo"："114",
"familyName"："wang",
"firstName"："dong",
"middleName"："",
"oriEng":"JFK",
"desEng":"PEK",
"bagStatus":"del", //行李删除标识"bagQty":"2",
"wgtUnit":"kg",
"bagWgt":"45",
"dimension":"45*120*13,43*123*16", "bagNumber":"999345,999234"
}]
}
(2)成功返回
返回的Header中包含的内容如下：
HTTPS/1.1 200 OK
Content-Type: application/json
返回的Body中包含的内容如下：
{
"data":"发送成功",
"code": "200"
}
(3)失败返回
返回的Header中包含的内容如下：
HTTPS/1.1 404 NotFound
Content-Type: application/json
返回的Body中包含的内容如下：
{
"data":"错误信息", "code": "404"
}
A
A
附录 A
(资料性)
请求数据的签名计算方法
服务器分配appid和appkey给调用方，其中：appid用于标识调用方身份;appkey用于加密签名字符串和服务器端验证签名字符串的密钥，必须严格保密。
调用方发起请求时，需携带签名信息，服务器验证签名失败时，返回HTTP 403错误。
签名信息由HTTP协议Header中的X-trust-signature字段表示，而不是放在HTTP的Header字段Authorization中。
签名采用HMAC-SHA-1算法进行计算，具体如下：
Signature = HMAC-SHA-1(K, V)
其中：
——K 为 appkey 的值。
——V 根据附录 2 所述构造。
HMAC-SHA-1输出的原始结果为20字节二进制数据，在实际传输时，转换为40字节十六进制小写。
B
B
附录 B (资料性) V 的构造
调用方发起请求时，在HTTP的Header中，需携带以下字段：
——Content-Type：标准字段，调用方发送的数据类型，如application/json。
——X-trust-signature-version：签名方案版本， 目前为1.0。
——X-trust-appid：值为服务器分配的appid，如419313。
——X-trust-timestamp：值为时间戳，如1581664261。
——X-trust-nonce：随机数，调用方需在每次请求时，使用不同的随机数，用于防重放，如af0ifjsldkj，短时间内不允许重复。
— — Content-MD5-HEX： 请求 Body 的 MD5 值的十六进制小写表示， 长度为 32 位， 如1917b36f0a7f732f0ca0da0651d498e7 (如果请求 Body 为空，比如GET请求，则 32位的MD5值应为d41d8cd98f00b204e9800998ecf8427e)
——Method：请求方法，请求时携带，如GET或POST。
对上述7个字段，每个字段写成：字段名=字段值的形式，其中，字段名中的大小字母要转换成小写字母，字段值前后的空格要删除，即产生7个字符串，例如：
——content-type=application/json
——x-trust-signature-version=1.0
——x-trust-appid=419313
——x-trust-timestamp=1581664261
——x-trust-nonce=af0ifjsldkj
——content-md5-hex=1917b36f0a7f732f0ca0da0651d498e7
——method=POST
对这7个字符串，按字符串排序并使用&符号连接，就得到V的值：
content-md5-hex=1917b36f0a7f732f0ca0da0651d498e7&content-
type=application/json&method=POST&x-trust-appid=419313&x-trust-nonce=af0ifjsldkj&x-trust- signature-version=1.0&x-trust-timestamp=1581664261
