肉品溯源数据接口规范

1肉品溯源数据接口规范本文件规定了调用肉品（批发）溯源系统的数据接口进行数据交换的接口方法和调用说明。本文件适用于调用肉品（批发）溯源系统的数据接口的集成开发。2规范性引用文件本文件没有规范性引用文件。3术语和定义下列术语和定义适用于本文件。3.1数据接口datainterface以电子文件的形式实现，计算机软件系统之间传送数据、交换信息的接口。[来源：GB/T42940—2023,3.3]3.2数据对接方datadockingparty数据接口调用者，与肉品（批发）溯源系统进行数据交换的单位。4缩略语下列缩略语适用于本文件。API：应用程序编程接口（ApplicationProgrammingInterface）HTTP：超文本传输协议（HyperTextTransferProtocol）JSON：对象简谱（JavascriptObjectNotation）5接口方法及调用说明5.1接口传输要求及对接流程5.1.1接口使用JSON传输数据，技术接口对接示意如图1所示。肉品数据对接方系统获取访问令牌，访问验证通过后，根据预先定义好的接口方法，进行肉品溯源数据交换，数据接口应用示例见附录A。5.1.2数据交换分为三种方式：a)数据对接方系统输入参数，同步肉品溯源数据后，肉品（批发）溯源系统（以下简称“溯源系统”）自动实时返回溯源数据同步结果；b)数据对接方系统主动进行动检证核验结果查询；2c)数据对接方系统输入参数，同步肉品溯源数据后，溯源系统自动实时返回溯源数据同步结果和动检证核验结果。图1技术接口对接示意图5.2数据类型数据接口应支持的数据类型包括:a)字符型；b)整数型；c)浮点型；f)对象型。35.3数据接口5.3.1凭据Token调用接口接口说明接口说明如下：a)接口名称：接口访问授权调用接口；b)接口描述：用于获取业务接口的访问调用凭据；c)HTTP请求方式：GET；d)接口标识符：GetToken。接口输入参数及说明凭据Token调用接口的输入参数及说明见表1。表1凭据Token调用接口的输入参数及说明是是接口返回参数及说明凭据Token调用接口的返回参数及说明见表2。表2凭据Token调用接口的返回参数及说明是是是成功则返回代码“0”；失败则返回错误码“500”是授权访问令牌Token是5.3.2同步肉品溯源数据的调用接口接口说明接口说明如下：a)接口名称：同步肉品溯源数据的调用接口；b)接口描述：用于同步数据对接方系统的肉品溯源数据；c)HTTP请求方式：POST；d）接口标识符：ImportData。接口输入参数及说明同步肉品溯源数据调用接口的输入参数及说明见表3。4表3同步肉品溯源数据调用接口的输入参数及说明是是否是是产品分类编码，由“动物代码+产品代码+产品类型代码”组成，例如商品猪胴体中温肉分类编码为1010610110102，动物代码、产品代码、产品类型代码分别见附录B、附录C及附录D否是批次编码，批次唯一标识，可用“检疫合格证否是否否是是批次进货单价，单价的单位为“元/KG”或“元/G”是是/(KG,G)”是是否否否是否否否是是是是是是否5表3同步肉品溯源数据调用接口的输入参数及说明（续）空否否否否否否否否否否否接口返回参数及说明同步肉品溯源数据调用接口的返回参数及说明见表4。表4同步肉品溯源数据调用接口的返回参数及说明是是是成功则返回代码“0”；失败则返回错误码“500”是是5.3.3查询动检证核验结果的调用接口接口说明接口说明如下：a）接口名称：查询动检证核验结果的调用接口；b）接口描述：用于数据对接方系统主动发起查询动检证在溯源系统的核验情况；c）HTTP请求方式：POST；d）接口标识符：QueryVerifyResults。接口输入参数及说明查询动检证核验结果的调用接口的输入参数及说明见表5。6表5查询动检证核验结果调用接口的输入参数及说明是空接口返回参数及说明查询动检证核验结果的调用接口的返回参数及说明见表6。表6查询动检证核验结果调用接口的返回参数及说明是是是成功则返回代码“0”；失败则返回错误码“500”是是表7查询动检证核验结果调用接口返回的结果信息参数及说明是是否是是是成功显示“核验通过”，失败显示“核验不通过”否是是否5.3.4同步肉品溯源数据并核验动检证的调用接口接口说明接口说明如下：a)接口名称：同步肉品溯源数据并核验动检证的调用接口；b）接口描述：用于数据对接方系统同步肉品溯源数据并返回核验的动检证结果，核验结果自动实时返回；c)HTTP请求方式：POST；7d)接口标识符：ImportAndVerifyData。接口输入参数及说明同步肉品溯源数据并核验动检证的调用接口输入参数与同步肉品溯源数据的调用接口输入参数一致（见），调用接口的输入参数及说明见表3。接口返回参数及说明同步肉品溯源数据并核验动检证调用接口的返回参数及说明见表8。表8同步肉品溯源数据并核验动检证调用接口的返回参数及说明是是是成功则返回代码“0”；失败则返回错误码“500”是是表9同步肉品溯源数据并核验动检证调用接口返回的结果信息参数及说明是是否是是是“核验不通过”否8（资料性）数据接口应用示例A.1凭据Token接口的应用示例A.1.1接口调用的示例代码凭据Token接口调用的示例代码见图A.1。OkHttpClientclient=newOkHttpClient().newBuilder().build();MediaTypemediaType=MediaType.parse("text/plain");RequestBodybody=RequestBody.create(mediaType,"");Requestrequest=newRequest.Builder().url("/mwtrace/api/api/GetToken?appId=XXX&appSecret=XXX").method("GET",body).build();Responseresponse=client.newCall(request).execute();图A.1凭据Token接口调用的示例代码A.1.2接口调用成功的返回示例凭据Token接口调用成功的返回示例见图A.2。{"success":true,"message":"","code":0,"result":"XXX","timestamp":1724988940013}图A.2凭据Token接口调用成功的返回示例A.1.3接口调用失败的返回示例凭据Token接口调用失败的返回示例见图A.3。9{"success":false,"message":"XXX","code":500,"result":"XXX","timestamp":1724989006467}图A.3凭据Token接口调用失败的返回示例A.2同步肉品溯源数据接口的应用示例A.2.1接口调用的示例代码同步肉品溯源数据接口调用的示例代码见图A.4。OkHttpClientclient=newOkHttpClient().newBuilder().build();MediaTypemediaType=MediaType.parse("application/json");RequestBodybody=RequestBody.create(mediaType,"[{\"salesDocumentNo\":\"分销凭证编号\",\"productBarcode\":\"产品编码\",\"productName\":\"产品名称\",\"productCategoryCode\":\"产品分类编码，由动物代码+产品代码+产品类型代码表组成，例如商品猪胴体中温肉分类编码为1010610110102，详细分类代码见附录\",\"productImg\":\"\",\"batchCode\":\"批次编码，批次唯一标识，例如（检疫合格证号+轨道号+分割流水号）\",\"batch\":\"批次\",\"batchWeight\":\"批次总重量\",\"batchUnit\":\"批次单位(KG，G，默认KG)\",\"batchInNo\":\"批次进货单号\",\"batchInWeight\":\"批次进货重量，\",\"batchInPrice\":\"（元/KG,元/G）\",\"batchInDate\":\"批次进货日期\",\"batchOutPrice\":\"（元/KG,元/G）\",\"batchOutDate\":\"批次销售日期\",\"batchOutWeight\":\"批次销售重量\",\"batchCheckReport\":\"\",\"animalCertNo\":\"动物检疫合格证编号\",\"animalCertType\":\"动物检疫合格证类型（da：动物A证，db：动物B证）\",\"quarantineCertNo\":\"产品检疫合格证编号\",\"quarantineCertType\":\"产品检疫合格证类型（ca：产品A证，cb：产品B证）\",\"producerBaseName\":\"生产/养殖基地名称\",图A.4同步肉品溯源数据接口调用的示例代码\"producerBaseAddr\":\"生产/养殖基地地址\",\"butcherEntName\":\"屠宰企业名称\",\"butcherEntUnifCode\":\"屠宰企业统一社会信用代码\",\"supplierEntName\":\"市场供货企业名称，以英文;间隔\",\"supplierEntUnifCode\":\"市场供货企业统一社会信用代码，多个代码以英文;间隔\",\"flowtoEntName\":\"流向企业名称，多个以英文;间隔\",\"flowtoEntUnifCode\":\"流向企业统一社会信用代码，多个代码以英文;间隔\"，\"qrcodeUrl\":\"分销溯源二维码网址\",\"animalCertSerial\":\"动物检疫合格证流水号\",\"quarantineCertSerial\":\"产品检疫合格证流水号\",\"exHz\":\"附加供货企业，多个企业以英文;间隔\",\"exButcher\":\"附加屠宰企业，多个企业以英文;间隔\",\"exFlowto\":\"附加流向，多个流向以英文;间隔\",\"exAnimalCertUrl\":\"附加动物检疫合格证图片网址，多个网址以英文;间隔\",\"exQuarantineCertUrl\":\"附加产品检疫合格证图片网址，多个网址以英文;间隔\",\"exAnimalCertNo\":\"附加动物检疫证编号，多个编号以英文;间隔\",\"exQuarantineCertNo\":\"附加产品检疫证编号，多个编号以英文;间隔\",\"meatQualityNo\":\"肉品品质检验证编号，多个编号以英文;间隔\",\"meatQualityUrl\":\"肉品品质检验证网址，多个网址以英文;间隔\",\"delFlag\":\"删除标记，默认0为不删除，1为删除，若仅删除数据可只传分销号（salesDocumentNo）和本删除标记\",}]");Requestrequest=newRequest.Builder().url("/mwtrace/api/api/ImportData").method("POST",body).addHeader("X-Access-Token","XXX").addHeader("Content-Type","application/json").build();Responseresponse=client.newCall(request).execute();图A.4同步肉品溯源数据接口调用的示例代码（续）A.2.2接口调用成功的返回示例同步肉品溯源数据接口调用成功的返回示例见图A.5。{"success":true,"message":"第X条，数据导入成功；第X条，数据导入成功；","code":0,"result":"数据导入完成，成功X条，失败X条","timestamp":1724989852669}图A.5同步肉品溯源数据接口调用成功的返回示例A.2.3接口调用失败的返回示例同步肉品溯源数据接口调用失败的返回示例见图A.6。{"success":false,"message":"****","code":500,"result":"****","timestamp":1724989006467}图A.6同步肉品溯源数据接口调用失败的返回示例A.3查询动检证核验结果接口的应用示例A.3.1接口调用的示例代码查询动检证核验结果接口调用的示例代码见图A.7。OkHttpClientclient=newOkHttpClient().newBuilder().build();MediaTypemediaType=MediaType.parse("application/json");RequestBodybody=RequestBody.create(mediaType,"[{\"salesDocumentNo\":\"XXX\",\"batchCode\":\"XXX\",\"quarantineCertNo\":\"XXX\"}]");Requestrequest=newRequest.Builder().url("/mwtrace/api/api/QueryVerifyResults").method("POST",body).addHeader("X-Access-Token","XXX").addHeader("Content-Type","application/json").build();Responseresponse=client.newCall(request).execute();图A.7查询动检证核验结果接口调用的示例代码A.3.2接口调用成功的返回示例查询动检证核验结果接口调用成功的返回示例见图A.8。{"success":true,"message":"","code":0,"result":"verifySlRemark":"","verifySlStatus":0,"verifyStatus":0,"verifyRemark":"","batchCode":"XXX","quarantineCertNo":"XXX","verifyResult":"核验通过","verifySlResult":"数量核验通过","salesDocumentNo":"XXX"}],"timestamp":1724990253246}图A.8查询动检证核验结果接口调用成功的返回示例A.3.3接口调用失败的返回示例查询动检证核验结果接口调用失败的返回示例见图A.9。{{"success":false,"message":"XXX","code":500,"result":"XXX","timestamp":1724989006467}图A.9查询动检证核验结果接口调用失败的返回示例A.4同步肉品溯源数据并核验动检证接口的应用示例A.4.1接口调用的示例代码同步肉品溯源数据并核验动检证接口调用的示例代码见图A.10。OkHttpClientclient=newOkHttpClient().newBuilder().build();MediaTypemediaType=MediaType.parse("application/json");RequestBodybody=RequestBody.create(mediaType,@"[{\"salesDocumentNo\":\"分销凭证编号\",\"productBarcode\":\"产品编码\",\"productName\":\"产品名称\",\"productCategoryCode\":\"产品分类编码，由动物代码+产品代码+产品类型代码表组成，例如商品猪胴体中温肉分类编码为1010610110102，详细分类代码见附录\",\"productImg\":\"产品图片的网址，多个网址以,分隔\",\"batchCode\":\"批次编码，批次唯一标识，例如（检疫合格证号+轨道号+分割流水号），必填\",\"batch\":\"批次\",\"batchWeight\":\"批次总重量\",\"batchUnit\":\"批次单位(KG，G，默认KG)\",\"batchInNo\":\"批次进货单号\",\r\n\"batchInWeight\":\"批次进货重量\",\"batchInPrice\":\"批次进货单价，人民币（元/KG,元/G）\",\"batchInDate\":\"批次进货日期\",\"batchOutPrice\":\"批次销售单价，人民币（元/KG,元/G）\",\"batchOutDate\":\"批次销售日期\",\"batchOutWeight\":\"批次销售重量\",\"batchCheckReport\":\"批次检验报告，产品报告图片或文件的网址，多张图片以英文,分隔\",\"animalCertNo\":\"动物检疫合格证编号\",\"animalCertType\":\"动物检疫合格证类型（da：动物A证，db：动物B证）\",\"quarantineCertNo\":\"产品检疫合格证编号\",\"quarantineCertType\":\"产品检疫合格证类型（ca：产品A证，cb：产品B证）\",\"producerBaseName\":\"生产/养殖基地名称\",\"producerBaseAddr\":\"生产/养殖基地地址\",\"butcherEntName\":\"屠宰企业名称\",图A.10同步肉品溯源数据并核验动检证接口调用的示例代码\"butcherEntUnifCode\":\"屠宰企业统一社会信用代码\",\"supplierEntName\":\"市场供货企业名称，多个名称以英文;间隔\",\"supplierEntUnifCode\":\"市场供货企业统一社会信用代码，多个代码以英文;间隔\",\"flowtoEntName\":\"流向企业名称，多个名称以英文;间隔\",\"flowtoEntUnifCode\":\"流向企业统一社会信用代码，多个代码以英文;间隔\"，\"qrcodeUrl\":\"分销溯源二维码网址\",\"animalCertSerial\":\"动物检疫合格证流水号\",\"quarantineCertSerial\":\"产品检疫合格证流水号\",\"exHz\":\"附加供货企业，多个企业以英文;间隔\",\"exButcher\":\"附加屠宰企业，多个企业以英文;间隔\",\"exFlowto\":\"附加流向，多个流向以英文;间隔\",\"exAnimalCertUrl\":\"附加动物检疫合格证图片网址，多个网址以英文;间隔\",\"exQuarantineCertUrl\":\"附加产品检疫合格证图片网址，多个网址以英文;间隔\",\"exAnimalCertNo\":\"附加动物检疫证编号，多个编号以英文;间隔\",\"exQuarantineCertNo\":\"附加产品检疫证编号，多个编号以英文;间隔\",\"meatQualityNo\":\"肉品品质检验证编号，多个编号以英文;间隔\",\"meatQualityUrl\":\"肉品品质检验证网址，多个网址以英文;间隔\",\"delFlag\":\"删除标记，默认0为不删除，1为删除，若仅删除数据可只传分销号（salesDocumentNo）和本删除标记\",}]");Requestrequest=newRequest.Builder().url("/mwtrace