DB31 T 1110.3-2025 食品和食用农产品信息追溯 第3部分：数据接口规范.pdf

1、 ICS 35.040.99 CCS L 78 31 上海市地方标准 DB 31/T 1110.32025 代替 DB 31/T 1110.32018 食品和食用农产品信息追溯 第 3 部分：数据接口规范 Full chain traceability of food and edible agricultural products informationPart 3：Data interface 2025-12-23 发布 2026-04-01 实施 上海市市场监督管理局 发 布 DB 31/T 1110.32025 I 目次 前言.II 引言.III 1 范围.1 2 规范性引用文件.1

2、3 术语和定义.1 4 符号和缩略语.2 5 技术要求.2 5.1 基本要求.2 5.2 接口格式定义.2 5.3 数据类型.2 6 服务功能类型.3 7 接口安全.4 7.1 安全认证.4 7.2 数字证书.4 7.3 数字令牌.4 附录 A（规范性）食品和食用农产品追溯系统接口服务功能说明.5 DB 31/T 1110.32025 II 前言 本文件按照GB/T 1.12020标准化工作导则 第1部分：标准化文件的结构和起草规则的规定起草。本文件是DB 31/T 1110食品和食用农产品信息追溯的第3部分。DB31/T 1110已经发布了以下部分：第 1 部分：追溯编码与标识规范；第 2

3、部分：数据元规范；第 3 部分：数据接口规范。本文件代替DB31/T 1110.32018食品和食用农产品信息追溯 第3部分：数据接口，与DB31/T 1110.32018相比，除结构调整和编辑性改动外，主要技术变化如下：a)更改了“技术要求”一章(见第 5 章 5.1、5.2、5.3，2018 年版的第 5 章)；b)删除了“数据接口”相关要求(见 2018 年版的第 6 章)；c)增加了“服务功能类型”一章(见第 6 章)，增加了“食品和食用农产品追溯系统接口服务功能说明”(见附录 A)。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。本文件由上海市食品药品安

4、全委员会办公室提出。本文件由上海市市场监督管理局归口并组织实施。本文件起草单位：上海仪电溯源科技有限公司、上海市大数据中心、上海市农业科学院、中国物品编码中心、上海市质量和标准化研究院、上海市农产品质量安全中心、上海前石科技有限公司、上海海关机电产品检测技术中心。本文件主要起草人：王献礼、彭海涛、蔡丽华、张向飞、王轶、方海宾、倪孟锴、李硕、朱丽华、陈旭、祁兵、徐振、齐相峰、陈可、卢宁、张轶荦、吴新敏、夏磊、苏航、钱进、李文婷、王佳琦。本文件及其所代替文件的历次版本发布情况为：2018 年首次发布为 DB31/T 1110.32018；本次为第一次修订。DB 31/T 1110.32025 II

5、I 引言 本文件旨在建立食品和食用农产品信息追溯的基础规范，明确追溯编码、数据元及接口标准，适用于追溯信息的标识、采集与交换。DB 31/T 1110 由以下三个部分组成：第1部分：追溯编码与标识规范，用于规定追溯码的结构、标识方式及符号要求；第2部分：数据元规范，用于规定追溯相关信息的数据分类、结构及格式要求；第3部分：数据接口规范，用于规定追溯信息交换接口的技术要求与安全机制。本文件梳理了上海市食品和食用农产品信息追溯系统的信息交换、共享、传输和认证，确保数据的互操作性、一致性和安全性。DB 31/T 1110.32025 1 食品和食用农产品信息追溯 第 3 部分：数据接口规范 1 范围

6、 本文件规定了上海市食品和食用农产品追溯系统接口的技术要求、服务功能类型和接口安全的要求。本文件适用于上海市食品和食用农产品追溯系统的信息交换、共享、传输和认证的接口实现。2 规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T 7408.1 日期和时间 信息交换表示法 第1部分：基本原则 GB/T 20518 信息安全技术 公钥基础设施 数字证书格式 GB/T 38155 重要产品追溯 追溯术语 DB31/T 1110.1 食品和食用农产

7、品信息追溯 第1部分：追溯编码与标识规范 DB31/T 1110.2 食品和食用农产品信息追溯 第2部分：数据元规范 IETF RFC 2818 TLS上的HTTP(HTTP over TLS)IETF RFC 3548 Base16、Base32、Base64数据编码（The Base16,Base32,and Base64 Data Encodings）IETF RFC 3629 UTF-8，ISO 10646转换格式（UTF-8,a transformation format of ISO 10646）IETF RFC 4627 JSON格式定义(The application/json

8、 media type for javascript object notation)3 术语和定义 GB/T 38155、DB31/T 1110.1、DB31/T 1110.2界定的以及下列术语和定义适用于本文件。3.1 数据接口 data interface 一组用于数据交换的服务。注：包括服务的功能、位置以及通讯的协议、传输格式和认证方法。3.2 数据接口协议 data interface protocol 用来和数据接口（3.1）服务进行通讯的应用层协议。注：其内容包括定义消息的内容、消息类型的语法结构、域所包含的信息的含义，确定通信程序何时发送消息和接收消息的规则。3.3 接口传输规

