DB37 T 4350-2021 重要产品追溯 食用农产品省级平台数据接口规范.pdf

1、 ICS 35.240.60 CCS L 70 37 山东省 地方 标准 DB 37/T 4350 2021 重要产品追溯 食用农产品省级平台数据 接口规范 Important product traceability Specification for provincial platform data interface of edible agricultural products 2021 - 03 - 11 发布 2021 - 04 - 11 实施 山东省 市场监督管理局 发 布 DB 37/T 4350 2021 I 目 次 前言 . II 1 范围 . 1 2 规范性引用文件 .

2、1 3 术语和定义 . 1 4 缩略语 . 1 5 基本要求 . 1 6 接口类型 . 2 省级平台与市级平台的接口类型 . 2 6.1 省级平台与节点系统的接口类型 . 2 6.2 7 对接要求 . 2 8 接口说明 . 3 接口请求 . 3 8.1 接口响应 . 4 8.2 附录 A（资料性） 代码类型 . 6 A.1 消息业务类型 . 6 A.2 追溯系统类型 . 6 A.3 响应码 . 6 A.4 经营类型 . 7 A.5 流通顺序码 . 7 A.6 内部环节信息类型 . 8 A.7 检测报告类型 . 8 附录 B（资料性） 业务参数示例 . 9 参考文献 . 12 DB 37/T 4

3、350 2021 II 前 言 本文件按照 GB/T 1.1 2020标准化工作导则 第 1部分：标准化文件的结构和起草规则的规定 起草。 请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。 本文件由 山东省商务厅提出、归口并 组织 实施 。 本文件起草单位： 山东省标准化研究院、浪潮软件股份有限公司。 本文件主要起草人： 王玎、 梁厚广、 王志恒、吴业虎、朱承鑫、陈通。 DB 37/T 4350 2021 1 重要产品追溯 食用农产品省级平台数据接口规范 1 范围 本文件规定了食用农产品省级追溯管理平台（以下简称“省级平台”）追溯数据接口的基本要求、 接口类型、对接要

4、求、接口说明。 本文件适用于省级平台与食用农产品市级追溯管理平台（以下简称“市级平台”）之间及省级平台 与食用农产品追溯节点（以下简称“节点”）系统之间的对接，其他相关平台或系统的接入参照执行。 2 规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件， 仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本 文件。 GB/T 7408 数据元和交换格式 信息交换 日期和时间表示法 GB/T 18391.1 信息技术 元数据注册系统（ MDR） 第 1部分：框架 GB/T 38154 2019 重要产品追溯

5、核心元数据 GB/T 38155 重要产品追溯 追溯术语 DB37/T 3659 2019 重要产品追溯 食用农产品省市平台管理规范 IETF RFC 2818 TLS上的 HTTP（ HTTP Over TLS） IETF RFC 3548 Basel6、 Base32、 Base64 数据编码（ The Basel6, Base32, and Base64 Data Encodings） IETF RFC 3629 UTF 8， ISO 10646转换 格式（ UTF-8, a transformation format of ISO 10646） 3 术语和定义 GB/T 18391.1

6、、 GB/T 38155、 DB37/T 3659界定的术语和定义适用于本文件。 4 缩略语 下列缩略语适用于本文件。 HTTPS：以安全为目标的 HTTP通道（ HyperText Transfer Protocol over Secure Socket Layer） JSON：一种轻量级的数据交换格式（ JavaScript Object Notation） SHA-256：安全杂凑算法（ Secure Hash Algorithm），摘要输出长度为 32字节 UTF-8：一种可变长度字符编码（ 8-bit Unicode Transformation Format） 5 基本要求 接口通

7、过服务调用实现信息交换，应符合下列要求： 采用符合 IETF RFC 2818 的 HTTPS 协议作为底层承载协议； 采用符合 IETF RFC 3629 规定的 UTF-8 字符集； DB 37/T 4350 2021 2 采用符合 GB/T 7408 规定的日期类型； 采用符合 IETF RFC 3548 规定的 BASE64 编码规则将图片文件转换为字符串； 接口请求与接口响应均采用 JSON 数据格式； 建立接口日志记录，能识别数据异常或追溯交换数据情况； 发生错误时，接口将详细的错误信息返回至相关平台和节点系统，由各平台和节点系统对错 误进行记录分析和整改。 6 接口类型 省级平台

