兽药追溯系统数据接口规范

前言

本文件按照 GB/T 1.1—2020《标准化工作导则 第 1 部分：标准化文件的结构和起草规则》的规定起草。

请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。

本文件由云南省农业农村厅提出。

本文件由云南省农业标准化专业技术委员会（YNTC07）归口。

本文件起草单位：云南省动物卫生监督所、武汉至为科技有限公司、云南省畜牧兽医科学院、怒江州动物卫生监督所、玉溪市动物卫生监督与疫病预防控制中心。

本文件主要起草人：尹红斌、张永仙、朱尤帅、钱朝海、翟祥波、和滕、乔玉洁、李素琳、赵智勇、李健平、张斌、洪瑞凤、吴小娟、施亚琪、郑欢莉。

1 范围

本文件规定了兽药追溯系统数据接口的设计原则、数据对接范围、数据接口方式、接口列表、接口测试及安全与隐私保护等内容。

本文件适用于对兽药系统的流通、使用、监管及数据接口的调用。

2 规范性引用文件

本文件没有规范性引用文件。

3 术语和定义

下列术语和定义适用于本文件。

3.1 数据接口 Data Interface

以电子文件的形式实现，计算机软件系统之间传送数据、交换信息的接口。

4 数据接口设计原则

4.1 标准化原则

接口设计应遵循国家和行业标准，确保数据的兼容性和一致性。

4.2 安全性原则

采用加密技术和访问控制策略，保护数据免遭未授权访问或篡改。

4.3 可扩展性原则

接口应具备良好的扩展能力，以适应未来业务发展和技术进步。

4.4 高效性原则

优化数据处理流程，减少延迟，提高响应速度。

4.5 开放性原则

符合产业习惯，兼容主流开源接口，减小接口定制化带来的重新设计、适配成本。

4.6 易用性原则

尽可能设计成抽象程度高、屏蔽底层实现、语法易理解的接口。

5 数据对接范围

5.1 兽药经营企业数据

兽药经营企业数据及说明见附录 A 表 A.1。

5.2 兽药采购数据

兽药采购数据及说明见附录 A 表 A.2。

5.3 兽药销售数据

兽药销售数据及说明见附录 A 表 A.3。

6 数据接口方式

6.1 调用方身份要求

应申请对应 appid（应用唯一标识）和 appsecret（私钥）。

6.2 接口传输要求

采用 HTTPS 协议，接口使用 JSON 传输数据。

6.3 接口要求

API 接口应符合以下要求：

a) 接口名称：兽药经营企业；

b) 接口描述：调用方需申请对应 appid 和 appsecret，获取兽药经营企业列表；

c) 接口地址：接口调用的地址，如 https://{域名}:{端口}/api/queryQuarantine；

d) 请求方式：POST；

e) 接口标识符：/api/queryQuarantine；

f) 请求参数设计：

1. 在请求参数中，添加 appid 和 timestamp，所有参数按照 ASCII 码从小到大排序；

2. 使用 HMAC-SHA256 算法对排序后的字符串和 appsecret 进行加密生成签名 sign；

3. 调用方需要将请求头 header 添加 appid、sign 和 timestamp。

g) 返回数据的参数结构说明见表 1；

h) 接口响应码及状态说明见表 2。

表 1 返回参数表基本结构

参数名称	数据类型	是否非空	描述
success	boolean	是	接口调用结果
code	number	是	接口响应码，见表 2
message	string	否	接口提示信息
total	number	是	查询到的数据总条数，可用于支持数组数据分页
page	number	是	返回数据的当前页码
size	number	是	返回数据的条数
result	array	是	接口调用成功后，返回的数据集
enterprise	object	是	接口调用成功后，返回的兽药企业信息对象

表 2 接口响应码及状态说明

响应码	状态说明
200	服务器已成功处理请求
401	未获得登录授权或令牌失效
403	服务器拒绝请求
404	服务器找不到请求的接口或页面
500	服务器遇到错误，无法完成请求
502	服务器作为网关或代理，从上游服务器收到无效响应
503	服务器目前无法使用（由于超载或停机维护）
504	服务器作为网关或代理，但是没有及时从上游服务器收到请求

7 接口列表

7.1 兽药经营企业数据

兽药经营企业数据符合以下要求：

a) 接口名称：兽药经营企业；

b) 接口描述：根据附录 B 参数，获取兽药经营企业列表；

c) 接口地址：https://{域名}:{端口}/api/Counterpart/GetNewGrid；

d) 请求方式：POST；

e) 请求参数设计：

1. 在请求参数中，添加 appid 和 timestamp，所有参数按照 ASCII 码从小到大排序；

