DB32∕T 310024.3-2024 长三角地区食品和食用农产品信息追溯 第3部分：数据接口(江苏省).pdf

ICS 35.240.99 CCS L 78 长江三角洲区域地方标准 长三角地区食品和食用农产品信息追溯 第 3 部分：数据接口 Yangtze River Delta information traceability for food and edible agricultural productsPart 3:Data interface 2024-05-17 发布 2024-09-01 实施 上海市市场监督管理局 江苏省市场监督管理局 浙江省市场监督管理局 安徽省市场监督管理局 DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 发 布 DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 I 目次 前言.II 引言.III 1 范围.1 2 规范性引用文件.1 3 术语和定义.1 4 缩略语.1 5 数据接口技术要求.2 6 数据结构.3 7 服务功能类型.4 8 接口安全.4 附录 A（资料性）长三角食品安全信息追溯平台数据接口 JSON 格式数据示例.5 DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 II 前言 本文件按照GB/T 1.12020标准化工作导则 第 1 部分：标准化文件的结构和起草规则的规定起草。本文件为 DB31/T 310024长三角地区食品和食用农产品信息追溯的第 3 部分。DB31/T 310024已经发布了以下部分：第 1 部分：通则；第 2 部分：数据元；第 3 部分：数据接口。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由上海市市场监督管理局、江苏省市场监督管理局、浙江省市场监督管理局、安徽省市场监督管理局联合提出、归口并组织实施。本文件主要起草单位：上海仪电溯源科技有限公司、上海市质量和标准化研究院、上海市农业科学院、上海海关动植物与食品检验检疫技术中心、江苏省质量和标准化研究院、浙江省标准化研究院、浙江省市场监督管理数字传媒中心、阿里云计算有限公司、安徽省质量和标准化研究院。本文件主要起草人：柳凌、胡传鑫、邵逸超、陈艳、阮丽芳、朱殊瑶、陈志明、潘明阳、崔诚、卜奎昊、陈青宇、管旭琳、章学周、侯月丽、杨博、程禹、鲁轮、周超群、徐振、彭海涛、王献礼、齐相峰、蔡丽华、石念、朱婕、那晶、过李辉、程璐璐、李博、闻天、丁炜、郭锐、钱文婧、骆琳、安金林、陈寿赛、叶文倩、郭德华、杨捷琳。DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 III 引言 本文件旨在推动构建区域联动的食品安全信息追溯体系。DB31/T 310024 由三个部分构成。第 1 部分：通则。目的在于为长三角地区食品和食用农产品信息追溯平台建设工作提供指导。第 2 部分：数据元。目的在于用来准确无歧义定义长三角地区食品和食用农产品的数据元分类方式和相关数据元信息。第 3 部分：数据接口。目的在于为长三角地区食品和食用农产品信息追溯平台数据接口的设计、开发和应用提供指导。本文件系统梳理了长三角地区食品和食用农产品信息追溯平台中各个参与方在数据收集、存储、传递和共享过程，研究编制了长三角地区食品和食用农产品信息追溯平台数据接口的数据结构和数据接口输出文件，确保数据的互操作性、一致性和安全性。DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 1 长三角地区食品和食用农产品信息追溯 第 3 部分：数据接口 1 范围 本文件规定了长三角地区食品和食用农产品追溯的数据接口技术要求、数据结构、服务功能类型和接口安全要求。本文件适用于长三角地区（上海市、江苏省、浙江省、安徽省）食品和食用农产品追溯信息交换、共享、传输和认证的接口实现。2 规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T 74082005 数据元和交换格式 信息交换 日期和时间表示法 GB/T 38155 重要产品追溯 追溯术语 DB31/T 310024.1 长三角地区食品和食用农产品信息追溯 第1部分：通则 DB31/T 310024.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 Media Type for JavaScript Object Notation)3 术语和定义 GB/T 38155、DB31/T 310024.1界定的以及下列术语和定义适用于本文件。3.1 数据接口 data interface 用于数据交换的服务，包括服务的功能、位置以及通讯的协议、传输格式和认证方法。3.2 安全认证 security certificate 保证数据传输安全的加密方法和身份认证方法。3.3 数字令牌 digital token 分发给传输方，代表传输方身份及权限的加密字符串。4 缩略语 DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 2 下列缩略语适用于本文件。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 基本要求 长三角地区食品和食用农产品信息追溯数据接口通过服务调用获取所需的信息，应符合下列要求：a)采用符合 IETF RFC 2818 的 HTTPS 协议作为底层承载协议；b)采用符合 IETF RFC 3629 规定的 UTF-8 字符集；c)采用符合 GB/T 7408 规定的日期类型；d)采用符合 IETF RFC 3548 规定的 Base64 编码规则将图片、文件二进制字节流转换为字符串；e)接口响应采用 IETF RFC 4627 规定的 JSON 数据格式；f)建立接口日志记录，能识别数据异常或追溯交换数据情况；g)发生错误时，接口将详细的错误代码和错误信息返回给接口使用方，以利于接口使用方进行记录分析和整改。5.2 接口格式定义 数据接口格式定义主要包括：a)接口地址：请求的 URL 地址，一般由域名或 IP、端口号、接口路径组成，参见附录 A 中 A.1；b)功能说明：数据接口功能的简要描述，参见附录 A 中 A.2；c)参数说明：调用数据接口的输入参数或者输出参数情况，参见附录 A 中 A.3；d)请求示例：数据接口的请求参数示例，参见附录 A 中 A.4；e)返回示例：数据接口调用正常或异常的报文主体示例，参见附录 A 中 A.5；f)接口响应码说明：数据接口的响应状态码，参见附录 A 中 A.6。5.3 数据类型 数据接口应支持的数据类型包括：a)字符型，用 String 表示；b)整数型，用 Integer 表示；c)浮点型，用 Float 表示；d)布尔型，用 Boolean 表示；e)日期时间型，用 DateTime 表示，应符合 GB/T 7408-2005 中定义的扩展时间表示法。日期格式为：YYYY-MM-DD，时区为中国北京时间(GMT+8)；时间格式为：YYYY-MM-DDThh:mm:ss，时区为中国北京时间(GMT+8)；根据信息交换中各方的约定，在不会引起日期和时间组合的日的表示法与本文件定义的其他表示法出现混淆的情况下，字符T可以省略；DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 3 f)文件型，用字符串标识，应采用 data:；base64,的字符串格式进行拼接。其中：表示文件的类型，例如 application/pdf；表示文件二进制字节流的 Base64 编码字符串；g)对象型，用 Object 表示，对应 JSON 中的“对象符号”；h)数组型，用 Array 表示，是一个或多个 JSON 对象符号的集合；i)空，用 NULL 表示。6 数据结构 6.1 应对接口交换的长三角食品安全信息追溯平台追溯数据的数据集进行封装，追溯数据的数据集由多条追溯数据构成，每一条追溯数据由追溯参与方和追溯单元构成，总体数据结构见图 1。注：图中实线表示必须包含，虚线表示可以包含。线段上的数字表示可以包含的数量，例如：1 表示可以包含1条，0.n 表示可以包含0到多条数据。图1 总体数据结构 6.2 总体数据结构组成元素见表 1。表1 总体数据结构组成元素 名称 数据类型 是否必填 描述 追溯数据的数据集 Array 是 追溯数据的数据集数组，由一组或多组追溯数据组成 追溯数据 Object 是 追溯数据对象，包括一组追溯参与方和一组追溯单元信息组成，并可根据需求扩展使用其他信息 追溯参与方 Object 是 追溯参与方信息数据包括一组食品和食用农产品生产经营者信息对象（以参数名称 enterprise 标识），信息的内容应符合DB31/T 310024.2 的要求 DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 4 表 1 总体数据结构组成元素（续）名称 数据类型 是否必填 描述 追溯单元 Object 是 追溯单元数据包括一组食品和食用农产品基础信息（以参数名称product 标识）、一组食品和食用农产品生产信息（以参数名称production 标识）、一组或多组食品和食用农产品流通信息（以参数名称 circulation 标识）、零或多组食品和食用农产品抽检信息对象（以参数名称 inspection 标识），信息的内容应符合 DB31/T 310024.2 的要求 其他信息 Object 是 视需求，可适情扩展使用，以参数名称 other 标识 7 服务功能类型 数据接口服务功能类型主要包括：a)认证接口，用于进行身份认证和授权访问，可以确保安全性和数据隐私；b)查询接口，用于获取数据和信息，可以满足不同的查询需求；c)权限管理接口，用于管理用户和角色的权限，控制对数据的访问和操作。8 接口安全 8.1 安全认证 数据接口采用数字令牌签名的方式进行安全认证。8.2 数字令牌 数据接口调用者应向数据接口服务提供方申请数字令牌，数字令牌通常包含appKey和appSecret两部份，appKey是调用者身份的标识，appSecret是调用者的密钥，调用者使用appSecret以约定的算法对参数数据进行签名。数据接口服务提供方可以通过验证参数数据的签名的方式，识别调用者的身份。8.3 传输安全 数据接口服务方提供基于CA颁发的数字证书和基于TLS之上的HTTPS协议的数据接口服务，应符合IETF RFC 2818中的规范建立连接并传输数据。8.4 数据加密 长三角地区食品和食用农产品信息追溯数据宜通过约定的加密算法，对明文数据进行加密处理后，再进行数据传输。DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 5 附录A （资料性）长三角食品安全信息追溯平台数据接口 JSON 格式数据示例 A.1 接口地址 接口地址通常由请求的URL地址构成，具体包含以下几个部分：域名或IP地址、端口号以及接口路径。示例：https:/域名:端口/api/trace A.2 功能说明 追溯信息查询的服务接口。根据请求调用返回某个追溯码对应的追溯信息。A.3 参数说明 A.3.1 提交方法(Method)：接收（Get）。A.3.2 请求头(Header)：如表A.1所示。表A.1 请求头(Header)表 参数名称 数据类型 是否必填 描述 appKey String 是 服务端提供给调用者的凭证，用于标识服务接口调用者的身份 timestamp DateTime 是 接口调用时间，采用 YYYY-MM-DDThh:mm:ss 的格式转化为字符串传输 signature String 是 请求签名，用于验证此次请求的合法性，由调用者根据实际的输入参数，并凭密钥（appSecret）和约定的签名算法生成的签名 A.3.3 请求参数以URL参数格式传输，如表A.2所示。表A.2 请求参数表 参数名称 数据类型 是否必填 描述 traceCode String 是 追溯码 page Integer 否 请求数据的当前页码，用于支持数组数据分页，默认为第 1 页 size Integer 否 请求数据的每页条数，用于支持数组数据分页，默认为 20 条 A.3.4 返回内容类型(Content-Type)：application/json;charset=utf-8。A.3.5 返回数据的参数说明，如表A.3所示。表 A.3 返回参数表 参数名称 数据类型 是否必填 描述 success Boolean 是 接口调用结果，包括以下两种结果：True=接口调用成功；False=接口调用失败。DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 6 表 A.3 返回参数表（续）参数名称 数据类型 是否必填 描述 code Number 是 接口响应码，见 A.6 message String 否 接口提示信息 total Integer 是 查询到的数据总条数，可用于支持数组数据分页 page Integer 是 返回数据的当前页码 size Integer 是 返回数据的条数 result Array 是 接口调用成功后，返回的追溯数据的数据集 enterprise Object 是 接口调用成功后，返回的食品和食用农产品生产经营者信息对象，对象中的参数见 DB31/T 310024.2 中第 6 章的规定 product Object 是 追溯信息中的食品和食用农产品基础信息对象，对象中的参数见DB31/T 310024.2 中第 7 章的规定 production Object 是 追溯信息中的食品和食用农产品生产信息对象的数组，对象中的参数见 DB31/T 310024.2 中第 8 章的规定 circulation Array 否 追溯信息中的食品和食用农产品流通信息对象的数组，流通信息对象中的参数见 DB31/T 310024.2 中第 9 章的规定 inspection Array 否 追溯信息中的食品和食用农产品抽检信息对象的数组，抽检信息对象中的参数见 DB31/T 310024.2 中第 10 章的规定 A.4 请求示例 请求的消息示例参见图A.1。请求方法：Get URL：https:/ 请求头:appKey:ak00001 timestamp:2023-05-31T09:09:09 signature:xxxxxxxxxxx 图 A.1 请求的消息示例 A.5 返回示例 返回的解密后的消息明文示例参见图A.2。success:true,code:200,total:200,page:1,size:20,result:图 A.2 返回消息代码示例 DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 7 enterprise:enterpriseName:上海市 xxxx 有限公司,enterpriseTrademark:上海 xxx,enterpriseType:0,uniSCID:91310000000000000X,licNo:JY00000000000000,certPicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,certEffectiveDate:2020-01-01,certExpiryDate:2030-01-01,legalRepresentative:张 xx,supervisoryAgency:xxx 街道市场监管所,scope:食品生产、销售,address:黄浦区 xxx 路 xxx 号,contactPerson:张 xx,contactPhone:13900000001,legalPersonType:0,establishmentDate:2020-01-01,businessLicensePicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,registeredAddress:黄浦区 xxx 路 xxx 号,registrationAuthority:黄浦区市场监督管理局,businessModel:批发,certificateStatus:1 ,product:productionName:饮料 A,producerName:生产厂商 A,standard:500ml,shelfLife:180,category:6,barcode:6901234567892,certNo:12345678,certPicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,production:productionDate:2022-01-01,batchNumber:20220101,origin:上海市,certificationPicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,certNoOfOrigin:CDZ000001,certNoOfOriginPicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,CIQNo:CIQ0000001,图A.2 返回消息代码示例（续）DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 8 CIQPicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,quarantineInstitution:检疫机构 A,certNoOfQuarantine:JYZS000001,certNoOfQuarantinePicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,executiveStandard:GB/TXXXXXX ,circulation:quantity:1000,unit:吨,saleDate:2022-02-01,customerName:江苏省南京市 xxxx 有限公司,customerAddr:江苏省南京市 xxx 路 xxx 号,customerTel:13800000000,uniSCID:91310000000000000X,licNo:JY00000000000000 ,inspection:enterpriseName:被抽样单位名称 A,uniSCID:91310000000000001X,address:抽样地点,province:上海市,city:上海市,county:黄浦区,sampleName:饮料 A,category:食品大类,subcategories:食品亚类,sampleStandard:样品规格,batchNumber:样品批号,productionDate:2022-01-01,checkTime:2022-02-01,reportDate:2022-02-05,producerName:标识生产企业名称,producerAddress:标识生产企业地址,reportNumber:SN000000000X,checkItem:检测项目 A,standardValue:3.05.0,inspectValue:实际检测值 4.1,inspectionResults:1,图A.2 返回消息代码示例（续）DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 9 inspectionAgency:上海检测机构 A ,enterprise:enterpriseName:上海市 xxxx 有限公司,enterpriseTrademark:上海 xxx,enterpriseType:0,uniSCID:91310000000000001X,licNo:JY00000000000001,certPicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,certEffectiveDate:2020-01-01,certExpiryDate:2030-01-01,legalRepresentative:张 xx,supervisoryAgency:xxx 街道市场监管所,scope:食品生产、销售,address:黄浦区 xxx 路 xxx 号,contactPerson:张 xx,contactPhone:13900000002,legalPersonType:0,establishmentDate:2020-01-01,businessLicensePicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,registeredAddress:黄浦区 xxx 路 xxx 号,registrationAuthority:黄浦区市场监督管理局,businessModel:批发,certificateStatus:1 ,product:productionName:饮料 A,producerName:生产厂商 A,standard:500ml,shelfLife:180,category:6,barcode:6901234567892,certNo:12345678,certPicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,production:productionDate:2022-01-01,batchNumber:20220101,图A.2 返回消息代码示例（续）DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 10 origin:上海市,certificationPicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,certNoOfOrigin:CDZ000001,certNoOfOriginPicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,CIQNo:CIQ0000001,CIQPicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,quarantineInstitution:检疫机构 A,certNoOfQuarantine:JYZS000001,certNoOfQuarantinePicture:data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=,executiveStandard:GB/TXXXXXX ,circulation:quantity:1000,unit:吨,saleDate:2022-02-01,customerName:江苏省苏州市 xxxx 有限公司,customerAddr:江苏省苏州市 xxx 路 xxx 号,customerTel:13800000000,uniSCID:91310000000000000X,licNo:JY00000000000000 ,inspection:enterpriseName:被抽样单位名称 A,uniSCID:91310000000000002X,address:抽样地点,province:上海市,city:上海市,county:黄浦区,sampleName:饮料 A,category:食品大类,subcategories:食品亚类,sampleStandard:样品规格,batchNumber:样品批号,productionDate:2022-01-01,checkTime:2022-02-01,reportDate:2022-02-05,producerName:标识生产企业名称,producerAddress:标识生产企业地址,图A.2 返回消息代码示例（续）DB31/T 310024.32024 DB32/T 310024.32024 DB33/T 310024.32024 DB34/T 310024.32024 11 reportNumber:SN000000000X,checkItem:检测项目 A,standardValue:3.05.0,inspectValue:实际检测值 4.1,inspectionResults:1,inspectionAgency:上海检测机构 A 图A.2 返回消息代码示例（续）A.6 接口响应码说明 接口响应码见表A.4。表 A.4 接口响应码及状态说明 响应码 状态说明 200 服务器已成功处理请求 401 未获得登录授权或令牌失效 403 服务器拒绝请求 404 服务器找不到请求的接口或页面 500 服务器遇到错误，无法完成请求 502 服务器作为网关或代理，从上游服务器收到无效响应 503 服务器目前无法使用（由于超载或停机维护）504 服务器作为网关或代理，但是没有及时从上游服务器收到请求