冷链物流信息系统数据接口规范

冷链物流信息系统数据接口规范1.总则1.1编制目的随着冷链物流行业的数字化转型加速，供应链上下游企业对于物流信息的实时性、准确性和可追溯性提出了极高的要求。本规范旨在统一冷链物流信息系统中各子系统（如仓储管理系统WMS、运输管理系统TMS、温湿度监控系统、订单管理系统OMS及第三方监管平台）之间的数据交互标准。通过制定标准化的数据接口规范，消除信息孤岛，确保温控数据、货物状态及物流轨迹在传输过程中的完整性与安全性，为医药、生鲜食品等对温度敏感的行业提供可靠的技术支撑，同时满足国家关于药品经营质量管理规范（GSP）及食品安全法的相关合规性要求。1.2适用范围本规范适用于参与冷链物流全链条的所有相关方，包括但不限于：冷链物流服务提供商、货主企业、温湿度设备供应商、软件系统集成商及政府监管平台。凡涉及冷链物流业务数据交换、系统对接、信息共享等场景，均需严格遵循本规范定义的数据格式、通信协议及安全机制。1.3编制原则本规范的制定遵循以下核心原则：一致性原则：所有接口的数据结构、命名规则及编码体系必须保持全局一致，避免因定义歧义导致的数据解析错误。扩展性原则：预留标准扩展字段，以适应未来业务创新及特殊品类（如生物制品、危化品）的个性化需求。安全性原则：数据传输过程必须经过加密处理，并具备严格的身份认证与权限校验机制，防止商业数据泄露及恶意篡改。高效性原则：接口设计需考虑高并发场景下的性能表现，支持批量数据传输及增量同步机制，降低系统间交互延迟。2.通信协议与安全机制2.1通信协议规范所有数据接口必须基于HTTP/HTTPS协议进行交互。鉴于冷链数据的敏感性，严禁使用未加密的HTTP协议进行数据传输。推荐使用RESTful架构风格，利用HTTP的标准动词（GET、POST、PUT、DELETE）来描述对资源的操作。传输编码：统一采用UTF-8字符集，确保多语言及特殊符号的正确显示。数据格式：请求体与响应体统一采用JSON（JavaScriptObjectNotation）格式。JSON具有轻量级、解析速度快的特点，适合移动端及物联网设备的数据交互。压缩机制：当单次交互数据量超过50KB时，建议在HTTPHeader中添加“Content-Encoding:gzip”，对传输内容进行压缩，以节省网络带宽并提升传输效率。2.2身份认证与鉴权为保证接口调用的安全性，系统间交互必须采用OAuth2.0标准协议或APIKey+签名机制。签名算法：采用HMAC-SHA256算法进行请求签名。调用方需将请求参数按字母顺序排序，拼接成字符串，并使用双方约定的SecretKey进行哈希运算，生成的签名值置于HTTPHeader的“X-Signature”字段中。时间戳校验：为防止重放攻击，每个请求必须包含“X-Timestamp”字段，服务端接收请求时需校验时间戳与当前服务器时间的差值，允许的最大误差不超过300秒（5分钟）。访问令牌：对于需要用户身份上下文的接口，必须携带有效的AccessToken。Token有效期由服务端设定，过期后需通过RefreshToken进行刷新。2.3异常处理机制接口调用过程中可能出现网络抖动或业务逻辑错误，需建立完善的错误码体系。HTTP状态码：利用标准HTTP状态码标识请求层级。200OK：请求成功。400BadRequest：请求参数错误或缺失。401Unauthorized：认证失败，Token无效或过期。403Forbidden：无权限访问该资源。404NotFound：请求的资源不存在。500InternalServerError：服务端内部错误。业务错误码：在响应体的JSON中通过“errorCode”和“errorMsg”字段返回具体的业务错误信息，如“TEMP_OUT_OF_RANGE”（温度超限）、“ORDER_NOT_FOUND”（订单不存在）等。3.数据通用规范3.1公共数据结构为减少重复定义，本规范设定了所有接口通用的基础数据结构。响应包装结构：所有接口的返回数据均需包装在统一的结构中，包含状态、时间戳及业务数据。```json{"traceId":"string",//全局唯一追踪ID，用于链路追踪"timestamp":1640995200000,//服务端响应时间戳（毫秒）"code":"string",//业务响应码，"0000"表示成功"message":"string",//响应消息描述"data":object//具体的业务数据对象}```分页参数结构：用于列表类查询接口，避免一次性返回过多数据。```json{"pageNum":1,//页码，从1开始"pageSize":50,//每页条数，最大值不超过100"totalCount":1200//总记录数（仅返回体包含）}```3.2基础数据字典为确保数据语义的标准化，以下枚举值在所有接口中通用。温度单位：CELSIUS：摄氏度（℃）FAHRENHEIT：华氏度（℉）数据来源类型：MANUAL：人工录入DEVICE：设备自动采集SYSTEM：系统计算接口类型：INBOUND：入库OUTBOUND：出库TRANSFER：移库TRANSPORT：在途运输4.基础数据管理接口基础数据管理是冷链物流信息化的基石，涵盖客户、物料、冷库及设备档案的同步。4.1冷库档案同步接口描述：用于同步货主或物流商的冷库基础信息，包括库房编码、名称、地理位置、库区类型（冷冻、冷藏、恒温）等。这是进行温控策略匹配的基础。请求参数说明：参数名类型必填描述示例值warehouseCodeString是冷库唯一编码，全局唯一WH-BJ-001warehouseNameString是冷库名称北京大兴生鲜一号库warehouseTypeString是库房类型：FROZEN(-18℃),CHILL(0-4℃)FROZENaddressString是详细地址北京市大兴区xx路xx号longitudeDouble是经度，用于地图定位116.33latitudeDouble是纬度39.90capacityDouble否设计库容（吨）5000.00statusInteger是状态：1-启用，0-停用14.2物料温控属性同步接口描述：同步SKU或物料级别的温控要求。不同品类的生鲜或药品对温度的要求截然不同，此接口用于下发温控标准，指导仓储与运输环节的操作。请求参数说明：参数名类型必填描述示例值值skuCodeString是物料编码SKU-2023001skuNameString是物料名称进口冷冻牛肉categoryString是类别：MEDICINE/FOODFOODminTempDouble是要求最低温度（℃）-22.0maxTempDouble是要求最高温度（℃）-18.0alertThresholdInteger否超限报警阈值（分钟）15isHazardousBoolean否是否危化品false5.业务订单协同接口业务订单是驱动冷链物流作业的核心指令，包括入库单、出库单及运输单据的交互。5.1冷链运输订单创建接口描述：由货主系统向物流TMS系统下发运输订单。该接口需明确包含提货、卸货信息及全程温控要求。请求参数详细定义：参数名类型必填描述示例值orderNoString是运输订单号T20231025001sourceOrderNoString是来源单号（销售单号）SO-998877businessTypeString是业务类型：DIRECT/TRANSFER/DISTRIBUTIONDIRECTshipperInfoObject是发货人信息（姓名、电话、地址）{...}consigneeInfoObject是收货人信息{...}cargoListArray是货物明细列表[...]requireTempMinDouble是运输要求最低温-25.0requireTempMaxDouble是运输要求最高温-15.0prePickupTimeString是预约提货时间2023-10-2609:00:00preArriveTimeString是预约到达时间2023-10-2714:00:00specialRequirementString否特殊要求（如：严禁挤压）需冷藏车运输货物明细结构（cargoList）：参数名类型必填描述skuCodeString是货物编码quantityDecimal是数量weightDecimal是重量（KG）volumeDecimal是体积（CBM）batchNoString否批次号（医药必填）productionDateString否生产日期expiryDateString否有效期5.2订单状态回调接口描述：物流系统执行作业过程中，需将关键节点状态实时回传给货主或监管平台，确保全程可视。状态枚举定义：CREATED：订单已创建ASSIGNED：已调度PICKED_UP：已提货IN_TRANSIT：运输中DELIVERED：已签收CANCELLED：已取消EXCEPTION：异常回调数据体示例：```json{"orderNo":"T20231025001","status":"IN_TRANSIT","location":{"longitude":116.40,"latitude":39.91,"address":"京沪高速k120处"},"occurTime":"2023-10-2615:30:00","remark":"车辆运行正常，温度达标"}```6.温湿度监控数据接口温湿度数据是冷链物流的灵魂，该部分规范重点解决IoT设备数据的高频上报与解析问题。6.1设备绑定与解绑接口描述：将温湿度记录仪或车载传感器与具体的运单或库房进行绑定，确立数据归属关系。请求参数说明：参数名类型必填描述示例值deviceIdString是设备唯一标识码（IMEI或设备ID）DEV-882910deviceTypeString是设备类型：PROBE/HANDHELD/VEHICLEPROBEtargetIdString是关联目标ID（运单号或库位号）T20231025001bindTypeString是绑定类型：ORDER/WAREHOUSEORDERbindTimeString是绑定时间2023-10-2608:00:006.2实时温湿度数据上传接口描述：由IoT设备或网关通过MQTT/HTTP协议将采集到的温湿度数据上传至平台。考虑到设备网络环境可能不稳定，设计上需支持断点续传和批量补传。批量上传数据结构：参数名类型必填描述示例值deviceIdString是设备IDDEV-882910uploadTimeString是上报批次时间戳1698300000000dataTypeString是数据类型：REALTIME/HISTORYREALTIMEdataListArray是温湿度记录点列表[...]数据点结构（dataList）：参数名类型必填描述备注recordTimeLong是记录时间戳（毫秒）1698300001000temperatureDouble是温度值（℃）-19.5humidityDouble否湿度值（%RH）65.0batteryInteger否剩余电量（%）85signalInteger否信号强度（dBm）-606.3温度数据异常报警接口描述：当监测数据超出预设阈值（如冷冻品高于-18℃）时，系统需立即触发报警接口，推送告警信息至相关责任人。报警等级定义：CRITICAL：严重，温度严重超标且持续时间长MAJOR：重要，温度超标MINOR：次要，设备离线或电量低报警推送体：```json{"alarmId":"ALM-20231026-001","deviceId":"DEV-882910","orderNo":"T20231025001","alarmLevel":"MAJOR","alarmType":"TEMP_HIGH","currentValue":-12.5,"threshold":-18.0,"duration":300,//持续时间（秒）"alarmTime":"2023-10-2610:05:00","location":"河南省郑州市服务区"}```7.数据追溯与合规性接口7.1电子运单与温控数据关联查询接口描述：用于监管端或客户端查询特定订单的完整冷链轨迹链路，实现“一单到底、全程可溯”。查询参数：orderNo：订单号startTime/endTime：查询时间范围返回内容需包含：订单基础信息车辆轨迹轨迹（GPS点集）绑定的设备列表按时间轴排序的温湿度曲线数据发生的所有异常事件记录7.2冷链验证报告生成接口描述：依据GSP要求，系统需能自动生成并导出冷链运输温度验证报告。此接口接收生成指令，返回PDF报告的下载地址或Base64编码流。报告内容规范要求：封面信息：运单号、发货人、收货人、货物信息、运输车辆信息。设备信息：记录仪型号、编号、校准有效期。温度数据：完整的温度曲线图、最高温、最低温、平均温。结论判定：依据预设规则，自动判定该批次运输是否合格（合格/不合格）。签章信息：需支持电子签章或CA认证，确保报告法律效力。8.系统运维与性能指标8.1接口性能要求为保证高并发下的系统稳定性，所有对外服务接口需满足以下性能指标：响应时间：简单查询接口（GET）：<200ms业务操作接口（POST/PUT）：<500ms复杂报表及大数据量导出：<3s并发能力：系统应支持至少1000TPS（每秒事务处理量）的峰值并发调用。在峰值负载下，CPU利用率不应超过80%，JVM内存占用率不应超过85%。可用性：服务年度可用性（SLA）需达到99.9%以上，即全年非计划停机时间不得超过8.76小时。8.2日志与审计接口调用日志：服务端必须记录每一次接口调用的详细日志，包括：调用方IP、请求参数、响应结果、耗时、异常堆栈。日志保留周期至少为180天，以满足审计追溯需求。数据变更审计：对于关键业务数据的修改（如修改温度阈值、删除订单），必须记录操作人、操作时间、修改前值、修改后值，确保数据变更可追溯。8.3版本管理策略接口版本控制：在URL路径中包含版本号，例如：`/api/v1/order/create`。版本迭代原则：新增字段：向后兼容，不影响旧版本客户端。修改字段：废弃旧字段，新增字段，维护过渡期，过渡期后下线旧版本。废弃通知：接口废弃前需提前至少3个月通过公告、邮件等方式通知所有对接方。9.数据质量保障与异常处理流程9.1数据校验规则接口提供方必须对传入的数据进行严格校验，拒绝脏数据。非空校验：所有标记为“必填”的字段，若为Null或空字符串，直接返回400错误。格式校验：日期时间必须符合ISO8601标准（YYYY-MM-DDTHH:mm:ss.SSSZ）。经纬度格式：经度范围-180至180，纬度范围-90至90。数值范围：温度值建议在-50℃至100℃之间，超出范围视为异常数据。业务逻辑校验：出库数量不能大于库存数量。订单创建后，状态流转必须符合生命周期定义（如：不允许从“已创建”直接跳转到“已签收”）。9.2重试与幂等性网络波动可能导致请求超时或丢包，调用方应实现自动重试机制。重试策略：推荐采用指数退避算法，重试间隔为1s,2s,4s,