9、范 interface transmission standard 定义数据源和数据宿之间传送的数据内容的格式和标记语言。3.4 DB 31/T 1110.32025 2 安全认证 security certificate 保证数据传输安全的加密方法和身份认证方法。3.5 数字令牌 digital token 分发给传输方，代表传输方身份及权限的加密字符串。3.6 数字签名 digital signature 附加在数据单元上的一些数据，或是对数据单元所作的密码交换，这种数据或变换允许数据单元接收者确认数据单元的来源和完整性，并防止数据单元被人（例如接收者）伪造。4 符号和缩略语 下列缩略语适

10、用于本文件。CA：数字证书认证机构（Certificate Authority）HTTPS：超文本传输安全协议（HyperText Transfer Protocol over Secure Socket Layer）JSON：JavaScript 对象标记（Java ScriptObject Notation）TLS：传输层安全协议（Transport Layer Security）URL：统一资源定位符（Uniform Resource Locator）UTF-8：一种可变长度字符编码（8-bit Unicode Transformation Format）5 技术要求 5.1 基本要求

11、食品和食用农产品追溯系统的接口应符合下列要求：a)采用符合 IETF RFC 2818 的 HTTPS 协议作为底层承载协议；b)采用符合 IETF RFC 3629 规定的 UTF-8 字符集；c)采用符合 GB/T 7408.1 规定的日期类型；d)采用符合 IETF RFC 3548 规定的 Base64 编码规则将图片、文件二进制字节流转换为字符串；e)接口响应采用 IETF RFC 4627 规定的 JSON 数据格式；f)建立接口日志记录，能识别数据异常或追溯交换数据情况；g)发生错误时，接口将详细的错误代码和错误信息返回给接口使用方，以利于接口使用方进行记录分析和整改。5.2 接

12、口格式定义 接口格式定义包括但不限于：a)接口地址：请求的 URL 地址，一般由域名或 IP、端口号、接口路径组成；b)功能说明：数据接口功能的简要描述；c)参数说明：调用数据接口的输入参数或者输出参数情况；d)请求示例：数据接口的请求参数示例；e)返回示例：数据接口调用正常或异常的报文主体示例；f)接口响应码说明：数据接口的响应状态码。5.3 数据类型 DB 31/T 1110.32025 3 接口支持传输的数据类型应包括：a)字符型，用 String 表示；b)整数型，用 Integer 表示；c)浮点型，用 Float 表示；d)布尔型，用 Boolean 表示；e)日期时间型，用 Da

13、teTime 表示，应符合 GB/T 7408.1 中定义的扩展时间表示法。日期格式为：YYYY-MM-DD，时区为中国北京时间(GMT+8)；时间格式为：YYYY-MM-DDThh:mm:ss，时区为中国北京时间（GMT+8）；根据信息交换中各方的约定，在不会引起日期和时间组合的表示法与本文件定义的其他表示法出现混淆的情况下，字符T可省略；f)时间戳型，用 Timestamp 表示，通过计算从 1970 年 1 月 1 日 0 点至当前时间的毫秒数，并将毫秒数结果作为数字传输；g)文件型，用字符串标识，应采用 data：；base64，的字符串格式进行拼接。其中：表示文件的类型，例如 app

14、lication/pdf；表示文件二进制字节流的 Base64 编码字符串；h)对象型，用 Object 表示，对应 JSON 中的对象符号；i)数组型，用 Array 表示，是一个或多个 JSON 对象符号的集合；j)空，用 NULL 表示。6 服务功能类型 追溯系统接口服务和格式的定义，应符合附录A的规定。追溯系统接口服务功能的示意图见图1，其类型主要包括：a)授权接口，用于进行身份认证和授权访问，可确保安全性和数据隐私；b)上传接口，用于上传追溯数据到追溯系统中；c)查询接口，用于获取追溯数据和信息，可满足不同环节参与者的查询需求。注：图中实线箭头表示接口调用，实线空心箭头表示产品流向。

15、图 1 追溯系统接口服务功能示例图 DB 31/T 1110.32025 4 7 接口安全 7.1 安全认证 食品和食用农产品追溯系统接口应采用数字证书和数字令牌的方式实现安全认证，数字证书的格式应符合GB/T 20518的规定。平台提供密码和证书服务，用于身份认证、证书解析、证书认证、信息的机密性、完整性和不可否认性验证。7.2 数字证书 使用食品和食用农产品追溯系统接口的生产经营者，可申请具有相应资质的CA中心签发的数字证书。使用数字证书对接口的传输内容进行数字签名，实现身份识别和数据传输安全。7.3 数字令牌 使用食品和食用农产品追溯系统接口的生产经营者，可通过认证接口申请追溯系统签发的

