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

　　上海市地方标准

　　DB31/T1110.3—2025代替DB31/T1110.3—2018

　　食品和食用农产品信息追溯

　　第3部分：数据接口规范

　　Fullchaintraceabilityoffoodandedibleagriculturalproducts

　　information—Part3：Datainterface

　　2025-12-23发布2026-04-01实施

　　上海市市场监督管理局发布

　　DB31/T1110.3—2025

　　目次

　　前言 II

　　引言 III

　　1范围 1

　　2规范性引用文件 1

　　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

　　DB31/T1110.3—2025

　　前言

　　本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。

　　本文件是DB31/T1110《食品和食用农产品信息追溯》的第3部分。DB31/T1110已经发布了以下部分：

　　——第1部分：追溯编码与标识规范;

　　——第2部分：数据元规范;

　　——第3部分：数据接口规范。

　　本文件代替DB31/T1110.3—2018《食品和食用农产品信息追溯第3部分：数据接口》，与DB31/T1110.3—2018相比，除结构调整和编辑性改动外，主要技术变化如下：

　　a)更改了“技术要求”一章(见第5章5.1、5.2、5.3，2018年版的第5章);

　　b)删除了“数据接口”相关要求(见2018年版的第6章);

　　c)增加了“服务功能类型”一章(见第6章)，增加了“食品和食用农产品追溯系统接口服务功能说明”(见附录A)。

　　请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。

　　本文件由上海市食品药品安全委员会办公室提出。

　　本文件由上海市市场监督管理局归口并组织实施。

　　本文件起草单位：上海仪电溯源科技有限公司、上海市大数据中心、上海市农业科学院、中国物品编码中心、上海市质量和标准化研究院、上海市农产品质量安全中心、上海前石科技有限公司、上海海关机电产品检测技术中心。

　　本文件主要起草人：王献礼、彭海涛、蔡丽华、张向飞、王轶、方海宾、倪孟锴、李硕、朱丽华、陈旭、祁兵、徐振、齐相峰、陈可、卢宁、张轶荦、吴新敏、夏磊、苏航、钱进、李文婷、王佳琦。

　　本文件及其所代替文件的历次版本发布情况为：

　　——2018年首次发布为DB31/T1110.3—2018;

　　——本次为第一次修订。

　　引言

　　本文件旨在建立食品和食用农产品信息追溯的基础规范，明确追溯编码、数据元及接口标准，适用于追溯信息的标识、采集与交换。DB31/T1110由以下三个部分组成：

　　——第1部分：追溯编码与标识规范，用于规定追溯码的结构、标识方式及符号要求;

　　——第2部分：数据元规范，用于规定追溯相关信息的数据分类、结构及格式要求;

　　——第3部分：数据接口规范，用于规定追溯信息交换接口的技术要求与安全机制。

　　本文件梳理了上海市食品和食用农产品信息追溯系统的信息交换、共享、传输和认证，确保数据的互操作性、一致性和安全性。

　　食品和食用农产品信息追溯

　　第3部分：数据接口规范

　　1范围

　　本文件规定了上海市食品和食用农产品追溯系统接口的技术要求、服务功能类型和接口安全的要求。本文件适用于上海市食品和食用农产品追溯系统的信息交换、共享、传输和认证的接口实现。

　　2规范性引用文件

　　下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件;不注日期的引用文件，其最新版本(包括所有的修改单)适用于本文件。 GB/T7408.1日期和时间信息交换表示法 第1部分：基本原则 GB/T20518信息安全技术公钥基础设施 数字证书格式 GB/T38155重要产品追溯追溯术语

　　DB31/T1110.1食品和食用农产品信息追溯

　　第1部分：追溯编码与标识规范 DB31/T1110.2食品和食用农产品信息追溯 第2部分：数据元规范 IETFRFC2818TLS上的HTTP(HTTPoverTLS)

　　IETFRFC3548Base16、Base32、Base64数据编码(TheBase16,Base32,andBase64DataEncodings)IETFRFC3629UTF-8，ISO10646转换格式(UTF-8,atransformationformatofISO10646)IETFRFC4627JSON格式定义(Theapplication/jsonmediatypeforjavascriptobject

　　notation)

　　3术语和定义

　　GB/T38155、DB31/T1110.1、DB31/T1110.2界定的以及下列术语和定义适用于本文件。3.1

　　数据接口datainterface

　　一组用于数据交换的服务。

　　注：包括服务的功能、位置以及通讯的协议、传输格式和认证方法。

　　3.2

　　数据接口协议datainterfaceprotocol

　　用来和数据接口(3.1)服务进行通讯的应用层协议。

　　注：其内容包括定义消息的内容、消息类型的语法结构、域所包含的信息的含义，确定通信程序何时发送消息和接收消息的规则。

　　3.3

　　接口传输规范interfacetransmissionstandard

　　定义数据源和数据宿之间传送的数据内容的格式和标记语言。

　　3.4

　　DB31/T1110.3—2025

　　安全认证securitycertificate

