1、ICS 67.040X 00备案号： DB 32江 苏 省 地 方 标 准DB32/T XXXX2018食品安全电子追溯标识解析服务数据接口规范Interface specification of identification resolution service for food safety electronic traceability2018 - XX - XX 发布 2018 - XX - XX 实施江 苏 省 质 量 技 术 监 督 局 发 布DB32/T XXXX2018I目 次前言 .III1 范围 12 规范性引用文件 13 术语和定义 14 缩略语 25 功能要求 35.1
2、 系统架构 35.2 基本服务功能 46 数据接口 46.1 基本要求 46.2 接口原语 46.3 数据类型 56.4 调用方式 56.5 参数要求 56.5.1 IRS 标识解析接口 56.5.2 DCS 网元登陆接口 66.5.3 DCS 网元注册接口 76.5.4 IRS 标识注册接口 76.5.5 IRS 标识更新接口 86.5.6 IRS 标识删除接口 9附录 A（规范性附录） 特殊数据类型定义 10附录 B（资料性附录） 数据接口应用示例 11DB32/T XXXX2018II前 言本标准按照GB/T 1.1-2009给出的规则起草。本标准由江苏省食品药品监督管理局提出并归口。本
3、标准起草单位：江苏省质量和标准化研究院、江苏省食品药品监督信息中心、中科院计算机网络中心、复旦大学无锡研究院、无锡捷玛物联科技有限公司。本标准主要起草人：章学周、杨博、刘佳、吴双力、胡冶、刘毅、田野、王瑜、周广军、曹云、钱侃、王俊宇、关春。DB32/T XXXX20181食品安全电子追溯标识解析服务数据接口规范1 范围本标准规定了食品安全电子追溯标识解析服务的功能要求和数据接口。本标准适用于食品安全电子追溯标识解析服务的接口实现。 2 规范性引用文件下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用
4、于本文件。GB 12904 商品条码 零售商品编码与条码表示RFC 1945 超文本传输协议 1.0 (Hypertext transfer protocol - HTTP/1.0)RFC 2616 超文本传输协议 1.1 (Hypertext transfer protocol - HTTP/1.1)RFC 4627 JSON格式定义(The application/JSON media type for javascript object notation)RFC 4825 可扩展标记语言配置接入协议(The extensible markup language (XML) configu
5、ration access protocol (XCAP)3 术语和定义下列术语和定义适用于本文件。3.1 标识解析服务 identification resolution service将物品的追溯标识翻译成物品所归属的数据目录服务器URL地址的过程。3.2 数据目录服务 data catalog service以物品的追溯标识为索引建立物品所流经的信息查询服务器URL地址列表的过程。3.3 信息查询服务 information query service向数据目录服务器注册追溯标识，并以格式化的数据结构向追溯代理提供追溯信息查询的过程。3.4 网元 network element由软硬件共
6、同组成的能实现网络中的一种或多种逻辑功能的逻辑单元。3.5 DB32/T XXXX20182IRS网元 identification resolution service network element提供追溯标识注册和追溯标识解析服务的网元。3.6 IQS网元 information query service network element提供可视化追溯信息查询服务的网元。3.7 DCS网元 data catalog service network element以追溯标识为单位提供追溯路径的建立和查询服务的网元。 3.8 追溯代理 traceability proxy以用户发起的HTTP
7、追溯查询请求为触发，代替追溯用户调用IRS,DCS和IQS网元的多个接口完成追溯查询逻辑功能的网元。3.9 EU网元 end user network element终端用户所使用的具备追溯查询能力的软件系统的统称。3.10 CU网元 capture unit network element负责采集主数据、交易数据和事件数据并提交到IQS网元，完成数据采集功能的网元。3.11 SP网元 Supervisor Platform Network Element接收IQS网元上报的追溯数据，支撑政府监管人员利用追溯数据开展对企业监管的网元。4 缩略语下列缩略语适用于本文件。CU：捕获单元(Captu
8、re Unit)DNS：域名服务(Domain Name Service)DCS：数据目录服务(Data Catalog Service)EU：终端用户(End User)GTIN：全球贸易项目代码(Global Trade Item Number)IQS：信息查询服务(Information Query Service)IRS：标识解析服务(Identification Resolution Service)JSON：JS对象标记(Java Script Object Notation)RFID：射频识别(Radio Frequency Identification)SP：监管平台(Supe
9、rvisor Platform)URL：统一资源定位符(Uniform Resource Locator)DB32/T XXXX20183URN：统一资源名称(Uniform Resource Name)XML：可扩展标记语言(Extensible Markup Language)5 功能要求5.1 系统架构5.1.1 总则食品安全电子追溯系统应由企业平台、监管平台和查询平台组成。企业应确保食品链的可追溯性，并通过建设符合本框架规定的相关接口的企业平台，加入食品安全电子追溯系统。食品安全电子追溯系统的系统架构见图1。E U网元追溯代理 I R S 网元D C S 网元I Q S 网元C U 网
10、元食品 质量安全监管平台各市监管平台 S P 网元I R S 标识管理接口D C S 标识管理接口D C S 事件登记接口I R S 解析查询接口I Q S查询接口W e b / A P P/ 微信服务数据交换接口数据上报接口I Q S 数据传输接口查询平台 监管平台企业平台D C S查询接口图 1 食品安全电子追溯系统结构5.1.2 网元要求5.1.2.1 IRS 网元应对外提供追溯标识注册和追溯标识解析服务。 5.1.2.2 DCS 网元应以追溯标识为单位提供追溯路径的建立和查询的服务。DCS 网元应以追溯标识为标识确保物品的可追溯性。 5.1.2.3 IQS 网元应提供追溯信息捕获、查询
11、服务和数据上报服务的功能。 5.1.2.4 CU 网元应通过条码识读设备和 RFID 读写器等数据采集设备实现采集一维码、二维码、RFID标签等信息的功能。 5.1.2.5 EU 网元功能应信息终端设备上实现；EU 网元应向用户提供追溯的交互式人机界面。 5.1.2.6 SP 网元应部署在监管部门的服务器系统上，SP 网元应实现支撑利用追溯数据开展对企业的监管功能。 5.1.2.7 追溯代理应以用户发起的追溯请求为触发，代替用户完成追溯系统的内部业务处理。 5.2 基本服务功能DB32/T XXXX20184IRS网元应提供但不限于以下功能：a) 追溯标识注册功能；b) 追溯标识解析功能。6
12、数据接口6.1 基本要求食品安全电子追溯系统的各个网元之间应通过Internet公共以太网接口互联互通。各网元的物理接口上承载的协议栈应为HTTP或HTTPS协议栈，数据接口应使用基于HTTP/HTTPS协议的JSON格式的消息体传输数据。IRS网元和其它各个网元之间应通过数据接口进行消息交互，实现IRS网元的功能。这些具体接口包括：a) IRS 解析查询接口； b) IRS 标识管理接口。 6.2 接口原语基于服务的方式定义数据接口的使用方法。服务响应流程使用了“请求-Request” “指示-Indication”“响应-Response”“确认-Confirm”四条服务原语，原语的顺序见
13、图2。客户端 服务器H T T PR e q u e s t 消息请求 - R e q u e s t指示 - I n d i c a t i o nH T T PR e s p o n s e 消息响应 - R e s p o n s e确认 - C o n f i r m图 2 服务响应流程IRS网元的服务接口分为：a) IRS 标识管理接口；b) IRS 解析查询接口。IRS标识管理接口应包括：a) DCS 网元登陆接口；b) DCS 网元注册接口；c) IRS 标识注册接口；DB32/T XXXX20185d) IRS 标识更新接口；e) IRS 标识删除接口。IRS解析查询接口只包括
14、IRS标识解析接口的一个接口。6.3 数据类型IRS网元接口中所使用到的数据类型见表1。表 1 数据类型说明类型名 类型描述 类型约束String 文本字符串 内容为所有的有效字符Number 数字类型 内容由从 0-9 的数字字符，和+-字符组成List 列表类型 每一项均为一个子数据项，子数据项编码方式与父数据项编码方式相同；每项不超过 305 个文本字符，有具体规定的参见具体规定Datatime 时间类型 固定格式字符串，格式为 YYYY-MM-DD hh:mm:ss6.4 调用方式6.4.1 请求请求接口应通过RFC 1945或RFC 2616中规定的HTTP请求，使用Get或者Pos
15、t方法调用食品电子追溯目录服务接口。请求接口将请求参数按照消息格式用JSON封装后，包含在HTTP的Request消息的Body中发送给对方。6.4.2 响应请求接口调用成功或失败以后，IRS网元应以RFC 4825中规定的XML或RFC 4627中规定的JSON格式将处理结果放置在HTTP的Response消息的Body中，返回给调用者。HTTP的Response消息应符合RFC 1945或RFC 2616中的要求。6.5 参数要求6.5.1 IRS 标识解析接口6.5.1.1 基本要求追溯代理网元应通过IRS标识解析接口向IRS网元发送需要解析的物品标识，并从IRS网元获得该被追溯产品归属
16、的DCS网元的URL地址信息。该接口示例参见附录B.1。6.5.1.2 接口参数该接口名称为IRS_ID_Resolute。IRS标识解析请求接口参数见表2，IRS标识解析响应接口参数见表3。表 2 IRS 标识解析请求接口参数参数名称 类型 最大长度Byte说明 是否必选DB32/T XXXX20186MessageName String 32 取值为 IRS_ID_Resolute 是ObjectCode1 String 255 被查询物品主标识 是ObjectCode2 String 255 被查询物品附加标识 否Role String 255 固定取值为：EndUser 或 Super
17、visor，默认值为 EndUser是GTIN String 14 被查询商品的 GTIN，编码规则参见 GB 12904否OID String 255 被查询商品的 OID 编码 否Handle String 255 被查询商品的 Handle 编码 否表 3 IRS 标识解析响应接口参数参数名称 类型 最大长度Byte说明 是否必选Status String 32 返回结果，定义见表 A.3 是DCSURL String 255 被追溯的资源编码所归属的DCS URL是SrvList List 见表 A.1 DCS 信息列表, Item 类型定义见表 A.1否6.5.2 DCS 网元登陆接
18、口6.5.2.1 基本要求DCS网元应先通过DCS网元登陆接口对DCS网元进行认证，并由IRS网元授予DCS网元相应的权限。IRS网元在对DCS网元的用户名和密码认证通过以后，应将会话ID返回给DCS，后续DCS通过会话ID与IRS网元进行数据交互。IRS网元应删除长期不用的空闲会话ID，空间会话ID的保留时间由IRS网元的管理策略决定。该接口示例参见附录B.2。6.5.2.2 接口参数该接口名称为IRS_DCS_Login，DCS网元登陆请求接口参数见表4，DCS网元登陆响应接口参数见表5。表 4 DCS 网元登陆请求接口参数参数名称 类型 最大长度Byte说明 是否必选MessageNam
19、e String 32 取值为 IRS_DCS_Login 是Name String 255 IRS 授予 DCS 的用户名 是Password String 255 DCS 设置的密码 是表 5 DCS 网元登陆响应接口参数参数名称 类型 最大长度Byte说明 是否必选DB32/T XXXX20187Status String 32 返回结果，定义见表 A.3 是Seid String 32 会话编号，由 IRS 统一分配，每次登陆分配一个全局唯一的会话 ID是6.5.3 DCS 网元注册接口6.5.3.1 接口描述DCS网元应通过DCS网元注册接口向IRS网元注册DCS网元的基础信息。该接
20、口应由DCS网元发起，由IRS网元处理并返回响应给DCS网元。该接口示例参见附录B.3。6.5.3.2 接口参数该接口名称为IRS_DCS_Reg。DCS网元注册请求接口参数见表6，DCS网元注册响应接口参数见表7。表 6 DCS 网元注册请求接口参数参数名称 类型 最大长度Byte说明 是否必选MessageName String 32 取值为 IRS_DCS_Reg 是Seid String 32 会话编号，IQS 在登录过程中获取是Node String 255 DCS 的标识，用于唯一识别DCS是Structure String 32 所注册的标识规则 是SrvList List 见表
21、 A.1 服务资源列表，Item 类型定义见表 A.1是表 7 DCS 网元注册响应接口参数参数名称 类型 最大长度Byte说明 是否必选Status String 32 返回结果，定义见表 A.3 是6.5.4 IRS 标识注册接口6.5.4.1 接口描述DCS网元应通过IRS注册接口实现DCS网元向IRS网元请求标识注册。该接口示例参见附录B.4。6.5.4.2 接口参数接口名称为IRS_ID_Reg，IRS标识注册请求接口参数见表8，IRS标识注册响应接口参数见表9。表 8 IRS 标识注册请求接口参数DB32/T XXXX20188参数名称 类型 最大长度Byte说明 是否必选Mess
22、ageName String 32 取值为 IRS_ID_Reg 是Seid String 32 会话编号，IQS 在登录过程中获取是CodeList List 每项不超过 255 所注册的标识列表，可包含多个标识是Structure String 32 所注册的标识规则 是DCSURL String 255发起标识注册的 DCS 的 URL地址 是表 9 IRS 标识注册响应接口参数参数名称 类型 最大长度Byte说明 是否必选Status String 32 返回结果，定义见表 A.3 是6.5.5 IRS 标识更新接口6.5.5.1 接口描述DCS网元应通过IRS标识更新接口向IRS网元
23、发起请求标识更新请求，修改IRS数据库中标识的相关信息。该接口示例参见附录B.5。6.5.5.2 接口参数接口名称为IRS_ID_Upd，IRS标识更新请求接口参数见表10，IRS标识更新响应接口参数见表11。表 10 IRS 标识更新请求接口参数参数名称 类型 最大长度Byte说明 是否必选MessageName String 32 取值为 IRS_ID_Upd 是Seid String 32会话编号，IQS 在登录过程中获取 是Code String 255 所需要更新的标识 id 是Structure String 32 所更新标识的标识规则 是DCSURL String 255发起标识
24、更新的 DCS 的 URL地址 是表 11 IRS 标识更新响应接口参数参数名称 类型 最大长度Byte说明 是否必选DB32/T XXXX20189Status String 32 返回结果，定义见表 A.3 是6.5.6 IRS 标识删除接口6.5.6.1 接口描述DCS网元与IRS网元之间可通过IRS标识删除接口，实现DCS网元向IRS网元发起请求删除，删除某个指定标识的相关信息。该接口示例参见附录B.6。6.5.6.2 接口参数接口名称为IRS_ID_Del。IRS标识删除请求接口参数见表12, IRS标识删除响应接口参数见表13。表 12 IRS 标识删除请求接口参数参数名称 类型
25、最大长度Byte说明 是否必选MessageName String 32 取值为 IRS_ID_Del 是Seid String 32 会话编号，IQS 在登录过程中获取是DeleteContent String 255 所需删除的标识内容 是DCSURL String 255发起标识删除的 DCS 的 URL地址 是表 13 IRS 标识删除响应接口参数参数名称 类型 最大长度Byte说明 是否必选Status String 32 返回结果，定义见表 A.3 是DB32/T XXXX201810A A附 录 A（规范性附录）特殊数据类型参数Item类型的参数见表A.1，Item类型参数的字段
26、取值见表A.2，Status类型参数见表A.3。表 A.1 Item 类型参数参数名称 类型 最大长度Byte说明 是否必选ItemName String 32 项目名称，取值见表 A.2 是ItemValue String 255 项目值，取值见表 A.2 是表 A.2 Item 类型字段取值ItemName 取值 ItemValue 取值 说明BackupDCSURL String 备份的 DCS 服务器的 URL，当主服务器不可达时，访问备份 DCS 服务器RecordTime Datatime 追溯查询请求被处理的时间，IQS 可以利用该消息与DCS 时间进行同步TranslatedC
27、ode String 按照内置的翻译规则，将被解析的标识翻译成一个新标识Structure String 该编码的编码结构信息表 A.3 Status 类型参数Status 取值 Status 含义 说明Succ 查询成功 成功处理该请求UnknowErr 未知错误 内部出现不可预见的异常CodeNotExist 编码不存在 被查询的编码不存在StructureErr 编码结构不符合规则 编码结构不符合编码组织规定的编码规则DCSErr DCS 状态异常 该编码所对应的 DCS 状态出现异常TooShort 编码太短 编码太短，解析不成功TooLong 编码太长 编码太长，含未知信息DB32/
28、T XXXX201811B B附 录 B（资料性附录）数据接口应用示例B.1 IRS标识解析接口应用示例B.1.1 HTTP-Request消息的JSON消息体var JSONObject= “MessageName“:“IRS_ID_Resolute“,“ObjectCode1“:“06900413431157“,“ObjectCode2“:“201709061A23“,“Role“:“EndUser“,“GTIN“:“06900413431157“,“Structure“:“GS1“B.1.2 HTTP-Response消息的JSON消息体var JSONObject= “Status“:
29、“Succ“,“SrvList“:“DCSURL“:“http:/ DCS网元登陆接口应用示例B.2.1 HTTP-Request消息的JSON消息体var JSONObject= “MessageName“:“IRS_DCS_Login“,“Name“:“NanJingDCS-01“,“Password“:“Js89765“B.2.2 HTTP-Response消息的JSON消息体var JSONObject= “Status“:“Succ“,“Seid“:“20170987681“B.3 DCS网元注册接口应用示例B.3.1 HTTP-Request消息的JSON消息体:var JSONO
30、bject= “MessageName“:“IRS_DCS_Reg“,“Node“:“http:/ HTTP-Response消息的JSON消息体:var JSONObject= “Status“:“Succ“DB32/T XXXX201812B.4 IRS标识注册接口应用示例B.4.1 HTTP-Request消息的JSON消息体var JSONObject= “MessageName“:“IRS_ID_Reg“,“codeList“:“ID“:“urn:cniotroot:id:obj:“,“ID“:“urn:cniotroot:id:obj:“,“Structure“:“GS1“,“DC
31、SURL“:“http:/ HTTP-Response消息的JSON消息体var JSONObject= “Status“:“Succ“B.5 IRS标识更新接口应用示例B.5.1 HTTP-Request消息的JSON消息体var JSONObject= “MessageName“:“IRS_ID_Upd“,“updateContent“:“urn:cniotroot:id:obj:“,“Structure“:“GS1“,“DCSURL“:“http:/ HTTP-Response消息的JSON消息体var JSONObject= “Status“:“Succ“B.6 IRS标识删除接口应用示例B.6.1 HTTP-Request消息的JSON消息体var JSONObject= “MessageName“:“IRS_ID_Del“,“DeleteContent“:“urn:cniotroot:id:obj:“B.6.2 HTTP-Response消息的JSON消息体var JSONObject= “Status“:“Succ“_
