2 0 2 5 0 4 1 1 发 布 － － 2 0 2 5 0 7 0 1 － － 实 施 农 产 品 质 量 安 全 追 溯 数 据 接 口 0 4 中 华 人 民 共 和 国 农 业 行 业 标 准 备 案 号 ： X X X X - X X X X Ｉ Ｃ Ｓ 6 5 . 0 2 0 . 0 1 C C S B 4 7 1 3 — 2 0 2 5 Q u a l i t y a n d s a f e t y t r a c e a b i l i t y o f a g r i c u l t u r a l p r o d u c t s — D a t a i n t e r f a c e Ｎ Ｙ ／ Ｔ 中 华 人 民 共 和 国 农 业 农 村 部 发 布NY/T４７１３—２０２５ 目　　次 前言 Ⅱ 􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺 １　范围 １ 􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺 ２　规范性引用文件 １ 􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺 ３　术语和定义 １ 􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺 ４　缩略语 １ 􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺 ５　设计原则 １ 􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺 ６　技术要求 １ 􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺 ７　接口实现 ２ 􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺 ８　接口安全 ４ 􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺 附录A(资料性)　常见接口错误代码及错误描述 ５ 􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺 附录B(资料性)　接口示例 ６ 􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺􀆺 ⅠNY/T４７１３—２０２５ 前　　言 本文件按照GB/T１􀆰１—２０２０«标准化工作导则　第１部分:标准化文件的结构和起草规则»的规定 起草. 请注意本文件的某些内容可能涉及专利.本文件的发布机构不承担识别专利的责任. 本文件由农业农村部市场与信息化司提出. 本文件由农业农村部农业信息化标准化技术委员会归口. 本文件起草单位:农业农村部农产品质量安全中心、农业农村部信息中心、北京工商大学、中国农业科 学院农业资源与农业区划研究所、中国科学院自动化研究所、中国农业科学院农业信息研究所、北京市农 林科学院、中国农业科学院饲料研究所、北京市农业农村局、上海市农业农村委员会、福建省农业农村厅、 北京市农产品质量安全中心、四川省农产品质量安全中心、内蒙古农畜产品质量安全中心、成都曙光光纤 网络有限责任公司、太极计算机股份有限公司、中检计量有限公司、福建有伦农业科技发展有限公司. 本文件主要起草人:孔亮、王子强、张梦飞、刘希艳、韩福军、赵守香、郑火国、张健、潘立刚、谭杰、王杰、 陈连武、陈炎、林方龙、王全红、云岩春、崔黎、张钰宸、郭征、孙丽娜、任欣欣、周磊、万靓军、张锋、路馨丹、徐 慧敏、刘学刚、徐文锦、沈崇胥、闫伟、陈能文、牟占山、王亚南、张进. ⅡNY/T４７１３—２０２５ 　 　 　农产品质量安全追溯　数据接口 １　范围 本文件规定了农产品质量安全追溯数据接口的设计原则、技术要求、接口实现和接口安全. 本文件适用于农产品质量安全追溯平台建设、平台对接、推广应用、运维服务及监督管理. ２　规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款.其中,注日期的引用文件, 仅该日期对应的版本适用于本文件;不注日期的引用文件,其最新版本(包括所有的修改单)适用于本 文件. GB/T７４０８􀆰１　日期和时间表示法　信息交换表示法　第１部分:基本原则 NY/T４７１０　农产品质量安全追溯　术语 NY/T４７１２　农产品质量安全追溯　数据格式 RFC３５４８　Base１６,Base３２和Base６４　数据编码(TheBase１６,Base３２,andBase６４DataEncodings) RFC３６２９　UTFＧ８数据转换格式(UTFＧ８,atransformationformatofISO１０６４６) ３　术语和定义 NY/T４７１０界定的术语和定义适用于本文件. ４　缩略语 下列缩略语适用于本文件. HTTP:超文本传输协议(hypertexttransferprotocol) HTTPS:超文本传输安全协议(hypertexttransferprotocolsecure) JSON:一种轻量级的数据交换格式(javascriptobjectnotation) SOAP:简易对象访问协议(simpleobjectaccessprotocol) XML:可扩展标记语言(extensiblemarkuplanguage) ５　设计原则 接口设计应遵循以下原则: a)　一致性原则.数据格式、参数命名等保持一致; b)安全性原则.考虑数据加密、身份验证等方面的安全性; c)容错性原则.发生错误时,能够运行并反馈错误信息; d)可扩展性原则.能够随着业务和技术的发展进行灵活调整,满足业务需求变化. ６　技术要求 ６􀆰１　基本要求 ６􀆰１􀆰１　接口要求 接口通过服务调用实现信息交换,应符合以下要求: a)　采用WebServices服务接口; b)采用GB/T７４０８􀆰１规定的日期类型; c)采用RFC３５４８规定的Base６４编码规则将图片文件转换为字符串; d)采用接口日志方式记录数据异常或数据交换情况. １NY/T４７１３—２０２５ ６􀆰１􀆰２　容错要求 发生错误时,能够运行并反馈错误信息.接口服务方将详细的错误信息返回至接口调用方,接口调用 方对错误进行记录和处理.接口错误代码及错误描述见附录A. ６􀆰２　接口协议 接口协议方式包括: a)　采用基于HTTP/HTTPS的简单对象访问协议SOAP; b)采用RFC３６２９规定的UTFＧ８字符集; c)接口请求与接口响应均采用JSON数据交换格式. ６􀆰３　数据要求 调用的数据资源应符合NY/T４７１２的规定,基本数据类型见表１. 表１　数据类型表 序号数据类型 描述 备注 １String 通过字符形式表达的类型 / ２Number 通过阿拉伯数字形式表示的值 NY/T４７１２规定的数据资源涉及该数据类型 ３ Date 表示日期的数据类型,格式为YYYYMMDD NY/T４７１２规定的数据资源涉及该数据类型 ４Datetime表示日期和时间的数据类型,格式为YYYYMMDDhhmmNY/T４７１２规定的数据资源涉及该数据类型 ５Boolean 布尔类型.真值:True;假值:False / ６Object JSON对象类型 / ７　接口实现 ７􀆰１　调用地址 接口服务方提供接口地址. ７􀆰２　接口关系 接口服务方与对接方通过WebService服务调用接口获取数据,接口关系见图１. 图１　接口关系 ７􀆰３　调用方法 ７􀆰３􀆰１　操作方法 数据新增、删除、变更、查询、同步日志获取等功能操作方法见表２,接口示例见附录B. 表２　操作方法 序号 功能 操作方法 １ 数据新增 addData ２ 数据批量新增 addBatch ３ 数据删除 deleteData ４ 数据批量删除 deleteBatch ２NY/T４７１３—２０２５ 表１(续) 序号 功能 操作方法 ５ 数据变更 updateData ６ 数据查询 getData ７ 同步日志获取 getDataChangeLog ７􀆰３􀆰２　参数描述 接口的参数描述见表３. 表３　参数描述 参数名称 类型 输入/输出 解释 Token String 输入 　信息资源的访问令牌 Start_Mark String 输入 　数据查询、同步日志获取操作起始位置 End_Mark String 输入 　数据查询、同步日志获取操作结束位置 Query_Field String 输入 　数据查询要求返回的字段列表 Query_Condition String 输入 　数据查询的条件 Row_Data Object 输入/输出　数据新增、删除、变更、查询、同步日志获取等操作的单条 数据,数据结构见表４ Field_Data Object 输入/输出　数据新增、删除、变更、查询、同步日志获取等操作的单个 数据项,数据结构见表４ Data_Import_Result Object 输出　数据新增、删除、变更操作的数据输入结果,数据结构见 表４ Data_Export_Result Object 输出 　数据查询操作的数据输出结果,数据结构见表４ Data_ChangeLog_Result Object 输出　数据同步日志获取操作的数据日志变更结果,数据结构 见表４ ７􀆰３􀆰３　数据结构 单条数据(Row_Data)、单个数据项(Field_Data)、数据输入结果(Data_Import_Result)、数据输出结 果(Data_Export_Result)、数据日志变更结果(Data_Change_Log_Result)的数据结构见表４. 表