平台对接前要备好什么：协议、字段和一份联调清单

设备能上线，不等于平台读得懂。本文列清对接前要拿到的六样东西、三类字段怎么对、一轮联调怎么验收，站内没公开的逐项写明该找谁确认。

设备能上线，不等于平台读得懂。对接前要拿齐六样东西：服务器地址与端口、协议与版本、APN 与卡、设备编号规则、字段字典、告警与回执口径。缺一样，联调会就会开成两边互相猜：这边说数据发了，那边说没收到，谁也拿不出一条能对上的记录。

早些年一个平台配一批设备，IP 和端口写在纸条上贴显示器边框，装完打个电话说「通了」就算完。后来车队系统、监管平台、客户自己的业务系统都要接，同一条位置数据得被几家按各自的字段读，时间带不带时区、经纬度谁在前、速度用哪种单位，任何一处不齐，一整天的轨迹就对不上。到今天对接更像两个班组交接台账，得有一张双方逐项打勾的清单。老会计带新人交接账本，头一天不教记账，先让新人把科目名称、计量单位、借贷方向三栏抄齐，说科目对不上，金额算得再准也合不了账。设备与平台之间，那三栏就是协议、字段和单位。

一、对接前要拿到的六样东西

项目	谁提供	站内是否公开	拿到后怎么验
服务器地址与端口	平台方	站内公开了参数写法，地址端口本身是项目值	用短信配置页的公开格式写入，再按服务器地址与端口配置把设备侧配置读回来逐字对
协议与版本	平台方与商务共同确认	TCP、UDP、MQTT、JT808 的分工站内讲过；TM800 产品页标注 JT/T 808-2019	让双方把协议名称、版本号、是否扩展消息写进同一份文档
APN 与物联网卡	运营商 / 平台方	APN 与物联网卡配置讲了换卡后要做的检查	卡装好后看设备能否附着上网，别把卡的问题当成协议问题
设备编号规则	商务与平台方	站内未公开编号与 IMEI 映射规则	拿一台样机，核对平台登记号与机身标识是否一致
字段字典	平台方	站内未公开，需向商务确认	见下节三类字段，逐项对名称、类型、单位、枚举
告警与回执口径	平台方与商务	站内未公开返回码表与告警枚举，需向商务确认	联调时各触发一次，把平台侧记录截图存档

六样里，只有前两样的「写法」能在站内找到公开资料，具体值都是项目自带的。把它们做成一张表，会前发给设备方、平台方、安装方，谁提供、谁确认、什么时候回，写在每一行后面。

二、三类字段怎么对

类别	常见项	容易错在哪	验收动作
身份类	设备号 / IMEI、车牌、SIM 卡号	平台登记号与机身标识不是同一个；换卡后没更新映射	取一台样机，把三处标识抄在一行里让双方签字
位置类	时间、经度、纬度、坐标系、速度、方向、定位方式、里程	时间戳时区、经纬度顺序、坐标系混用、速度单位不一致、补位点没有标记	同一条上报，在设备侧与平台侧各导一份，逐字段并排比
状态与告警类	点火熄火、外电状态、电量、报警位、盲区补传标记	报警位枚举各叫各的；掉电告警被当成离线；补传数据没有去重规则	每类触发一次，记录触发时刻与平台收到的字段值

字段名、单位与枚举值一律以平台接口文档为准，站内页面没有公布这张字段表，需向商务索取。这里给的是「要对齐哪几类」，不是替平台定义字段。产品页上能查到的通道信息可以作为旁证，例如 TM820 技术规格写 TCP/IP、UDP/IP，TM800 产品页标注部标标准，但通道对得上只是起点。

一个常被忽略的地方是补传。设备进了盲区会先存位置，恢复网络后再补发；平台若按接收时间排序，轨迹就会突然倒回去一段。上报间隔、补传标记、去重规则要一起定，上报间隔怎么定里讲的续航、流量与轨迹精度三角，在联调阶段同样适用。数据量大起来之后，这类约定比调参数更费时间。

三、一轮联调走四步

步骤	设备侧动作	平台侧要看什么	留下的证据
写参数	按公开格式写入服务器地址、端口、APN、上报间隔	参数是否被接受，设备是否在线	写入记录、参数回读截图
发位置	样机在开阔处静置并移动一小段	收到一条位置，时间、经纬度、定位方式齐全	设备侧与平台侧同一条记录并排表
触发告警	在安全且告知车主的前提下断开外电，或按项目约定触发一次报警	告警字段与枚举值是否对上，有没有被当成离线	告警时间、字段截图、双方确认人
断网补传与回读	短暂断网后恢复，再用站内公开的查询指令把配置读回来	补传点有没有标记、顺序对不对、配置与写入值是否一致	断网起止时间、补传记录、回读结果

四步都用手上一台样机做完，再谈批量。CXIP、CXPI 这类查询写法在站内短信配置页是公开的，用来把设备侧配置读回来核对很顺手；至于某型号支持哪几条、固件版本范围如何，站内没有型号与指令的对应矩阵，需向商务确认后再写进操作单，别照着别款机器抄。

四、站内没公开的，别在会上猜

联调会里容易出事的是临时补一句「应该支持吧」。下列内容站内均未公开，也没有实测记录可依：型号与指令支持矩阵、返回码表、短信指令是否有密码或白名单、平台字段字典与告警枚举、回执样例、平台兼容清单、固件版本范围。这些要由商务或研发给书面版本，拿不到的项目在清单里写「需向商务确认」，定责任人和回复日期。涉及设备操作的指令类内容只写研发实测过、标了适用范围的那部分；远程调试、油电控制这类高风险操作不进公开页面，也不在联调清单里展开。

五、如果你在筹备下周的联调会

会前把开头那张六样东西的表发出去，每行留「提供方 / 确认人 / 回复日期」三栏；把第二节的三类字段做成空白对照表，现场逐格填；把第三节四步排进会议议程，每步指定谁在设备侧动手、谁在平台侧截图。散会时收齐三样东西：一份双方签过字的字段对照表、一组四步联调的原始记录、一张写着「需向商务确认」项目和责任人的待办清单。资料缺口可以通过联络方式正式提出，口头答应的那几项也请对方补一封邮件；批量装机排在邮件之后，比排在一句「应该没问题」后面稳当得多。