报文反向解析接口文档

接口概述

该接口用于将符合TCP位置上报协议的十六进制报文解析为结构化JSON数据，支持验证报文格式合法性并提取终端编号、定位信息等关键字段，便于开发调试和数据校验。

接口信息

• 接口地址：wuhan.gishub.com.cn:4100/position-server/test/packet/parse
• 请求方法：POST
• 请求格式：纯文本（十六进制报文字符串）
• 响应格式：JSON
• 接口标签：报文反向解析接口

请求参数说明

参数名	类型	是否必传	描述	示例值
十六进制报文	String	是	待解析的TCP上报报文（不含空格或特殊字符）	FF0000006502A1A1A1...FF（完整帧结构报文）

响应参数说明

成功响应（success: true）

一级字段	二级字段	类型	描述	示例值
success	-	Boolean	解析是否成功	true
parsedData	packetLength	Integer	报文总长度（字节）	102
	version	String	协议版本号（十六进制）	0x02
	terminalId	String	终端编号（BCD编码转换后）	0012345678901234567
	deviceType	String	设备类型编码（BCD编码转换后）	8800012345678901234
	appIdSecretMd5	String	appID与秘钥的MD5编码	e10adc3949ba59abbe56e057f20f883e
	locationData	Object	定位数据详情	-
	├ date	String	定位日期（yyyy-MM-dd）	2023-10-05
	├ time	String	定位时间（HH:mm:ss）	14:30:25
	├ coordinateType	String	坐标类型描述	NETWORK（网络定位）
	├ latLonFlag	String	经纬度方向（北纬/南纬，东经/西经）	北纬：true，东经：true
	├ longitude	Long	经度值（小端序解析后）	1163972000
	├ latitude	Long	纬度值（小端序解析后）	399075000
	├ speed	String	速度（单位：km/h）	60 km/h
	├ direction	String	方向角（单位：度）	90°
	└ altitude	String	高度（单位：米）	50 m
description	-	String	解析结果描述	报文解析成功

失败响应（success: false）

字段	类型	描述	示例值
success	Boolean	解析是否成功	false
message	String	错误原因描述	帧头或帧尾不正确（应为0xFF）

接口逻辑说明

1. 输入校验：检查十六进制字符串是否为空、长度是否为偶数。
2. 帧结构验证：验证报文首尾是否为0xFF（帧头/帧尾）。
3. 逆转义处理：将报文中的0xFE00还原为0xFF，0xFE01还原为0xFE。
4. 字段解析：

• 按协议格式提取包长、版本号、终端编号等基础字段。
• 解析22字节定位数据，包括日期时间、坐标类型、经纬度等信息。
• 对多字节字段（如经度、速度）按小端序转换。

5. 结果组装：将解析后的数据转换为可读性强的JSON结构返回。

调用示例

正确报文请求示例

FF63000000020000000000000000000000000000098765432100000000000000000000000000000000123456616263646566303132333435363738396162636465663031323334353637383919070B111D3B0103003B61455C4ECA175000B4006400FF

正确响应示例

{
  "parsedDataFromHEX": {
    "deviceType": "00000000000000000000000000000000123456",
    "locationData": {
      "date": "2025-07-11",
      "altitude": "100 m",
      "latitude": 399134300,
      "coordinateType": "BD（北斗）",
      "time": "17:29:59",
      "latLonFlag": "北纬：true，东经：true",
      "speed": "80 km/h",
      "longitude": 1164000000,
      "direction": "180°"
    },
    "packetLength": 99,
    "terminalId": "00000000000000000000000000000987654321",
    "appIdSecretMd5": "abcdef0123456789abcdef0123456789",
    "version": "0x2"
  },
  "parsedDataConvert": {
    "deviceId": "00000000000000000000000000000000123456",
    "terminalId": "00000000000000000000000000000987654321",
    "locationType": "BD",
    "longitude": 116.4,
    "latitude": 39.91343,
    "altitude": 100,
    "speed": 22.222221,
    "direction": 180,
    "timestamp": 1752226199000,
    "createTime": "2025-07-11T09:29:53.250+00:00"
  },
  "success": true,
  "description": "报文解析成功"
}

错误报文请求示例

FF63000000020000000000000000000000000000012345678900000000000000000001938123186535186432303031232370617373776F726431323334353637383930616263646566000000180A050F1E2D0203A0CD6045B866C9173C005A003200FF

错误响应示例

{
  "parsedDataFromHEX": {
    "deviceType": "00000000000000000000000000000000123456",
    "locationData": {
      "date": "2024-13-31",
      "altitude": "100 m",
      "latitude": 399134300,
      "coordinateType": "BD（北斗）",
      "time": "23:59:59",
      "latLonFlag": "北纬：true，东经：true",
      "speed": "80 km/h",
      "longitude": 1164000000,
      "direction": "180°"
    },
    "packetLength": 99,
    "terminalId": "00000000000000000000000000000987654321",
    "appIdSecretMd5": "abcdef0123456789abcdef0123456789",
    "version": "0x2"
  },
  "parsedDataConvertError": "非法月份: 13 (范围: 1-12)",
  "success": true,
  "description": "报文解析成功"
}

错误码说明

错误信息	可能原因	解决方案
请传入十六进制报文	请求体为空或仅含空格	检查请求体是否包含有效的十六进制字符串
报文长度不足（至少包含帧头和帧尾）	报文字节数小于2（无法包含帧头和帧尾）	确认报文是否完整
帧头或帧尾不正确（应为0xFF）	报文首尾不是0xFF	检查报文是否符合协议帧结构
十六进制字符串长度必须为偶数	输入的十六进制字符串长度为奇数	补充或修正十六进制字符，确保长度为偶数
报文解析失败（格式不符合协议规范）	报文字段长度或格式不符合协议	对照协议检查报文各字段是否完整、格式正确
非法月份: 13 (范围: 1-12)	日期不对	检查日期值是否合法

注意事项

1. 报文必须包含完整的帧结构（帧头0xFF+内容+帧尾0xFF），否则会验证失败。
2. 输入的十六进制字符串需去除空格、0x等分隔符，仅保留纯字符（如FFA1B2而非0xFF 0xA1 0xB2）。
3. 定位数据中的经纬度、速度等多字节字段按小端序解析，与协议保持一致。
4. 终端编号和设备类型编码为非压缩BCD编码，解析后会自动去除前补的0xA。