ICS35.020 CCSL78 33 浙江省地方标准 DB33/T1417—2025 食品安全追溯信息系统接口技术导则 Interfacetechnicalspecificationoffoodsafetytraceability informationsystem 2025-01-22发布 2025-02-22实施 浙江省市场监督管理局  发布DB33/T1417—2025 I前言 本标准按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定 起草。 请注意本标准的某些内容可能涉及专利。本标准的发布机构不承担识别专利的责任。 本标准由浙江省市场监督管理局提出、归口并组织实施。 本标准起草单位：湖州市市场监督管理局、浙江省质量科学研究院、绍兴市能源检测院、浙江方圆 检测集团股份有限公司、江山市市场监督管理局、德清县市场监督管理局、嘉兴市市场监督管理局、遂 昌县市场监督管理局、浙江省市场监督管理数字传媒中心、苍南县市场监督管理局、政采云有限公司、 阿里云计算有限公司、杭州农副产品物流网络科技有限公司、杭州半云科技有限公司、杭州联华华商集 团有限公司、衢州市衢江区检验检测中心、嘉兴聚水潭智能科技有限公司。 本标准主要起草人：闻雪娅、郭锐、程璐璐、潘凯凌、姚璇、邱勤丽、杨春、徐超、赵江涛、陈斌、 高壮飞、潘凌骏、杨清潭、崔芳芳、郑剑、杜志才、温建东、过李辉、黄冠、陶炜、李博、焦站静、万 家武、李洋、徐翔、谢晓东、周肖君、王美蓉、沈仙兰、张雪婷、郝禾琼、曹张华。DB33/T1417—2025 1食品安全追溯信息系统接口技术导则 1范围 本标准规定了食品安全追溯信息系统的总体要求、接口类型、管理要求、接口报文、安全要求、接 口应用、接口说明文档。 本标准适用于食品安全追溯信息系统接口的设计和管理。 2规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本标准必不可少的条款。其中，注日期的引用文件， 仅该日期对应的版本适用于本标准；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本 标准。 GB/T7408.1日期和时间信息交换表示法第一部分：基本原则 GB/T35274信息安全技术大数据服务安全能力要求 GB/T38155重要产品追溯追溯术语 IETFRFC2818TLS上的HTTP(HTTPoverTLS) IETFRFC3548Base16、Base32、Base64数据编码（TheBase16,Base32,andBase64DataEncodings） IETFRFC3629UTF-8，ISO10646转换格式（UTF-8,atransformationformatofISO10646） IETFRFC4627JSON格式定义(Theapplication/jsonMediaTypeforJavaScriptObjectNotation) 3术语和定义 GB/T38155界定的术语和定义适用于本标准。 4总体要求 食品安全追溯信息系统接口与通过服务调用所需的信息，应符合以下要求： ——底层承载协议应符合IETFRFC2818的规定； ——字符集应符合IETFRFC3629的规定； ——日期类型应符合GB/T7408.1的规定； ——图片、文件转换为字符串应符合IETFRFC3548的规定； ——接口响应应符合IETFRFC4627的规定； ——应建立接口日志记录，能识别数据异常和追踪交换数据情况； ——发生错误时，接口应把详细的错误代码和错误信息返回给接口使用方。 5接口类型 食品安全追溯信息系统的数据接口包括数据查询接口、数据修改接口、数据增加接口和数据删除接 口，供食品和食用农产品生产经营者及第三方追溯系统使用。 ——数据查询接口：用于数据的查询或下载操作。DB33/T1417—2025 2——数据修改接口：用于数据的修改操作。 ——数据增加接口：用于数据的上报和导入操作，示例见附录A。 ——数据删除数据：用于数据的删除操作。 6管理要求 食品安全追溯信息系统接口的管理要求包括接口测试、申请、激活、应用、维护等方面。 ——接口测试：用户应在申请接口前获取测试包完成接口测试。测试包应包括安全SDK，测试接口， 测试密钥等。 ——接口申请：完成接口测试后，用户向食品安全追溯信息系统管理员提出接口申请，包括接口 名称、功能描述、接口权限、使用目的等信息。 ——接口激活：食品安全追溯信息系统根据用户信息进行审核，分配企业密钥，进行激活操作。 ——接口应用：完成接口激活后，用户可根据需求开展接口应用，接口应用包括企业对接、第三 方系统对接、物联设备对接。 ——接口维护：食品安全追溯信息系统管理员负责对已发布的接口进行维护和监控，及时处理接 口相关的问题和漏洞。 7接口报文 请求报文 食品安全追溯信息系统接口的请求报文由请求头和请求体组成，采用POST方式发送。不同接口具有 统一的请求头，请求头的字段及其描述应符合表1的规定。请求体的参数格式见表2，根据不同接口功能， 其请求体参数不同。 注：POST是HTTP协议的一种请求方式。 表1请求头格式 参数名 数据类型 最大长度是否必填 参数描述 appKey string 128 是 应用序号，追溯平台提供 appMessageId string 128 是 消息流水号 nonce string 4 是 4位随机数 signature string 256 是 签名值 timestamp long - 是 调用当前时间戳,基于UTC时间 version string 16 是 接口版本号 表2请求体参数格式 参数名 数据类型 最大长度 是否必填 描述 给出参数名 所属数据类型 给出最大字长度 是/否对参数的描述及补充说明DB33/T1417—2025 3 响应报文 食品安全追溯信息系统接口的响应报文由响应头和响应体组成。不同接口具有统一的响应头，响应 头的字段及其描述应符合表3的规定。响应体的参数格式见表4，根据不同接口功能，其响应体不同。 表3响应头格式 参数名 数据类型 最大长度是否必填 参数描述 appKey string 128 是 应用序号，追溯平台提供 appMessageId string 128 是 消息流水号 nonce string 4 是 4位随机数 resultCode string 64 是 响应码 resultMessage string 500 是 响应信息 signature string 256 是 签名值 timestamp long - 是 调用当前时间戳,基于UTC时间 表4响应体参数格式 参数名 数据类型 最大长度 描述 给出参数名 所属数据类型 给出最大字长度 对参数的描述及补充说明 8安全要求 食品安全追溯信息系统接口的安全要求应符合以下基本要求： ——应符合GB/T35274的安全能力要求； ——应提供安全传输SDK，SDK初始化所需的参数由食品安全追溯信息系统初始分配； ——第三方请求发送到食品安全追溯信息系统时，平台应进行IP白名单、签名、防重放、调用次 数、调用时间段、接口属性的校验； ——安全算法应分为签名和加密两步骤。签名算法对请求头和请求参数进行SHA256签名后转HEX； 加密采用AES/CBC算法，加密后数据采用BASE64进行编码。 请求体加密规则包括： ——加密算法：AES/CBC； ——密钥：128位； ——初始向量：nonce格式化为16位（不足前面补0）； ——加密前数据：待加密文本UTF-8的字节数组； ——加密数据编码方式：BASE64。 响应体解密规则包括： ——加密数据：通过BASE64解码后获得； ——解密算法：AES/CBC； ——密钥：128位； ——初始向量：nonce格式化为16位（不足前面补0）； ——解密后数据：解密后字节数组转换成UTF-8文本。DB33/T1417—2025 49接口应用 食品和食用农产品生产经营者对接 9.1.1生产者 生产者对接信息宜包括食品或食用农产品的名称、规格、数量、生产日期或者生产批号、保质期、 质量合格证明，以及生产者名称、统一社会信息代码等追溯信息，涉及物联设备对接参照9.3。 9.1.2批发经营者 批发经营者对接信息宜包括食品或食用农产品的名称、规格、数量、质量合格证明、进货信息，以 及批发经营者信息、供应商信息、采购商信息等追溯信息。 9.1.3零售经营者 零售经营者对接信息宜包括食品或食用农产品的名称、规格、数量、质量合格证明，以及零售经营 者信息、供应商信息等追溯信息。 9.1.4餐饮服务提供者 餐饮服务提供者对接信息宜包括食品或食用农产品基本信息、采购信息以及餐饮服务提供者信息等 追溯信息。 第三方系统对接 第三方系统对接信息宜包括系统名称、系统运营商信息、产品信息、追溯信息等。 物联设备对接 物联数据宜包括企业基本信息、设备基本信息、设备区域信息、设备传感信息等。 10接口说明文档 食品安全追溯信息系统接口设计开发完成后，应提供详细的接口说明文档。接口说明文档宜明确服 务接口在调用协议、数据格式、字符集、服务安全等方面的基本约定，注明管理工作或技术支持服务联 系人。针对每个服务接口,提供功能说明、调用地址、请求参数、返回参数、报文示例等信息。 A