2. 使用 HMAC-SHA256 算法对排序后的字符串和 appsecret 进行加密生成签名 sign；

3. 调用方需要将请求头 header 添加 appid、sign 和 timestamp。

f) 接口标识符：/api/Counterpart/GetNewGrid；

g) 请求示例，见附录 B。

7.2 兽药采购数据

兽药采购数据符合以下要求：

a) 接口名称：获取兽药采购记录；

b) 接口描述：根据附录 C 参数，获取兽药采购记录；

c) 接口地址：https://{域名}:{端口}/api/management/jxc_WareHouse_GSP/grid；

d) 请求方式：POST；

e) 请求参数设计：

1. 在请求参数中，添加 appid 和 timestamp，所有参数按照 ASCII 码从小到大排序；

2. 使用 HMAC-SHA256 算法对排序后的字符串和 appsecret 进行加密生成签名 sign；

3. 调用方需要将请求头 header 添加 appid、sign 和 timestamp。

f) 接口标识符：/api/management/jxc_WareHouse_GSP/grid；

g) 请求示例，见附录 C。

7.3 兽药销售数据

兽药销售数据符合以下要求：

a) 接口名称：获取兽药销售记录；

b) 接口描述：根据附录 D 参数，获取兽药销售记录；

c) 接口地址：https://{域名}:{端口}/api/management/jxc_WareHouse_GSP/grid；

d) 请求方式：POST；

e) 请求参数设计：

1. 在请求参数中，添加 appid 和 timestamp，所有参数按照 ASCII 码从小到大排序；

2. 使用 HMAC-SHA256 算法对排序后的字符串和 appsecret 进行加密生成签名 sign；

3. 调用方需要将请求头 header 添加 appid、sign 和 timestamp。

f) 接口标识符：/api/management/jxc_WareHouse_GSP/grid；

g) 请求示例，见附录 D。

8 接口测试

8.1 测试方法

提供测试接口地址，接口使用 https 传输协议交互，使用 postman 调用接口测试。

8.2 测试过程

按照文档要求封装接口参数，生成接口签名，调用接口。

8.3 测试指标

接口返回结果，结果与预期一致，接口的响应时间应在可接受的范围内（单条查询数据 3 秒以内），对入参合规性做校验。

9 安全与隐私保护

9.1

接口访问需经过身份验证，针对业务开放相关接口。

9.2

对敏感信息如身份证号、养殖场编号、申请单位编号等应进行脱敏处理。

9.3

在数据传输过程中按国家规定的加密算法。

附录A

（资料性）

数据对接范围

A.1 兽药经营企业数据及说明

兽药经营企业数据及说明见表 A.1。

表 A.1 兽药经营企业数据及说明

序号	数据项名称	数据类型	字节	备注
1	cp_full_name	string	200	兽药经营企业名称
2	area_fullname	string	200	省市区乡镇
3	cp_address	string	200	详细地址
4	yb	string	20	邮编
5	build_date	datetime	20	成立时间
6	credit_code	string	30	统一社会信用代码
7	responsor	string	50	法人代表
8	id_no	string	50	身份证号
9	responsory_phone	string	20	法人联系电话
10	jyfw	string	200	经营范围
11	jyxkz_jylx	string	20	经营许可证经营类型
12	xsms	string	20	销售模式
13	employee_num	number	10	职工人数
14	cp_address	string	200	经营地址
15	jysite_area	number	10	经营场所面积
16	cangchu_adress	string	200	仓储地址
17	storage_area	number	10	仓储面积
18	contactor	string	50	仓储负责人
19	tel_no	string	20	仓储负责人电话
20	responsor	string	50	质量负责人
21	responsory_phone	string	20	质量负责人电话

A.2 兽药采购数据及说明

兽药采购数据及说明见表 A.2。

表 A.2 兽药采购数据及说明

序号	数据项名称	数据类型	字节	备注
1	org_name	string	200	兽药经营企业名称
2	supplier_name	string	200	供应商名称
3	in_date	datetime	20	入库日期
4	inman_name	string	50	录入人
5	create_time	datetime	20	录入时间
6	remark	string	200	备注
7	pizhunwenhao	string	100	批准文号
8	good_name	string	200	兽药名称
9	good_spec	string	100	规格
10	in_qty	number	10	入库数量
11	unit	string	20	数量单位
12	batch	string	50	批号
13	scrq	datetime	20	生产日期
14	expiry_date	datetime	20	有效期至

A.3 兽药销售数据及说明

兽药销售数据及说明见表 A.3。

表 A.3 兽药销售数据及说明

