食品安全信息追溯基础技术规范 第3部分：数据接口

1DB53/TXXXX.3—2022食品安全信息追溯基础技术规范第3部分：数据接口本文件规定了食品安全信息追溯的数据接口技术要求、数据接口参数和接口安全。本文件适用于食品安全信息追溯的数据交换、传输和认证。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T7408数据元和交换格式信息交换日期和时间表示法GB/T7635.1全国主要产品分类与代码第1部分：可运输产品GB12904商品条码零售商品编码与条码表示GB/T38155重要产品追溯追溯术语RFC1945超文本传输协议1.0(Hypertexttransferprotocol--HTTP/1.0)RFC2616超文本传输协议1.1(Hypertexttransferprotocol--HTTP/1.1)RFC4627JSON格式定义(Theapplication/JSONmediatypeforjavascriptObjectnotation)RFC4825可扩展标记语言配置接入协议(Theextensiblemarkuplanguage(XML)configurationaccessprotocol(XCAP))3术语和定义下列术语和定义适用于本文件。3.1数据接口datainterface一组用于数据交换的服务，包括服务的功能、位置以及通讯的协议、传输格式和认证方法。3.2接口协议interfaceprotocol需要进行信息交换的接口间需要遵从的通信方式和要求。其内容包括协议约定、消息头域、消息体内容等，确定通信程序发送消息和接收消息的规则。3.3消息头MessageHeader消息头包含了关于消息本身的元数据（例如，发送者和目标详细信息、消息属性、消息类型），不同传输的头包含不同类型的信息。3.4安全认证securitycertificate保证数据传输安全的加密方法和身份认证方法。3.5“名称/值”对name/valuepair2DB53/TXXXX.3—2022JSON的数据存储格式，“名称/值”对组合中的名称写在前面双引号中，值写在后面双引号中，中间用冒号隔开，“名称/值”对之间由逗号分隔。3.6追溯系统中对追溯单元进行唯一标识的代码。[来源：GB/T38155—2019，2.10]4缩略语下列缩略语适用于本文件。HTTPS：安全超文本传输协议（HyperTextTransferProtocoloverSecureSocketLayer）JSON：一种轻量级的数据交换格式(JavaScriptObjectNotation)MD5：消息摘要算法第五版（Message-DigestAlgorithm5）RESTFul：基于HTTPS协议，可以使用XML格式定义或JSON格式定义Token：是服务端生成的一串加密字符串、以作客户端进行请求的一个“令牌”URL：互联网服务程序上用于指定信息位置的表示方法（UniformResourceLocator）UTF-8：一种可变长度字符编码(8-bitUnicodeTransformationFormat)XML：可扩展标记语言（ExtensibleMarkupLanguage）5技术要求5.1基本要求5.1.1接口要求接口通过服务调用实现信息交换，应符合下列要求：——采用符合GB/T7408规定的日期类型；——接口请求与接口响应均采用JSON数据格式；——建立接口日志记录，能识别数据异常或追溯交换数据情况。5.1.2容错要求发生错误时，接口服务方将详细的错误信息返回至接口调用方，由接口调用方对错误进行记录分析和整改。5.2接口协议接口协议方式包括：——采用基于HTTPS传输协议的RESTFul接口方式；——采用JSON格式报文打包方式。5.3消息头基本参数5.3.1安全认证接口Header参数安全认证接口Header参数见表1。3DB53/TXXXX.3—2022表1安全认证接口Header参数表参数名称参数描述Authorization接口授权采用默认值5.3.2业务交互接口Header参数业务交互接口Header参数见表2。表2业务交互接口Header参数表接口授权授权token，格式为：bearer+token例如：bearereyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJpc3N1c2VyIiwiYXVkIjoiYXVkaWVuY2UiLCJ0ZW5hbnRfaWQiOiIwMDAwMDAiLCJ1c2VyX25hbWUiOiLkupHljZfkupHpgJ_kv6Hmga_mioDmnK_mnInpmZDlhazlj7giLCJ0b2tlbl90eXBlIjoiYWNjZXNzX3Rva2VuIiwicm9sZV9uYW1lIjoiZW50ZXJwcmlzZSIsInVzZXJfdHlwZSI6Im1hc3RlciIsInVzZXJfaWQiOiI5OTY0NTgzMDUxMTgxMjE4MyIsInJvbGVfaWQiOiIxNDAyNDM3NTkyMDc4NzQ5Njk3Iiwibmlja19uYW1lIjoi5LqR5Y2X5LqR6YCf5L-h5oGv5oqA5pyv5pyJ6ZmQ5YWs5Y-4IiwiZGV0YWlsIjp7InR5cGUiOiJ3ZWIifSwiZW50ZXJwcmlzZV9jb2RlIjoiOTE1MzAxMDJNQTZLNEtBNTdRIiwiZGVwdF9pZCI6IjIzNyIsImFjY291bnQiOiI5MTUzMDEwMk1BNks0S0E1N1EiLCJjbGllbnRfaWQiOiJzYWJlciIsImV4cCI6MTY1NTM3MDM4MCwibmJmIjoxNjU1MzY2NzgwfQ.M8o2wrI6eKb9JovCDKLGhZVAB4k4tmwA-GmUGEGzZ71zCStoL62e0vmRlzppuniuOcvQa8cbqHyz1E_uk-MyEQ采用默认值5.4基本数据类型基本数据类型说明见表3。表3数据类型说明表6数据接口6.1数据接口分类4DB53/TXXXX.3—2022数据接口分类见图1所示。图1数据接口分类6.2基本信息接口6.2.1安全认证接口获取用户登录token信息，进行用户安全认证，相关参数见表4。表4安全认证接口数据是是是是是6.2.2商品类别查询接口查询追溯商品类别，参数见表5。表5商品类别查询接口数据是String是查询追溯商品类别，返回值见表6。5DB53/TXXXX.3—2022表6商品类别查询返回值String6.2.3图片文件上传接口上传食品追溯相关数据时所需提供的图片文件，参数见表7。表7图片文件上传接口数据File是String是图片文件上传接口，返回值见表8。表8返回值86.2.4新增食品生产经营市场主体信息备案上传新增食品生产企业、食品经营企业的基本备案信息，如：企业统一社会信用代码、企业名称等，参数见表9。表9新增食品市场主体信息备案是是是是是是是是6DB53/TXXXX.3—2022表9新增食品市场主体信息备案（续）是是营业执照图片URL地址是许可证图片图片URL地址新增食品市场主体信息备案，返回值见表8所示。6.2.5新增原辅料信息备案上传新增追溯食品的原辅料基本备案信息，如：类别、名称、来源等，参数见表10。表10新增原辅料备案数据是是是是4是是是是是是2是是新增原辅料信息备案，返回值见表8所示。6.2.6新增生产食品信息备案上传新增生产食品备案基本信息，包括食品类别、食品名称等，参数见表11。表11新增生产食品信息备案数据是是是是7DB53/TXXXX.3—2022表11新增生产食品信息备案数据（续）否是保质期单位，D天M月Y年是是是4是是是是是是否4是是新增生产食品信息备案，返回值见表8所示。6.2.7新增采购食品信息备案上传新增采购食品备案基本信息，包括食品类别、食品名称等，参数见表12。表12新增采购食品信息备案数据是是是是是是4是是是是是是4是新增采购食品信息备案，返回值见表8所示。8DB53/TXXXX.3—20226.2.8新增仓库备案上传新增仓库备案基本信息，参数见表13。表13新增仓库备案数据warehouseName是warehouseAddr是warehouseType是是是是是是新增仓库备案，返回值见表8所示。6.3追溯信息接口6.3.1新增生产食品数据上传新增生产食品数据信息，包括批次号、生产日期等，参数见表14。表14新增生产食品数据是Array是是是是是是是新增生产食品数据，返回值见表8所示。6.3.2上传质检报告上传生产食品的质检报告图片，参数见表15。表15上传质检报告数据是是质检报告图片URL地址9DB53/TXXXX.3—2022上传质检报告，返回值见表8所示。6.3.3新增原辅料进货数据上传新增原辅料进货信息，包括原料类别、数量等，参数见表16。表16新增原辅料进货数据是是是是是是是是新增原辅料进货数据，返回值见表8所示。6.3.4新增首站进货数据流通企业上传新增食品首站进货数据，参数见表17。表17新增首站进货数据是是是是是是是是是是是4是是是是是新增首站进货数据，返回值见表8所示。DB53/TXXXX.3—20226.3.5新增食品销货数据流通企业上传新增食品销货订单数据，参数见表18。表18新增食品销货数据String4是String是String是String是String是Datetime是String否是新增食品销货数据，返回值见表8所示。6.4追溯码生成接口6.4.1追溯码下载接口食品追溯码的下载，参数见表19。表19追溯码下载数据是String是是是追溯码下载，返回值见表8所示。6.4.2追溯码样式新增新增追溯码样式（带码值和图片），参数见表20。表20追溯码样式新增数据String是String是String是String是二维码示例图URL地址是是String是DB53/TXXXX.3—2022追溯码样式下载，返回值见表8所示。6.4.3追溯码样式生成生成追溯码（带码值，有图片），参数见表21。表21追溯码样式生成数据是是追溯码样式生成，返回值见表8所示。6.4.4追溯码生成生成追溯码（只有码值），参数见表22。表22追溯码生成数据String是String是String是是追溯码生成，返回值见表8所示。6.4.5追溯码赋码绑定生产企业追溯码绑定对应食品，参数见表23。表23追溯码赋码绑定数据String是String是String是String是String否追溯码赋码绑定，返回值见表8所示。7接口安全7.1安全认证食品安全信息追溯数据接口采用数字令牌的方式实现安全认证。即服务端生成的一串加密字符串、以作客户端进行请求的一个“令牌”，如果“令牌”不存在，说明请求无效。7.2安全传输DB53/TXXXX.3—2022使用食品安全信息追溯信息数据接口的生产经营者，可以申请具有相应资质的CA中心签发的数字证书。采用HTTPS的方式，使用数字证书对接口的传输内容进行数字签名,实现身份识别和数据传输安全。7.3数字令牌使用食品安全信息追溯数据接口的生产经营者,可以申请追溯平台签发的唯一的数字令牌。使用接口传输数据时附加数字令牌,实现身份识别认证。数字令牌的有效期为1小时，令牌失效后生产经营者需要重新申请新的令牌，生产经营者的新令牌一经颁发，原有令牌即刻失效。7.4密码算法数字证书和数字令牌采用的密码算法，应采用符合国家规定的密码算法。DB53/TXXXX.3—2022HTTP状态码表HTTP响应报文状态码，见表A.1。表A.1HTTP响应报文状态码表HTTP状态码POST/PUT消息，带消息体消息已接收不带消息体BadRequestUnauthorizedForbiddenNotFoundTooManyRequestInternalServerErrorDB53/TXXXX.3—2022响应报文样例（JSON格式）B.1安全认证接口B.1.1认证请求请求示例：tenantId:000000username:91530102MA6K4KA57Qpassword:xxxxxxxgrant_type:passwordB.1.2信息返回{"tenant_id":"91530102MA6PHKJ764","user_id":"99645830511814941","dept_id":"530102","post_id":"-1","role_id":"1402437592078749697","oauth_id":"","account":"91530102MA6PHKJ764","user_name":"云南xxxxxx技术有限公司","nick_name":"xxx","role_name":"enterprise","avatar":"冷链系统企业用户","access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJpc3N1c2VyIiwiYXVkIjoiYXVkaWVuY2UiLCJ0ZW5hbnRfaWQiOiIwMDAwMDAiLCJ1c2VyX25hbWUiOiLkupHljZfpvI7ogIDkv6Hmga_mioDmnK_mnInpmZDlhazlj7giLCJ0b2tlbl90eXBlIjoiYWNjZXNzX3Rva2VuIiwicm9sZV9uYW1lIjoiZW50ZXJwcmlzZSIsInVzZXJfdHlwZSI6Im1hc3RlciIsInBvc3RfaWQiOiItMSIsInVzZXJfaWQiOiI5OTY0NTgzMDUxMTgxNDk0MSIsInJvbGVfaWQiOiIxNDAyNDM3NTkyMDc4NzQ5Njk3Iiwibmlja19uYW1lIjoi5p2O5paH5aqbIiwiZGV0YWlsIjp7InR5cGUiOiJ3ZWIifSwiZW50ZXJwcmlzZV9jb2RlIjoiOTE1MzAxMDJNQTZQSEtKNzY0IiwiZGVwdF9pZCI6IjUzMDEwMiIsImFjY291bnQiOiI5MTUzMDEwMk1BNlBIS0o3NjQiLCJjbGllbnRfaWQiOiJzYWJlciIsImV4cCI6MTY1NTM2ODA4OSwibmJmIjoxNjU1MzY0NDg5fQ.FO7so_nz1QRNRpITxgH_Uv9bMNxYuHv3kutET_yKNibzQi6rz18ZzT_kC1E1gp4RVMmvlwhWy8s2hsJu7S9phg","refresh_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJpc3N1c2VyIiwiYXVkIjoiYXVkaWVuY2UiLCJ1c2VDB53/TXXXX.3—2022yX2lkIjoiOTk2NDU4MzA1MTE4MTQ5NDEiLCJ0b2tlbl90eXBlIjoicmVmcmVzaF90b2tlbiIsImNsaWVudF9pZCI6InNhYmVyIiwiZXhwIjoxNjU1OTY5Mjg5LCJuYmYiOjE2NTUzNjQ0ODl9.Yjnj2aLG6P6J3qHhwrQt1Z3c1lzlPS0oi19UXGKRKGazPRsFPKxOiG5s_Iy_PXpk20jYKDvp50JVsiXj3iBztA","token_type":"bearer","expires_in":3600,"detail":{"license":"poweredbyyunsu"}B.2商品类别查询接口{"success":true,{"id":-1,"goodsCatalogId":"99645830511722496","hasChildren":false,"goodsCatalogName":"冷链畜类","parentId":-1,{"id":"99645830511722496","goodsCatalogId":"99645830511722917","hasChildren":false,"goodsCatalogName":"整头及半头鲜或冷藏的野牛肉","parentId":"99645830511722496","msg":"操作成功"B.3图片文件上传接口{"code":"200","msg":"操作成功"“data”:DB53/TXXXX.3—2022{"name":"/foodTraceFile/upload/20220926/03eb98dd5e6a2988a6b7a10bd9d9e49d.jpeg"},"success":true,B.4新增食品生产经营市场主体信息备案{"code":"200","msg":"操作成功""success":true,B.5新增原辅料备案{"code":"200","msg":"操作成功""data":["entMateriaInfoId":"1530067222014230529"],"success":true,B.6