资讯中心

一物一码接口字段如何映射?主键、幂等与失败回执联调清单

一物一码接口字段映射,应把每个字段的含义、来源、格式、可变条件与失败处理写清楚。产品名称相同不代表身份相同,请求发出也不代表业务已经完成。潜利建议在联调前建立字段与事件清单,用能够人工复核的任务样本逐项验证。

接口主键与事件回传技术示意

产品主键和展示名称分别管理

产品编码用于识别对象,名称用于阅读。两个系统使用不同编码时,应维护受控映射并保存有效范围,不宜按名称相似直接匹配。前导零、大小写和批号字符要按约定保留,避免把字符编号当成数字处理。

单位也需要明确。ERP一箱、现场一瓶、仓库一托的数量不能直接相加。箱规发生变化,应根据任务及版本计算,不能用今天的箱规解释所有历史单据。

最小字段清单怎样写?

字段含义示例校验重点
businessId原系统业务单号可追到实际任务
eventId本次业务事件身份重试沿用原编号
productCode受控产品主键映射有效且唯一
eventTime现场实际发生时间与接收时间分开
version当前业务版本防止旧状态覆盖

这些名称是技术示例,不是潜利或其他平台固定接口。实际开发应列出必填、允许为空、长度、字符集、枚举及责任系统。对于包装关系,还需说明绑定、拆分和更正事件如何表达。

重试为何需要保持同一身份?

网络超时可能发生在服务端已经处理后。若客户端每次重试都创建新事件,可能重复入库或重复绑定。可使用稳定事件编号识别同一请求,并检查相同编号的内容是否一致。内容冲突应进入异常处理,不能无条件当作成功。

并发修改也需要核对当前业务版本。读取箱内十件后,另一工位已经拆走两件,原请求不能继续按旧清单覆盖。应返回明确冲突,让人员重新查询和复核。

错误回执需要分几类?

区分网络不可达、权限不足、字段错误、对象不存在、状态冲突与结果未知。临时网络问题可按策略重试,业务校验失败应修复原因后再处理。回执应包含请求身份、处理状态及可查询线索,公开页面不显示内部凭据与敏感日志。

错误清单还需明确人工职责。技术人员可以检查传输格式,但不能代替仓库确认实物。补录与更正由授权岗位操作,并保存前后关系。

模拟联调:回执丢失后的重复提交

以下为模拟测试。仓库出库事件已处理,但返回中断。重试后应查到原处理结果,库存只变化一次。随后再用相同事件编号提交不同数量,系统应提示冲突,而不是静默覆盖。最后对照原单据、库存与事件记录,确认一致。

测试条件与交付材料

固定测试数据、系统版本、时区与样本数量,分别演练重复提交、字段缺失、主键未知、取消单据和断网恢复。测试结果注明预期、实际、证据与处理人,不用“接口正常”一句话概括全部场景。

可以先参考系统职责与实施总览确定业务边界,再结合生产赋码管理系统确认现场回传数据。

常见问题

原系统只有文件导出还能对接吗?

可以评估文件或中间表方式,但仍需唯一身份、导入校验和结果对账。

重发失败记录可以直接改编号吗?

不宜通过改编号绕过错误,应先判断是否同一业务事件。

时间字段全部用服务器时间可以吗?

应区分现场发生时间与接收时间,尤其关注离线补传。

需要制定字段与异常联调清单,可联系潜利科技:400-600-9896。