16、数字令牌。使用接口传输数据时附加数字令牌，实现身份识别和数据传输安全。数字令牌的有效期应为7天，在数字令牌过期前，生产经营者应重新申请新的令牌；生产经营者的新令牌一经颁发，原有令牌即刻失效。DB 31/T 1110.32025 5 A A 附录A （规范性）食品和食用农产品追溯系统接口服务功能说明 A.1 授权接口 A.1.1 接口地址 接口地址由请求的URL地址构成，具体包含以下几个部分：域名或IP地址、端口号、接口路径以及接口关键字auth。示例：https:/域名:端口/api/v1/auth。A.1.2 功能说明 系统授权接口，验证调用方的appKey和签名，验证通过后，返回数字令牌。

17、A.1.3 参数说明 A.1.3.1 提交方法(Method)：提交（Post）。A.1.3.2 请求头(Header)具体内容见表 A.1。表 A.1 授权接口请求头(Header)表 参数名称 数据类型 是否必填 描述 Content-Type String 是 请求数据的内容类型字符串，固定为：application/json;charset=utf-8 A.1.3.3 请求参数以 JSON 格式消息体(Body)传输，具体内容见表 A.2。表 A.2 授权接口请求参数表 参数名称 数据类型 是否必填 描述 appKey String 是 服务端提供给调用者的凭证，用于标识服务接口调用者

18、的身份 timestamp Timestamp 是 接口调用时间 signature String 是 请求签名，用于验证此次请求的合法性，由调用者根据实际的输入参数，并凭密钥（appSecret）和约定的签名算法生成的签名 A.1.3.4 返回内容类型(Content-Type)：application/json;charset=utf-8。A.1.3.5 返回数据的参数说明见表 A.3。表 A.3 授权接口返回参数表 参数名称 数据类型 是否必填 描述 success Boolean 是 接口调用结果，包括以下两种结果：True=接口调用成功；DB 31/T 1110.32025 6 表

19、A.3 授权接口返回参数表（续）参数名称 数据类型 是否必填 描述 False=接口调用失败。code Number 是 接口响应码，见表 A.10 message String 否 接口提示信息 result Object 是 接口调用成功后，返回的数据对象 token String 是 接口调用成功后，返回的数字令牌 expired Timestamp 是 数字令牌的过期时间 code Number 是 接口响应码，见表 A.10 A.1.4 请求示例 授权接口请求的消息示例参见图A.1。请求方法：Post URL：https:/ 请求头:Content-Type:application/

20、json;charset=utf-8 请求消息体：appKey:ak00001,timestamp:1711001391000,signature:xxxxxxxxxxx 图 A.1 授权接口请求的消息示例 A.1.5 返回示例 授权接口返回的解密后的消息明文示例参见图A.2。图 A.2 授权接口返回的消息明文示例 success:true,code:200,result:token:xxxxxxxx.xxxxxxxxxxxxxxxxxx.xxxxxxxx,expired:1711011391000 DB 31/T 1110.32025 7 A.2 上传接口 A.2.1 接口地址 接口地址由请

21、求的 URL 地址构成，具体包含以下几个部分：域名或 IP 地址、端口号、接口路径以及接口关键字数据元标识。示例：https:/域名:端口/api/v1/数据元标识。数据元标识为上传的追溯信息数据集的唯一标识，例如 product 表示产品信息。具体可参考DB31/T 1110.2。A.2.2 功能说明 追溯信息的上传接口。A.2.3 参数说明 A.2.3.1 提交方法(Method)：提交（Post）。A.2.3.2 请求头(Header)具体内容见表 A.4。表 A.4 上传接口请求头(Header)表 参数名称 数据类型 是否必填 描述 Content-Type String 是 请求数

22、据的内容类型字符串，固定为：application/json;charset=utf-8 Authorization String 是 调用者的认证凭据，由固定字符串Bearer+数字令牌字符串拼接而成 A.2.3.3 请求参数以 JSON 格式消息体(Body)传输，具体内容见表 A.5。表 A.5 上传接口请求参数表 参数名称 数据类型 是否必填 描述 data Array 是 按照数据元的标识和数据元的值，构造数据元的 JSON 对象，并可将多条数据元 JSON 组合为一个 Array 放入该参数值中，实现批量上传。A.2.3.4 返回内容类型(Content-Type)：applica