8、与市级平台的接口类型 6.1 主要包括下列类型： 主体备案信息类：用于市级平台上报节点主体备案信息至省级平台； 产品备案信息类：用于市级平台上报节点产品备案信息至省级平台； 追溯业务信息类：用于市级平台上报节点追溯业务信息至省级平台，业务信 息包括但不限于 种植信息、养殖信息、生产加工信息、屠宰信息、批发（配送）信息、零售信息、消费信息、 召回信息等。 省级平台与节点系统的接口类型 6.2 主要包括：追溯业务信息类，用于节点系统上报节点追溯业务信息至省级平台，该信息是用于面向 消费者展示的追溯查询数据。 7 对接要求 接入前应按照 DB37/T 3659 2019 中第 6 章的要求提出申请、

9、取得入驻资格。对接示意图见图 1。 7.1 DB 37/T 4350 2021 3 省 级 平 台 主 体 备 案 信 息 接 口 产 品 备 案 信 息 接 口 追 溯 业 务 信 息 接 口 在 线 填 报 在 线 填 报 追 溯 业 务 信 息 接 口 市 级 平 台 主 体 备 案 信 息 产 品 备 案 信 息 追 溯 业 务 信 息 种 植 信 息 养 殖 信 息 生 产 加 工 信 息 屠 宰 信 息 批 发 信 息 零 售 信 息 消 费 信 息 召 回 信 息 节 点 系 统 主 体 备 案 信 息 产 品 备 案 信 息 追 溯 业 务 信 息 种 植 信 息 养 殖 信

10、息 生 产 加 工 信 息 屠 宰 信 息 批 发 信 息 零 售 信 息 消 费 信 息 召 回 信 息 注： 节点系统的主体备案信息、产品备案信息不通过接口传输，直接从省级平台在线填报，省级平台 审核通过后， 该节点系统追溯业务信息接口方可使用。 图 1 对接示意图 应采用省级平台分配的授权密匙，以 SHA-256摘要算法生成签名数据，采用 post提交方法（ Method）7.2 及 application/json 内容类型（ Content-Type）上传数据。 节点系统应向省级平台申请追溯码，省级平台接收请求数据，审核校验成功后生成正式的追溯码，7.3 并按申请数量反馈消息至节点系

11、统；节点系统接收响应数据，将上报批次产品数据与省级平台返回的追 溯码及追溯网址绑定，生成二维码标识。 8 接口说明 接口请求 8.1 8.1.1 公共请求 请求参数表见表 1。 表 1 公共请求参数 名称 含义 类型 是否可空 说明 BIZ_TYPE 业务消息类型 字符串 否 见附录 A 中的表 A.1 REQ_TIME 请求时间 日期时间型 否 yyyy-MM-dd HH:mm:ss REQ_ID 请求编码 字符串 否 yyyyMMddHHmmss+6 位字母数字组合随机码 AUTH_ID 认证编码 字符串 否 省级平台提供的授权密匙， SHA-265 加密 PARAM 业务请求参数 字符串

12、 否 见 8.1.2， JSON 子节点，自由文本 DB 37/T 4350 2021 4 请求格式示例见表 2。 表 2 请求格式 BIZ_TYPE:traceDataRequest, REQ_TIME:2020-01-10 00:00:00, REQ_ID:20200721084654qJJ2Jb, AUTH_ID:20200609153209831756, PARAM: 8.1.2 业务请求 业务请求参数应根据接口类型的不同做相应调整，具体参数见对应接口的 WSDL（ Web服务描述语言， Web Services Description Language）文件，应符合 GB/T 381

13、54 2019中的相关规定。追溯业务信息 参数示例见附录 B。 接口响应 8.2 8.2.1 公共响应 公共响应参数见表 3。 表 3 公共响应参数 名称 含义 类型 是否可空 说明 BIZ_TYPE 业务类型 字符串 否 见附录 A 中的表 A.1 RESP_TIME 响应时间 日期时间型 否 yyyy-MM-dd HH:mm:ss RESP_ID 响应编码 字符串 否 响应方产生的唯一编码 REQ_ID 请求编码 字符串 否 请求方的唯一编码 RESULT 响应数据参数 字符串 否 JSON 子节点，自由文本 响应格式示例见表 4。 表 4 响应格式 BIZ_TYPE: traceData

14、Request, RESP_TIME: 2020-01-10 00:00:00, RESP_ID: 20200721084836BSoICl, REQ_ID: 20200721084654qJJ2Jb, RESULT: 8.2.2 业务响应 业务响应结果信息见表 5。 DB 37/T 4350 2021 5 表 5 业务响应参数 名称 含义 类型 是否可空 说明 SUCCESS 是否成功 字符串 否 true/false RESULT_CODE 响应码 字符串 否 见附录 A 中的表 A.3 RESULT_MSG 响应消息 字符串 否 BATCH_ID 批次码 字符串 是 对应请求消息中的批次

