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

版本提示：本标准已于2026年4月29日废止。本页保留废止前原文供历史查阅。[查看官方标准状态](https://std.samr.gov.cn/db/search/stdDBDetailed?id=38FDD8BFE55F41ADE06397BE0A0AF80D)

## 前言

本文件按照 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。

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

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

## 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。

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

  - 列1：数据项名称：tel_no
  - 列2：数据类型：string
  - 列3：字节：20
  - 列4：备注：仓储负责人电话
- 行名：20
  - 列1：数据项名称：responsor
  - 列2：数据类型：string
  - 列3：字节：50
  - 列4：备注：质量负责人
- 行名：21
  - 列1：数据项名称：responsory_phone
  - 列2：数据类型：string
  - 列3：字节：20
  - 列4：备注：质量负责人电话

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

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

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

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

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

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

## 附录B

（资料性）

兽药经营企业接口列表

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

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

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

### B.2 请求消息示例

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

示例：

```text
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。

- 行名：result
  - 列1：返回参数：area_code
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：20
  - 列5：说明：区域 code
- 行名：result
  - 列1：返回参数：area_fullname
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：100
  - 列5：说明：区域名称
- 行名：result
  - 列1：返回参数：area_id
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：36
  - 列5：说明：区域 id
- 行名：result
  - 列1：返回参数：contactor
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：50
  - 列5：说明：联系人
- 行名：result
  - 列1：返回参数：cp_full_name
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：100
  - 列5：说明：兽药经营企业全称
- 行名：result
  - 列1：返回参数：cp_id
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：36
  - 列5：说明：兽药经营企业 id
- 行名：result
  - 列1：返回参数：cp_name
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：200
  - 列5：说明：兽药经营企业
- 行名：result
  - 列1：返回参数：cp_statename
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：20
  - 列5：说明：经营状态
- 行名：result
  - 列1：返回参数：cp_type_name
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：50
  - 列5：说明：监管对象类型
- 行名：result
  - 列1：返回参数：cp_address
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：150
  - 列5：说明：地址
- 行名：result
  - 列1：返回参数：create_time
  - 列2：是否非空：是
  - 列3：数据类型：datetime
  - 列4：字节：20
  - 列5：说明：创建时间
- 行名：result
  - 列1：返回参数：create_user
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：50
  - 列5：说明：创建人
- 行名：result
  - 列1：返回参数：datafrom
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：20
  - 列5：说明：数据来源
- 行名：result

  - 列1：返回参数：doc_sn
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：50
  - 列5：说明：生产经营编码
- 行名：result
  - 列1：返回参数：id_no
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：50
  - 列5：说明：身份证编码
- 行名：result
  - 列1：返回参数：latitude
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：20
  - 列5：说明：经度
- 行名：result
  - 列1：返回参数：longtitude
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：20
  - 列5：说明：纬度
- 行名：result
  - 列1：返回参数：responsor
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：50
  - 列5：说明：负责人
- 行名：result
  - 列1：返回参数：tel_no
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：20
  - 列5：说明：电话
- 行名：result
  - 列1：返回参数：xmj_id
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：80
  - 列5：说明：畜牧局 id
- 行名：result
  - 列1：返回参数：xmj_user
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：80
  - 列5：说明：畜牧局账号
- 行名：result
  - 列1：返回参数：xmj_pwd
  - 列2：是否非空：是
  - 列3：数据类型：string
  - 列4：字节：80
  - 列5：说明：畜牧局密码

## 附录C

（资料性）

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

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

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

- 行名：参数说明
  - 列1：输入参数：page
  - 列2：是否非空：是
  - 列3：数据类型：number
  - 列4：字节：10
  - 列5：说明：页码
- 行名：参数说明
  - 列1：输入参数：size
  - 列2：是否非空：是
  - 列3：数据类型：number
  - 列4：字节：10
  - 列5：说明：返回数据的条数
- 行名：参数说明
  - 列1：输入参数：sort_name
  - 列2：是否非空：否
  - 列3：数据类型：string
  - 列4：字节：50
  - 列5：说明：排序字段
- 行名：参数说明
  - 列1：输入参数：sortorder
  - 列2：是否非空：否
  - 列3：数据类型：string
  - 列4：字节：10
  - 列5：说明：排序类型 ASC/DESC
- 行名：参数说明
  - 列1：输入参数：enter_name
  - 列2：是否非空：否
  - 列3：数据类型：string
  - 列4：字节：200
  - 列5：说明：兽药经营企业名称
- 行名：参数说明
  - 列1：输入参数：credit_code
  - 列2：是否非空：否
  - 列3：数据类型