　　保证数据传输安全的加密方法和身份认证方法。

　　3.5

　　数字令牌digitaltoken

　　分发给传输方，代表传输方身份及权限的加密字符串。

　　3.6

　　数字签名digitalsignature

　　附加在数据单元上的一些数据，或是对数据单元所作的密码交换，这种数据或变换允许数据单元接收者确认数据单元的来源和完整性，并防止数据单元被人(例如接收者)伪造。

　　4符号和缩略语

　　下列缩略语适用于本文件。

　　CA：数字证书认证机构(CertificateAuthority)

　　HTTPS：超文本传输安全协议(HyperTextTransferProtocoloverSecureSocketLayer)

　　JSON：JavaScript对象标记(JavaScriptObjectNotation)

　　TLS：传输层安全协议(TransportLayerSecurity)

　　URL：统一资源定位符(UniformResourceLocator)

　　UTF-8：一种可变长度字符编码(8-bitUnicodeTransformationFormat)

　　5技术要求

　　5.1基本要求

　　食品和食用农产品追溯系统的接口应符合下列要求：

　　a)采用符合IETFRFC2818的HTTPS协议作为底层承载协议;

　　b)采用符合IETFRFC3629规定的UTF-8字符集;

　　c)采用符合GB/T7408.1规定的日期类型;

　　d)采用符合IETFRFC3548规定的Base64编码规则将图片、文件二进制字节流转换为字符串;

　　e)接口响应采用IETFRFC4627规定的JSON数据格式;

　　f)建立接口日志记录，能识别数据异常或追溯交换数据情况;

　　g)发生错误时，接口将详细的错误代码和错误信息返回给接口使用方，以利于接口使用方进行记录分析和整改。

　　5.2接口格式定义

　　接口格式定义包括但不限于：

　　a)接口地址：请求的URL地址，一般由域名或IP、端口号、接口路径组成;

　　b)功能说明：数据接口功能的简要描述;

　　c)参数说明：调用数据接口的输入参数或者输出参数情况;

　　d)请求示例：数据接口的请求参数示例;

　　e)返回示例：数据接口调用正常或异常的报文主体示例;

　　f)接口响应码说明：数据接口的响应状态码。

　　5.3数据类型 接口支持传输的数据类型应包括：

　　a)字符型，用String表示;

　　b)整数型，用Integer表示;

　　c)浮点型，用Float表示;

　　d)布尔型，用Boolean表示;

　　e)日期时间型，用DateTime表示，应符合GB/T7408.1中定义的扩展时间表示法。日期格式为：YYYY-MM-DD，时区为中国北京时间(GMT+8);时间格式为：YYYY-MM-DDThh:mm:ss，时区为中国北京时间(GMT+8);根据信息交换中各方的约定，在不会引起日期和时间组合的表示法与本文件定义的其他表示法出现混淆的情况下，字符[T]可省略;

　　f)时间戳型，用Timestamp表示，通过计算从1970年1月1日0点至当前时间的毫秒数，并将毫秒数结果作为数字传输;

　　g)文件型，用字符串标识，应采用data：;base64，的字符串格式进行拼接。其中：表示文件的类型，例如application/pdf;表示文件二进制字节流的Base64编码字符串;

　　h)对象型，用Object表示，对应JSON中的对象符号;

　　i)数组型，用Array表示，是一个或多个JSON对象符号的集合;

　　j)空，用NULL表示。

　　6服务功能类型

　　追溯系统接口服务和格式的定义，应符合附录A的规定。追溯系统接口服务功能的示意图见图1，其类型主要包括：

　　a)授权接口，用于进行身份认证和授权访问，可确保安全性和数据隐私;

　　b)上传接口，用于上传追溯数据到追溯系统中;

　　c)查询接口，用于获取追溯数据和信息，可满足不同环节参与者的查询需求。

　　注：图中实线箭头表示接口调用，实线空心箭头表示产品流向。

　　图1追溯系统接口服务功能示例图 7接口安全

　　7.1安全认证

　　食品和食用农产品追溯系统接口应采用数字证书和数字令牌的方式实现安全认证，数字证书的格式应符合GB/T20518的规定。平台提供密码和证书服务，用于身份认证、证书解析、证书认证、信息的机密性、完整性和不可否认性验证。

　　7.2数字证书

　　使用食品和食用农产品追溯系统接口的生产经营者，可申请具有相应资质的CA中心签发的数字证书。使用数字证书对接口的传输内容进行数字签名，实现身份识别和数据传输安全。

　　7.3数字令牌

　　使用食品和食用农产品追溯系统接口的生产经营者，可通过认证接口申请追溯系统签发的数字令牌。使用接口传输数据时附加数字令牌，实现身份识别和数据传输安全。数字令牌的有效期应为7天，在数字令牌过期前，生产经营者应重新申请新的令牌;生产经营者的新令牌一经颁发，原有令牌即刻失效。 A

　　A

　　附录A

　　(规范性)

　　食品和食用农产品追溯系统接口服务功能说明