序号	数据项名称	数据类型	字节	备注
1	org_name	string	200	兽药经营企业名称
2	supplier_name	string	200	客户名称
3	in_date	datetime	20	入库日期
4	inman_name	string	50	录入人
5	create_time	datetime	20	录入时间
6	remark	string	200	备注
7	pizhunwenhao	string	100	批准文号
8	good_name	string	200	兽药名称
9	good_spec	string	100	规格
10	in_qty	number	10	入库数量
11	unit	string	20	数量单位
12	batch	string	50	批号
13	scrq	datetime	20	生产日期
14	expiry_date	datetime	20	有效期至

附录B

（资料性）

兽药经营企业接口列表

B.1 兽药经营企业接口列表输入参数

兽药经营企业接口列表输入参数见表 B.1。

表 B.1 兽药经营企业接口列表输入参数表

分组	输入参数	是否非空	数据类型	字节	说明
参数说明	page	是	number	10	页码
参数说明	size	是	number	10	返回数据的条数
参数说明	sortorder	否	string	10	排序类型 ASC/DESC
参数说明	cp_name	否	string	200	兽药经营企业名称
参数说明	contactor	否	string	50	联系人名称
参数说明	tel_no	否	string	20	电话号码
参数说明	area_id	否	string	36	区域 ID
参数说明	t_cp_state_val	否	string	2	状态 0 关停 1 正常
参数说明	t_audit_state_val	否	string	2	审核状态 0 未审核 1 初审通过 2 审核通过
参数说明	appid	是	string	50	应用 id
参数说明	timestamp	是	number	10	时间戳
header	appid	是	string	50	应用 id
header	sign	是	string	100	签名
header	timestamp	是	number	10	时间戳

B.2 请求消息示例

请求消息应以正确的形式表示，见示例。

示例：

URL:/api/Counterpart/GetNewGrid?
appid=your_appid&area_id=00000000-0000-0000-0000-000000000021&contactor=&cp_name=&page=1&size=20&sortorder=ASC&t_audit_state_val=&t_cp_state_val=3&tel_no=&timestamp=1609459200

B.3 兽药经营企业接口列表输出参数

兽药经营企业接口列表输出参数见表 B.2。

表 B.2 兽药经营企业接口列表输出参数表

返回对象	返回参数	是否非空	数据类型	字节	说明
result	area_code	是	string	20	区域 code
result	area_fullname	是	string	100	区域名称
result	area_id	是	string	36	区域 id
result	contactor	是	string	50	联系人
result	cp_full_name	是	string	100	兽药经营企业全称
result	cp_id	是	string	36	兽药经营企业 id
result	cp_name	是	string	200	兽药经营企业
result	cp_statename	是	string	20	经营状态
result	cp_type_name	是	string	50	监管对象类型
result	cp_address	是	string	150	地址
result	create_time	是	datetime	20	创建时间
result	create_user	是	string	50	创建人
result	datafrom	是	string	20	数据来源
result	doc_sn	是	string	50	生产经营编码
result	id_no	是	string	50	身份证编码
result	latitude	是	string	20	经度
result	longtitude	是	string	20	纬度
result	responsor	是	string	50	负责人
result	tel_no	是	string	20	电话
result	xmj_id	是	string	80	畜牧局 id
result	xmj_user	是	string	80	畜牧局账号
result	xmj_pwd	是	string	80	畜牧局密码

附录C

（资料性）

获取兽药采购记录接口列表

C.1 兽药采购记录接口列表输入参数

获取兽药采购记录接口列表输入参数见表 C.1。

表 C.1 兽药采购记录接口列表输入参数表

分组	输入参数	是否非空	数据类型	字节	说明
参数说明	page	是	number	10	页码
参数说明	size	是	number	10	返回数据的条数
参数说明	sort_name	否	string	50	排序字段
参数说明	sortorder	否	string	10	排序类型 ASC/DESC
参数说明	enter_name	否	string	200	兽药经营企业名称
参数说明	credit_code	否	string	30	统一社会信用代码
参数说明	contactor	否	string	50	联系人名称
参数说明	id_no	否	string	50	身份证号
参数说明	supplier_name	否	string	200	供应商名称
参数说明	start_date	否	datetime	20	入库日期起
参数说明	end_date	否	datetime	20	入库日期止
参数说明	data_year	否	datetime	20	入库年份
参数说明	area_id	否	string	36	区域 ID
参数说明	s_type	否	string	10	R101 代表采购入库 C101 销售出库
参数说明	upload_status	否	string	10	0 未上传 3 上传失败 2 上传成功 1 上传中
参数说明	scqy	否	string	50	生产企业
参数说明	goods_name	否	string	50	药品名称
参数说明	pizhunwenhao	否	string	50	批准证号
参数说明	pihao	否	string	50	批号
参数说明	type	否	string	10	固定值 GSP
header	appid	是	string	50	应用 ID
header	sign	是	string	100	签名
header	timestamp	是	number	10	时间戳