23、tion/json;charset=utf-8。A.2.3.5 返回数据的参数说明见表 A.6。表 A.6 上传接口返回参数表 参数名称 数据类型 是否必填 描述 success Boolean 是 接口调用结果，包括以下两种结果：True=接口调用成功；DB 31/T 1110.32025 8 表 A.6 上传接口返回参数表（续）参数名称 数据类型 是否必填 描述 False=接口调用失败。code Number 是 接口响应码，见表 A.10 message String 否 接口提示信息 A.2.4 请求示例 上传接口请求的消息示例参见图A.3。图 A.3 上传接口请求的消息示例 A.2

24、5 返回示例 上传接口返回的解密后的消息明文示例参见图A.4。图 A.4 上传接口返回的消息明文示例 请求头:Content-Type:application/json;charset=utf-8 Authorization:Bearer xxxxxxxx.xxxxxxxxxxxxxxxxxx.xxxxxxxx 请求消息体：data:productionName:饮料 A,producerName:生产厂商 A,standard:500ml,shelfLife:180,category:6,barcode:6901234567892,certNo:A12345678,certPicture:

25、data:application/jpeg;base64,xxxxxxxxxxxxxxxxxxxxxx ,productionName:饮料 B,producerName:生产厂商 B,standard:500ml,shelfLife:180,category:6,barcode:6911234567891,certNo:B12345678,certPicture:data:application/jpeg;base64,xxxxxxxxxxxxxxxxxxxxxx success:true,code:200 DB 31/T 1110.32025 9 A.3 查询接口 A.3.1 接口地址 接

26、口地址由请求的 URL 地址构成，具体包含以下几个部分：域名或 IP 地址、端口号、接口路径以及接口关键字 trace。示例：https:/域名:端口/api/v1/trace。A.3.2 功能说明 根据单品追溯码查询追溯信息的查询接口。A.3.3 参数说明 A.3.3.1 提交方法(Method)：接收（Get）。A.3.3.2 请求头(Header)具体内容见表 A.7。表 A.7 单品追溯码查询接口请求头(Header)表 参数名称 数据类型 是否必填 描述 Content-Type String 是 请求数据的内容类型字符串，固定为：application/json;charset=u

27、tf-8 Authorization String 是 调用者的认证凭据，由固定字符串Bearer+数字令牌字符串拼接而成 A.3.3.3 请求参数以 URL 参数格式传递，具体内容见表 A.8。表 A.8 单品追溯码查询接口请求参数表 参数名称 数据类型 是否必填 描述 individualCode String 是 要 获 取 追 溯 信 息 的 单 品 追 溯 码，例 如：010690123456789221000002。A.3.3.4 返回内容类型(Content-Type)：application/json;charset=utf-8。A.3.3.5 返回数据的参数说明见表 A.9。

28、表 A.9 单品追溯码查询接口返回参数表 参数名称 数据类型 是否必填 描述 success Boolean 是 接口调用结果，包括以下两种结果：True=接口调用成功；False=接口调用失败。DB 31/T 1110.32025 10 表 A.9 单品追溯码查询接口返回参数表(续)参数名称 数据类型 是否必填 描述 code Number 是 接口响应码，见表 A.10 message String 否 接口提示信息 data Object 是 按照数据元的标识和数据元的值，返回该追溯码对应的数据元的JSON 对象。A.3.4 请求示例 单品追溯码查询接口请求的消息示例参见图A.5。图 A

29、5 查询接口请求的消息示例 A.3.5 返回示例 单品追溯码查询接口返回的解密后的消息明文示例参见图A.6。图 A.6 查询接口返回的消息明文示例 请求方法：Get URL：https:/ 请求头:Content-Type:application/json;charset=utf-8 Authorization:Bearer xxxxxxxx.xxxxxxxxxxxxxxxxxx.xxxxxxxx success:true,code:200,data:product:productionName:饮料 A,producerName:生产厂商 A,standard:500ml,shelfLif

30、e:180,category:6,barcode:6901234567892,certNo:A12345678,certPicture:data:application/jpeg;base64,xxxxxxxxxxxxxxxxxxxxxx ,sales:code:xxxxxxxxxxxxxxxxxxxx,name:销售单位 A,tCode:010690123456789221000002,producer:生产厂商 A,productionDate:2024-9-9,batch:1000,quantity:123,unit:公斤,saleDate:2024-10-10 DB 31/T 1110.32025 11 A.4 接口响应码说明 接口响应码见表A.10。表 A.10 接口响应码及状态说明 响应码 状态说明 200 服务器已成功处理请求 400 错误的请求 401 未获得登录授权或令牌失效 403 服务器拒绝请求 404 服务器找不到请求的接口或页面 500 服务器遇到错误，无法完成请求 502 服务器作为网关或代理，从上游服务器收到无效响应 503 服务器目前无法使用（由于超载或停机维护）504 服务器作为网关或代理，但是没有及时从上游服务器收到请求