15、码 CODE_NUM 追溯码数量 数值型 是 实际返回的追溯码数量 TRACE_IDS 追溯码 字符串 是 多个追溯码以逗号分隔 ,最多返回100000 个，自由文本 其他参数 字符串 是 响应格式示例见表 6。 表 6 响应格式 BIZ_TYPE: traceDataResponse, RESP_TIME: 2020-01-10 00:00:00, RESP_ID: 20200721084836BSoICl, REQ_ID: 20200721084654qJJ2Jb, RESULT: SUCCESS: true, RESULT_CODE: 0000, RESULT_MSG: 处理成功 , B

16、ATCH_ID: 批次码 , CODE_NUM: 追溯码数量 , TRACE_IDS: 追溯码 1,追溯码 2,追溯码 3 DB 37/T 4350 2021 6 A A 附录 A （资料性） 代码类型 A.1 消息业务类型 消息业务类型见表 A.1。 表 A.1 消息业务类型 类型代码 含义 traceDataRequest 追溯数据上报请求 traceDataResponse 追溯数据上报响应 A.2 追溯系统类型 追溯系统类型见表 A.2。 表 A.2 追溯系统类型 类型代码 含义 00 肉菜追溯系统 01 老字号追溯系统 02 可追溯供应商追溯系统 03 商业超市追溯系统 04 地理标

17、志产品追溯系统 05 特色产品追溯系统 06 中药材追溯系统 99 其他追溯系统 A.3 响应码 响应码见表 A.3。 表 A.3 响应码 类型代码 含义 0000 成功 0001 请求参数错误 0002 json 格式不合法 0003 认证信息错误 0004 验签错误 0005 请求时间错误 0006 业务类型错误 0100 非空校验错误 0101 正则表达式校验错误 0102 枚举值校验错误 0103 数据范围校验错误 DB 37/T 4350 2021 7 表 A.3 响应码 （续） 类型代码 含义 0104 长度校验错误 0105 其他校验错误 0300 农残抑制率不合格 50% 03

18、01 检测报告错误 0302 经营主体编码错误 0303 地区校验错误 0304 生成追溯码错误 9999 未知错误 A.4 经营类型 经营类型见表 A.4。 表 A.4 经营类型 类型代码 含义 00 种养殖 10 生产加工 20 批发 21 仓储配送 22 零售 30 团体消费单位 99 其它 A.5 流通顺序码 流通顺序码见表 A.5。 表 A.5 流通顺序码 类型代码 含义 10 种养殖 11 种养殖环节仓储配送 12 种养植环节销售 20 生产加工 21 生产加工环节仓储配送 22 生产加工环节销售 30 批发 31 批发环节仓储配送 32 批发环节销售 40 零售 41 零售环节仓

19、储配送 42 零售环节销售 DB 37/T 4350 2021 8 表 A.5 流通顺序码 （续） 类型代码 含义 50 团体消费单位 51 团体消费单位仓储配送 90 其它 91 其它环节仓储配送 92 其它环节销售 A.6 内部环节信息类型 内部环节信息类型见表 A.6。 表 A.6 内部环节信息类型 类型代码 含义 01 农事信息（种养殖等） 02 生产加工过程信息 03 仓储配送信息 A.7 检测报告类型 检测报告类型见表 A.7。 表 A.7 检测报告类型 类型代码 含义 01 动物检疫合格证明 02 肉品品质检验合格证 03 瘦肉精检测报告 10 农药残留检测报告 20 入境货物检

20、验检疫证明 30 质检报告（生产加工环节） DB 37/T 4350 2021 9 B B 附录 B （资料性） 业务参数示例 追溯业务数据上报请求参数见 B.1。 表 B.1 追溯业务数据上报请求参数 名称 含义 类型 是否可空 说明 TRACE_TYPE 追溯系统类型 字符串 否 见附录 A 中的表 A.2 SEQ_ID 流通顺序码 字符串 否 见附录 A 中的表 A.5 BUSI_ID 经营主体编码 字符串 否 统一社会信用代码 GOODS_ID 商品条码 字符串 否 符合 GB 12904 的规定 GOODS_NAME 商品名称 字符串 否 上报企业系统商品名称 GOODS_NUM 商

21、品数量 数值型 否 GOODS_UNIT 计量单位 字符串 否 KG-千克 ,L-升 GOODS_PRICE 商品单价 数值型 否 元，保留小数点 2 位 BATCH_ID 批次码 字符串 否 企业原批次码 TRACE_ID 追溯码 字符串 是 平台统一下发的追溯码，沿用上一环节 追溯码时使用 OPER_DESC 内部环节信息 字符串 否 见附录 A 中的表 A.6 VERIFY_IMG 检测报告图片 字符串 是 JPG 格式 BASE64 编码字符串 VERIFY_IMGS 检测报告多图地址 字符串 是 多个地址以逗号分隔 VERIFY_MULTIIMG 检测报告多图 字符串 是 报告类型见