　　A.1授权接口

　　A.1.1接口地址

　　接口地址由请求的URL地址构成，具体包含以下几个部分：域名或IP地址、端口号、接口路径以及接口关键字auth。

　　示例：https://{域名}:{端口}/api/v1/auth。

　　A.1.2功能说明

　　系统授权接口，验证调用方的appKey和签名，验证通过后，返回数字令牌。

　　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 是 服务端提供给调用者的凭证，用于标识服务接口调用者的身份 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=接口调用成功; 表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://www.mydomain.com/api/v1/auth

　　请求头:

　　Content-Type:application/json;charset=utf-8请求消息体：

　　{

　　"appKey":"ak00001",

　　"timestamp":"1711001391000",

　　"signature":"xxxxxxxxxxx"

　　} 图A.1授权接口请求的消息示例

　　A.1.5返回示例

　　授权接口返回的解密后的消息明文示例参见图A.2。

　　{

　　"success":true,

　　"code":200,

　　"result":

　　{

　　"token":"xxxxxxxx.xxxxxxxxxxxxxxxxxx.xxxxxxxx","expired":1711011391000

　　}

　　} 图A.2授权接口返回的消息明文示例 A.2上传接口

　　A.2.1接口地址

　　接口地址由请求的URL地址构成，具体包含以下几个部分：域名或IP地址、端口号、接口路径以及接口关键字{数据元标识}。

　　示例：https://{域名}:{端口}/api/v1/{数据元标识}。

　　{数据元标识}为上传的追溯信息数据集的唯一标识，例如product表示产品信息。具体可参考DB31/T1110.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 是 请求数据的内容类型字符串，固定为：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)：application/json;charset=utf-8。

　　A.2.3.5返回数据的参数说明见表A.6。

　　表A.6上传接口返回参数表

　　参数名称 数据类型 是否必填 描述 success Boolean 是 接口调用结果，包括以下两种结果：

　　True=接口调用成功; 表A.6上传接口返回参数表(续) 参数名称 数据类型 是否必填 描述 — — — False=接口调用失败。 code Number 是 接口响应码，见表A.10 message String 否 接口提示信息

　　A.2.4请求示例

　　上传接口请求的消息示例参见图A.3。

　　请求头:

　　Content-Type:application/json;charset=utf-8

　　Authorization:Bearerxxxxxxxx.xxxxxxxxxxxxxxxxxx.xxxxxxxx

　　请求消息体：

　　{

　　"data":[

　　{

　　"productionName":"饮料A",

　　"producerName":"生产厂商A",

　　"standard":"500ml",

　　"shelfLife":180,

　　"category":"6",

　　"barcode":"6901234567892",

　　"certNo":"A12345678",

　　"certPicture":"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"}

　　]

　　} 图A.3上传接口请求的消息示例

　　A.2.5返回示例

　　上传接口返回的解密后的消息明文示例参见图A.4。

　　{

　　"success":true,"code":200

　　} 图A.4上传接口返回的消息明文示例

　　A.3查询接口

　　A.3.1接口地址

　　接口地址由请求的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=utf-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。

　　表A.9单品追溯码查询接口返回参数表

　　参数名称 数据类型 是否必填 描述

　　success

　　Boolean

　　是 接口调用结果，包括以下两种结果：

　　True=接口调用成功;

　　False=接口调用失败。 表A.9单品追溯码查询接口返回参数表(续)

　　参数名称 数据类型 是否必填 描述 code Number 是 接口响应码，见表A.10 message String 否 接口提示信息 data Object 是 按照数据元的标识和数据元的值，返回该追溯码对应的数据元的JSON对象。

　　A.3.4请求示例

　　单品追溯码查询接口请求的消息示例参见图A.5。

　　请求方法：Get

　　URL：https://www.mydomain.com/api/v1/trace?individualCode=010690123456789221000002

　　请求头:

　　Content-Type:application/json;charset=utf-8

　　Authorization:Bearerxxxxxxxx.xxxxxxxxxxxxxxxxxx.xxxxxxxx 图A.5查询接口请求的消息示例

　　A.3.5返回示例

　　单品追溯码查询接口返回的解密后的消息明文示例参见图A.6。

　　{

　　"success":true,

　　"code":200,

　　data:{

　　"product":{

　　"productionName":"饮料A",

　　"producerName":"生产厂商A",

　　"standard":"500ml",

　　"shelfLife":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"

　　}

　　}

　　} 图A.6查询接口返回的消息明文示例

　　A.4接口响应码说明

　　接口响应码见表A.10。

　　表A.10接口响应码及状态说明

　　响应码 状态说明 200 服务器已成功处理请求 400 错误的请求 401 未获得登录授权或令牌失效 403 服务器拒绝请求 404 服务器找不到请求的接口或页面 500 服务器遇到错误，无法完成请求 502 服务器作为网关或代理，从上游服务器收到无效响应 503 服务器目前无法使用(由于超载或停机维护) 504 服务器作为网关或代理，但是没有及时从上游服务器收到请求