C.2 请求消息示例

请求消息应以正确的形式表示，见示例。

示例：

URL:/api/management/jxc_WareHouse_GSP/grid?
appid=your_appid&area_id=00000000-0000-0000-0000-000000000021&contactor=&credit_code=&data_year=&end_date=&enter_name=&goods_name=&id_no=&pihao=&pizhunwenhao=&scqy=&s_type=&size=20&sort_name=&sortorder=&start_date=&supply_name=&timestamp=1609459200&type=&upload_status=&page=1

C.3 兽药采购记录接口列表输出参数

获取兽药采购记录接口列表输出参数见表 C.2。

表 C.2 获取兽药采购记录接口列表输出参数表

返回对象	返回参数	是否非空	数据类型	字节	说明
result	create_time	否	datetime	20	创建时间
result	create_user	否	string	50	创建人
result	datasources	否	string	20	数据来源 App
result	inman_name	否	string	50	入库人
result	in_no	否	string	50	流水号
result	remark	否	string	200	备注
result	supplier_name	否	string	100	供应商
result	upload_result	否	string	20	上传结果
result	ssq	否	string	50	省市区
result	tel_no	否	string	20	电话
result	in_date	否	datetime	20	采购时间
result	org_name	否	string	100	机构
result	total_ammont	否	number	20	总金额

附录D

（资料性）

获取兽药销售记录接口列表

D.1 兽药销售记录接口列表输入参数

获取兽药销售记录接口列表输入参数见表 D.1。

表 D.1 获取兽药销售记录接口列表输入参数表

分组	输入参数	是否非空	数据类型	字节	说明
参数说明	page	是	number	10	页码
参数说明	size	是	number	10	返回数据的条数
参数说明	sort_name	否	string	50	排序字段
参数说明	sortorder	否	string	10	排序类型 ASC/DESC
参数说明	enter_name	否	string	200	兽药经营企业名称
参数说明	contactor	否	string	50	联系人名称
参数说明	supplier_name	否	string	200	客户名称
参数说明	start_date	否	datetime	20	入库日期起
参数说明	end_date	否	datetime	20	入库日期止
参数说明	data_year	否	datetime	20	入库年份
参数说明	area_id	否	string	36	区域 ID
参数说明	s_type	否	string	10	R101 代表采购入库 C101 销售出库
参数说明	upload_status	否	string	10	0 未上传 3 上传失败 2 上传成功 1 上传中
参数说明	scqy	否	string	50	生产企业
参数说明	goods_name	否	string	50	药品名称
参数说明	pizhunwenhao	否	string	50	批准证号
参数说明	pihao	否	string	50	批号
参数说明	type	否	string	10	固定值 GSP
header	appid	是	string	50	应用 ID
header	sign	是	string	100	签名
header	timestamp	是	number	10	时间戳

D.2 请求消息示例

请求消息应以正确的形式表示，见示例。

示例：

URL:/api/management/jxc_WareHouse_GSP/grid?
appid=your_appid&area_id=00000000-0000-0000-0000-000000000021&contactor=&data_year=&end_date=&enter_name=&goods_name=&id_no=&pihao=&pizhunwenhao=&scqy=&s_type=&size=20&sort_name=&sortorder=ASC&start_date=&supply_name=&timestamp=1609459200&type=&upload_status=&page=1

D.3 兽药销售记录接口列表输出参数

获取兽药销售记录接口列表输出参数见表 D.2。

表 D.2 获取兽药销售记录接口列表输出参数表

返回对象	返回参数	是否非空	数据类型	字节	说明
result	create_date	否	datetime	20	创建时间
result	create_man	否	string	50	创建人
result	datasources	否	string	20	数据来源 App
result	inman_name	否	string	50	入库人
result	in_no	否	string	50	流水号
result	remark	否	string	200	备注
result	supplier_name	否	string	100	供应商
result	upload_result	否	string	20	上传结果
result	ssq	否	string	50	省市区
result	tel_no	否	string	20	电话
result	in_date	否	datetime	20	采购时间
result	org_name	否	string	100	机构
result	recipe_path	否	string	200	http 图片下载路径
result	total_ammont	否	number	20	总金额

原文链接：全国标准信息公共服务平台《兽药追溯系统数据接口规范》