长三角地区食品和食用农产品信息第3部分：数据接口.docx

ICS35.240.99CCSL78B长江三角洲区域地方标准DB31T310XX.3202XxDB33T310XX.3202XxDB32T310XX.3202XDB34T310XX.3202X长三角地区食品和食用农产品信息追溯第3部分：数据接口YangtzeRiverDeltainformationtraceabilityforfoodandedibleagriculturalproducts一Part3:Datainterface（征求意见稿）在提交反馈意见时，请将您知道的相关专利连同支持性文件一并附上。XXXX-XX-XX发布XXXX-XX-XX实施上海市市场监督管理局、江苏省市场监督管理局浙江省市场监督管理局、安徽省市场监督管理局发布目次前言II引言TTI1范围12规范性引用文件13术语和定义14缩略语25数据共享方式26数据接口技术要求27数据结构38接口安全4附录A（资料性）长三角食品安全信息平台追溯数据接口JSoN格式数据示例6本文件按照GB"1.1-2020标准化工作导则第1部分：标准化文件的结构和起草规则的规定起草。本文件为DB31“310XX长三角地区食品和食用农产品信息追溯的第3部分。DB31/T31OXX已经发布了以下部分：第1部分：通则；第2部分：数据元；第3部分：数据接口。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由上海市市场监督管理局、江苏省市场监督管理局、浙江省市场监督管理局、安徽省市场监督管理局联合提出并归口。本文件主要起草单位：上海市市场监督管理局、上海仪电溯源科技有限公司、上海市质量和标准化研究院、上海海关动植物与食品检验检疫技术中心、江苏省市场监督管理局、江苏省质量和标准化研究院、浙江省市场监督管理局、浙江省标准化研究院、浙江省市场监督管理数字传媒中心、阿里云计算有限公司、安徽省市场监督管理局、安徽省质量和标准化研究院。本文件主要起草人：陈艳、徐振、彭海涛、齐相峰、蔡丽华、邵逸超、石念、朱婕、那品、郭德华、杨捷琳、朱殊瑶、陈志明、卜奎昊、于全才、管旭琳、章学周、侯月丽、杨博、任永斌、金技、阮丽芳、骆琳、郭锐、闻天、丁炜、过李辉、柳凌、李博、安金林、陈寿赛、胡传鑫、程禹、鲁轮、周超群。为全面贯彻“实施食品安全战略，让人民吃得放心”的要求和习近平总书记关于加强食品安全“四个最严'的一系列重要指示精神，落实长三角区域一体化发展国家战略，加强农产品质量安全追溯体系建设。上海市、江苏省、浙江省、安徽省食品（药品）安全委员会办公室共同协商签订了长三角地区食品安全信息追溯体系建设战略合作协议，坚持“以人民为中心”的发展思想，贯彻实施食品安全战略,进一步深化食品安全合作协调机制，推进建设“信息互通、监管互动、抽检互认、执法互助''的大食品安全工作格局。长三角地区充分利用现代科技手段，在全国率先构建区域联动的食品安全信息追溯体系,推动和促进长三角区域食品安全智能化治理水平提升，保障人民群众“舌尖上的安全DB31/T31OXX拟由三个部分构成。 第1部分：通则，目的在于确立适用于长三角地区食品和食用农产品信息追溯通用技术要求和相关原则。 第2部分：数据元，目的在于规定长三角地区食品和食用农产品追溯信息数据的数据元和数据元目录等。 第3部分：数据接口，目的在于确定适用于长三角地区食品和食用农产品追溯的数据共享方式、数据接口技术要求以及数据接口安全认证方法等内容。数据接口的标准化是长三角地区食品和食用农产品信息追溯数据共享的前提。本文件结合长三角地区食品安全信息追溯体系建设工作实际，旨在确立食品和食用农产品信息追溯系统中各个参与方在数据收集、存储、传递和共享过程中遵循相同的数据接口标准，确保数据的互操作性、一致性和安全性，实现数据的有效共享和合作，更好地保障食品和食用农产品的安全和质量。长三角地区食品和食用农产品信息追溯第3部分：数据接口1范围本文件规定了长三角地区食品和食用农产品追溯的数据共享方式、数据接口技术要求、数据结构和接口安全要求等内容。本文件适用于长三角地区(上海市、江苏省、浙江省、安徽省)内食品和食用农产品追溯信息交换、共享、传输和认证的接口实现。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中,注口期的引用文件,仅该日期对应的版本适用于本文件；不注口期的引用文件，其最新版本(包括所有的修改单)适用于本文件。GBa7408-2005数据元和交换格式信息交换口期和时间表示法GBfT38155重要产品追溯追溯术语DB31/T310XX.1长三角地区食品和食用农产品信息追溯第1部分：通则DB31/T310XX.2长三角地区食品和食用农产品信息追溯第2部分：数据元IETFRFC1945超文本传输协议Lo(HyPerteXttranSferPrOtOeoI-HTTP/1.0)IETFRFC2616超文本传输协议Ll(HyPerteXttransferprotocol-HTTP/1.1)IETFRFC2818TLS上的HTTP(HTTPoverTLS)IETFRFC3548Basel6>BaSe32、Base64数据编码(TheBase16,Base32,andBase64DataEncodings)IETFRFC3629UTF-8,UTF-8,ISOlo646转换格式(UTF-8,aIransformalionformatofISO10646)IETFRFC4627JSON格式定义(Theapplication/JSONmediatypeforjavascriptObjectnotation)3术语和定义GBfT38155、DB31f310XX.l界定的以及下列术语和定义适用于本文件。3.1数据接口datainterface用于数据交换的服务，包括服务的功能、位置以及通讯的协议、传输格式和认证方法。3.2数据接口协议datainterfaceprotocol用来和数据接口服务进行通讯的应用层协议，包括定义消息的内容、消息类型的语法结构、域所包含的信息的含义，确定通信程序何时发送消息和接收消息的规则。3.3接口传输规范interfacetransmissionstandard定义数据源和数据宿之间传送的数据内容的格式和标记语言。3.4安全认证securitycertificate保证数据传输安全的加密方法和身份认证方法。3.5数字令牌digitaltoken分发给传输方，代表传输方身份及权限的加密字符串。3.6“名称/值”对name/valuepairJSON的数据存储格式，“名称/值”对组合中的名称写在前面双引号中，值写在后面双引号中，中间用冒号隔开，“名称/值”对之间由逗号分隔。4缩略语下列缩略语适用于本文件。CA：数字证书认证机构(CertifiCateAUthority)HTTPS：安全超文本传输协议(HyperTextTransferProtocoloverSecureSocketLayer)JSON：一种轻量级的数据交换格式(JavascriptObjectNotation)TLS：传输层安全协议(TranSPortLayerSeCUrity)URL：统一资源定位符(UnifOrmReSOUrCeLoCatOr)UTF-8：一种可变长度字符编码(8-bitUnicodeTransformationFormat)5数据共享方式5.1 长三角地区食品和食用农产品信息追溯，采用各省/直辖市提供统一数据接口服务的共享方式，各省/直辖市按实际情况提供信息的共享接口，供其他省/直辖市的系统使用。5.2 各省/直辖市在需要其他省/直辖市的相关信息追溯时，可以调用对应省/直辖市的数据接口服务，获取追溯数据，用于各自的功能需要。6数据接口技术要求6.1 基本要求长三角地区食品和食用农产品信息追溯数据接口通过服务调用获取所需的信息，应符合下列要求：a)采用符合IETFRFC2818的HTTPS协议作为底层承载协议；b)采用符合IETFRFC3629规定的UTF-8字符集；c)采用符合GB/T7408规定的日期类型；d)采用符合IETFRFC3548规定的Base64编码规则将图片、文件二进制字节流转换为字符串；e)接口响应采用RFC4627规定的JSoN数据格式；f)建立接口日志记录，能识别数据异常或追溯交换数据情况；g)发生错误时，接口将详细的错误代码和错误信息返回给接口使用方，以利于接口使用方进行记录分析和整改。6.2 接口格式定义数据接口格式定义主要包括：a)接口地址：请求的URL地址，一般由域名或IP、端口号、接口路径组成，参见附录A中A.1；b) c)d)e)功能说明 参数说明 请求示例 返回示例数据接口功能的简要描述，参见附录A中A.2；调用数据接口的输入参数或者输出参数情况，参见附录A中A3；数据接口的请求参数示例，参见附录A中A.4；数据接口调用正常或异常的报文主体示例，参见附录A中A.5；f）接口响应码说明：数据接口的响应状态码，参见附录A中A.6。6.3 数据类型数据接口应支持的数据类型包括：a）字符型，用String表示；b）整数型，用Integer表示；c）浮点型，用Float表示；d）布尔型，用BOOIean表示；e）日期时间型，用DateTime表示，应符合GBZT7408-2005中定义的扩展时间表示法。日期格式为：YYYY-MM-DD,时区为中国北京时间（GMT+8）；时间格式为：YYYY-MM-DDThhimnrss,时区为中国北京时间（GMT+8）；根据信息交换中各方的约定，在不会引起日期和时间组合的日的表示法与本标准定义的其他表示法出现混淆的情况下，字符T可以省略；f）文件型，用字符串标识，应采用data:mediatype；base64,data的字符串格式进行拼接。其中：mediatype表示文件的类型，例如application/pdf；data表示文件二进制字节流的Base64编码字符串；g）对象型，用ObjeCt表示，对应JSoN中的“对象符号”；h）数组型，用AITay表示，是一个或多个JSON对象符号的集合；i）空，用NULL表示。7数据结构7.1 追溯数据的总体数据结构7.2 应对接口交换的长三角食品安全信息追溯平台追溯数据的数据集进行封装，追溯数据的数据集由多条追溯数据构成，每一条追溯数据由追溯参与方和追溯单元构成，总体数据结构见图1：图中实线表示必须包含，虚线表示可以包含。线段上的数字表示可以包含的数量，例如：1表示可以包含1条，0.oo:表示可以包含0到多条数据。图1总体数据结构总体数据结构组成元素见表1。表1总体数据结构组成元素名称数据类型是否必填描述追溯数据的数据集Array是追溯数据的数据集数组，由一组或多组追溯数据组成追溯数据Object是追溯数据对象，包括组追溯参与方和组追溯单元信息组成，并可根据需求扩展使用其他信息追溯参与方Object是追溯参与方信息数据包括一组食品和食用农产品生产经营者信息对象（以参数名称enterprise标识）,信息的内容应符合DB31"310XX2的要求追溯单元Object是追溯单元数据包括一组食品和食用农产品基础信息（以参数名称product标识）、一组食品和食用农产品生产信息（以参数名称production标识）、一组或多组食品和食用农产品流通信息（以参数名称CirCUlatiOn标识）、零或多组食品和食用农产品抽检信息对象（以参数名称inspection标识），信息的内容应符合DB3I,7310XX.2的要求其他信息Object是视需求，可适情扩展使用，以参数名称。ther标识8接口安全8.1 安全认证数据接口采用数字令牌签名的方式进行安全认证。8.2 数字令牌数据接口调用者需要向数据接口服务提供方申请数字令牌，数字令牌通常包含叩PKey和appSecrel两部份，appKey是调用者身份的标识，叩PSeCreI是调用者的密钥，调用者使用叩PSeCre似约定的算法对参数数据进行签名。数据接口服务提供方可以通过验证参数数据的签名的方式，识别调用者的身份。8.3 传输安全数据接口服务方提供基于CA颁发的数字证书和基于TLS之上的HTTPS协议的数据接口服务，应符合IETFRFC2818中的规范建立连接并传输数据。8.4 数据加密长三角地区食品和食用农产品信息追溯数据宜通过约定的加密算法，对明文数据进行加密处理后，再进行数据传输。附录A(资料性)长三角食品安全信息平台追溯数据接口JSON格式数据示例A.1接口地址接口地址由请求的URL地址，一般由域名或IP、端口号、接口路径组成。示例：https:/域名:端口apitraceA.2功能说明追溯信息查询的服务接口。根据请求调用返回某个追溯码对应的追溯信息。A.3参数说明A.3.4提交方法(MeIhOd)：GetoA.3.2请求头(Header):如表A.1所示。表Al请求头(Header)表参数名称数据类型是否必填描述appKeyString是服务端提供给调用者的凭证，用于标识服务接口调用者的身份timestampDateTime是接口调用时间，采用YYYY-MM-DDThkmnrss的格式转化为字符串传输signatureString是请求签名，用于验证此次请求的合法性，由调用者根据实际的输入参数，并凭密钥(appSecret)和约定的签名算法生成的签名A.3.3请求参数以URL参数格式传输，如表A.2所示。表A.2请求参数表参数名称数据类型是否必填描述traceCodeString是追溯码pageInteger否请求数据的当前页码，用于支持数组数据分页，默认为第1页sizeInteger否请求数据的每页条数，用于支持数组数据分页，默认为20条A.3.4.返回内容类型(ContenI-TyPe)：application/json;CharSet=Utf-8。3.5返回数据的参数说明，如表A.3所示。表A.3返回参数表参数名称数据类型是否必填描述successBoolean是接口调用结果，包括以下两种结果：TrUe=接口调用成功；FaISe=接口调用失败。codeNumber是接口响应码，见A.6messageString否接口提示信息totalInteger是查询到的数据总条数，可用于支持数组数据分页pageInteger是返回数据的当前页码sizeInteger是返回数据的条数表A.3返回参数表（续）参数名称数据类型是否必填描述resultArray是接11调用成功后，返回的追溯数据的数据集enterpriseObject是接口调用成功后，返回的食品和食用农产品生产经营者信息对象，对象中的参数应符合DB31T310XX.2中第6章的规定productObject否追溯信息中的食品和食用农产品基础信息对象，对象中的参数应符合DB31/T3IOXX.2中第7章的规定productionObject否追溯信息中的食品和食用农产品生产信息对象的数组，对象中的参数应符合DB31/T31OXX.2中第8章的规定circulationArray否追溯信息中的食品和食用农产品流通信息对象的数组，流通信息对象中的参数应符合DB31T310XX.2中第9章的规定inspectionArray否追溯信息中的食品和食用农产品抽检信息对象的数组，抽检信息对象中的参数应符合DB31T310XX.2中第10章的规定A.4请求示例请求的消息示例参见表A.4。表A.4请求的消息示例请求方法：GetURL：https:WWw.mydomain,com/api/trace?traceCode=010690123456789910999999请求头：appKey:ak00001timestamp:2023-05-31TO9:09:09signature:xxxxxxxxxxxA.5返回示例返回的解密后的消息明文示例参见A.5。表A.5返回消息代码示例表“success”:true,"code":200,"total”:200,page:1,"size”:20,“result”:“enterprise”:“enterpriseName":"上海市XXXX有限公司”，“enlerpriseTrademark":"上海xxx”,enterprseType:0,yzUniSCID":"91310000000000000000，“IicNo"："Jyoooooooooooooo",z,certPicturez,:,data:application/jpeg;base64,dk8234klj0ksjdfkl23iosdf=yi,DB31T31OXX.3202XvDB32T31OXX.3202XDB33T31OXX.3202XxDB34T31OXX.3202X表A.5返回消息代码示例表（续）zzCertEffectiveDate":"2020-01-0,“certExpiryDate":"2030-01-01”,“IegalRepresentative”:张xx，“supervisoryAgency":"XXX街道市场监管所”，"scope”:食品生产、销售，“address":"黄浦区XXX路XXX号”，“contactPerson":"张xx”,“contactPhone":"13900000000”,“legalPersonTypeyO”,“establiShmentDate":"2020-Ol-01，“businessLicensePicture":"data:application/jpeg;base64,dk8234klj0ksjdfkl23iosdf=","regiSteredAddreSs":"黄浦区XXX路XXX号”，,regiStrationAuthority":"黄浦区市场监督管理局”，"businessModel":"生产、批发“，“certifiCateStatUs”:T',“product”:zzproductionNamezz:"饮料A”,"producerName":"生产厂商A”,"standard":"500ml”,"shelfLife":"180”,category:5,"barcode":"693000000000,"certNo":"12345678”,"certPiCtUre":"data:application/jpeg;base64,dk8234k1jksjdfkl23iosdf=",“production”:"productionDate":"2022-01-01”,"batChNumber":zz2022010,"origin":"上海市”，*certificationPicture*:*data:application/jpeg;base64,dk8234k1jksjdfk123iosdf=*,"CertNoOfOrigin”:*CDZ00000,zzCertNoOfOriginPicture*:*data:application/jpeg;base64,dk8234klj0ksjdfkl23iosdf=z,"CIQNo":"CIQOOOOOO1”,"CIQPicture”:*data:application/jpeg;base64,dk8234kljksjdfkl23iosdf=,z,quarantineInstitutionz,:"检疫机构A”,zzCertNoOfQuarantine":"JYZSOOOOO1”,表A.5返回消息代码示例表(续)yzCertNoOfQuarantinePiCtUre":"data:application/jpeg;base64,dk8234k1jksjdfk123iOSdf=","executivestandard":"GB/TXXXXXX"),“circulation”:(“quantity”:1000,"unit":吨"，“saleDate":"2022-02-01”,customerNamezz:“江苏省南京市XXXX有限公司”，,customerAddr,z:“江苏省南京市XXX路XXX号”，zzCustomerTer:"138000000000”,zuniSCIDz,:z,91310000000000000Xz,“iicNo"/Jyoooooooooooooo",“inspection”:("enterpriseName”:被抽样单位名称A”,"uniSCID":"91310000000000000X","address":抽样地点，“province":"上海市"，"city":"上海市，“county”:黄浦区，"sampleName":"样品名称A”,"categcy":"食品大类"，"subcategories”:食品亚类”，"sampleStandard”:样品规格”，"batchNumber":"样品批号”，“productiOnDate”:*2022-01-01”,zzCheckTimezz:,2022-02-0,*reportDatezz:"2022-02-05”,"producerName”:标识生产企业名称“，zzProducerAddress:“标识生产企业地址”，"sampieNumber"："Snooooooooox”,"checkItem”:检测项目A”,表A.5返回消息代码示例表（续）zzStandardValue*:“3.05.0","inspectValue":"实际检测值4.1”,z,inspectionResults*:T,"inspectiOnAgencyzz:"上海检测机构A”)JA.6接口响应码说明接口响应码见表A.6。表A.6接口响应码及状态说明响应码状态说明200服务器已成功处理请求401未获得登录授权或令牌失效403服务器拒绝请求404服务器找不到请求的接口或页面500服务器遇到错误，无法完成请求502服务器作为网关或代理，从上游服务器收到无效响应503服务器目前无法使用（由于超载或停机维护）504服务器作为网关或代理，但是没有及时从上游服务器收到请求