22、附录 A 中的表 A.7 VERIFY 检测数据 数组型 是 JSON 子节点 VERIFY/COMPANY 检测单位 字符串 否 检测单位名称 VERIFY/INSPECTOR 检验员 字符串 否 检验员名称 VERIFY/DATE 检测日期 日期型 否 yyyy-MM-dd VERIFY/INHIBIT 抑制率 (%) 数值型 否 如： 22.6，保留小数点 2 位 VERIFY/RESULT 检测结果 字符串 否 如：合格等 MAKE_DATE 生产日期 日期型 否 yyyy-MM-dd VALID_DAYS 保质期 数值型 否 默认天 VALID_TYPE 保质期类型 字符串 是 Y-

23、年， M-月， D-日 CONTACT_BATCH_ID 关联批次码 字符串 是 多个批次码以逗号分隔，填报上游批次 码，用于本环节重新产生批次码的情况 CONTACT_TRACE_ID 关联追溯码 字符串 是 多个追溯码以逗号分隔，填报上游追溯 码，用于本环节重新产生追溯码的情况 CODE_NUM 请求追溯码数量 数值型 否 大于 0 的为请求数量，最大 100000 个， 如果传 0则追溯码 TRACE_ID字段必填， 市级平台上报直接传 0 SELL_COUNTRY 销售地国家编码 字符串 是 销售环节填写符合 GB/T 2659中规定的数字代码 DB 37/T 4350 2021 10

24、 表 B.1 追溯业务数据上报请求参数 （续） 名称 含义 类型 是否可空 说明 SELL_REGION 销售地区编码 字符串 是 销售地为国内时，填写 6 位的省市区编 码（符合 GB/T 2260 中规定的数字代 码），否则为空 请求格式示例见表 B.2。 表 B.2 请求格式 BIZ_TYPE: traceDataRequest, REQ_TIME: 2020-01-10 00:00:00, REQ_ID: 20200721084654qJJ2Jb, AUTH_ID: 20200609153209831756, PARAM: TRACE_TYPE: 追溯类型 , SEQ_ID: 顺序码

25、, BUSI_ID: 经营主体编码 , GOODS_ID: 商品编码 , GOODS_NAME: 商品名称 , GOODS_NUM: 商品数量 , GOODS_UNIT: 计量单位 , GOODS_PRICE: 商品单价 , BATCH_ID: 批次码 , OPER_DESC: OPER_DATE: 2020-07-01, OPERATOR: 种植操作员 , DESC: 种植 , OPER_TYPE: 01 , OPER_DATE: 2020-08-01, OPERATOR: 施肥操作员 , DESC: 施肥 , OPER_TYPE: 01 , DB 37/T 4350 2021 11 表 B

26、.2 请求格式 （续） OPER_DATE: 2020-07-01, OPERATOR: 浸泡操作员 , DESC: 浸泡 , OPER_TYPE: 02 , OPER_DATE: 2020-08-01, OPERATOR: 发酵操作员 , DESC: 发酵 , OPER_TYPE: 03 , VERIFY_IMG: 检测报告图片 , VERIFY_IMGS: 检测报告多图地址 , VERIFY_MULTIIMG: TYPE: 检测类型 , IMG: BASE64编码图片内容或 URL地址 , VERIFY: COMPANY: 检测单位 , INSPECTOR: 检验员 , DATE: 202

27、0-08-06, INHIBIT: 22.6, RESULT: 合格 , MAKE_DATE: 生产日期 , VALID_DAYS: 保质期 , VALID_TYPE: D, CONTACT_BATCH_ID: 关联批次码 , CONTACT_TRACE_ID: 关联追溯码 , CODE_NUM: 请求追溯码数量 , SELL_COUNTRY: 销售地国家编码 , SELL_REGION: 销售地区编码 DB 37/T 4350 2021 12 参考文 献 1 GB/T 2260 中华人民共和国行政区划代码 2 GB/T 2659 世界各国和地区名称代码 3 GB 12904 2008 商品条码 零售商品编码与条码表示 4 GM/T 0017 2012 智能密码钥匙 密码应用接口数据格式规范 5 DB37/T 3660 2019 重要产品追溯 食用农产品省市平台建设规范 6 DB37/T 3661 2019 重要产品追溯 食用农产品追溯码编码规则