一物一码数据对接：三层、字段、时序与异常
核心结论
对接失败，八成不是接口不通，是字段口径、时序、异常处理没约定。三层写清楚，联调一周内能跑完。
一、三层对接
| 层 | 对接什么 | 谁负责 |
|---|---|---|
| 设备层 | 相机、光源、触发、工控机 | 设备方 |
| 系统层 | 采集软件 ↔ ERP/MES/WMS | 软件方 + 甲方 IT |
| 平台层 | 追溯数据 ↔ 监管/客户平台 | 软件方 |
三层里最容易漏的是系统层：设备能读、平台能传，中间业务系统对不上。
二、字段口径先对齐
对接前先做一张字段对照表，五列：业务含义 / 本地字段 / 对方字段 / 类型长度 / 是否必填。
三个高频冲突：
- 时间：本地是采集时间还是生产时间？时区是不是都在 +08:00？
- 批次：批号规则两边不同，谁转换？
- 数量：箱内件数是固定还是可变？尾箱怎么表示？
三、时序与幂等
对接最怕两件事：重复上传、乱序到达。约定三条：
- 每条记录带唯一业务号，对方按业务号幂等
- 允许乱序，但关联关系以“最后到达的完整记录”为准
- 补传要带原始采集时间，不是补传时间
四、异常怎么处理
| 异常 | 处理 | 谁负责 |
|---|---|---|
| 网络中断 | 本地缓存，恢复后按序补传 | 软件方 |
| 对方接口报错 | 记录原始报文，重试三次后进人工队列 | 软件方 + 甲方 IT |
| 字段缺失 | 拒绝入库，返回明确错误码 | 对方系统 |
| 数据不一致 | 每日对账，输出差异清单 | 双方 |
五、联调五步
- 打通连通性（能调用、能返回）
- 单条推送成功（一条记录跑通）
- 批量推送（100 条，看顺序与幂等）
- 断网演练（30 分钟后补传）
- 对账（条数、关键字段全对）
五步走完再上线，别把联调留到验收前一周。
六、对接检查单（联调前逐项打勾）
- □ 对方接口文档（含错误码表）已拿到
- □ 测试环境与账号已开通
- □ 字段对照表双方签字确认
- □ 唯一业务号规则已约定
- □ 补传策略（缓存时长、重试次数）已约定
- □ 对账频率与差异处理人已确定
六项齐了再开始联调；少一项，联调就会变成“边聊边改”。
七、三句话判断对接会不会翻车
- “接口的事后面再说”——现在不说，验收前两周一定慌
- “字段你们看着办”——两边各看着办，最后对不上
- “先上再补文档”——补文档的人，半年后已经不在了
三句话出现任意一句，就把对接提上当前周的议程。对接这件事，早一周谈，少两周返工。
验证说明：本文的判断项均可现场核对（看系统架构、看交付清单、看合同条款）。文中涉及的行业数据为公开资料整理，具体数字以最新公开口径为准；我们不在此评价任何具体服务商。
常见问题
对接一般要多久？
字段对齐 3 天、联调 1 周、对账 2 天。前提是对方的接口文档与测试环境提前给到。
对方没有接口怎么办？
常见替代：中间库、文件交换、定时导出导入。速度慢一些，但能跑通。
对接费用谁出？
合同里写清。常见做法是“甲方系统侧由甲方负责，平台与设备侧由乙方负责”。
数据对不上怎么查？
先分三层：设备有没有读、软件有没有存、平台有没有收。逐层看日志，别一起猜。