海关商品接口文档

模块概述

商品编码（HS Code）管理模块，包含商品管理和商品采集两部分功能。管理页面展示正式数据，支持启用/禁用和变更记录查看；采集页面支持从外部数据源全量采集商品编码信息，并同步到正式表。

接口列表

商品管理

接口名称	请求方式	URL	描述
管理页分页查询	POST	/bc-goods/page	查询正式表商品编码列表
启用/禁用	POST	/bc-goods/enable-or-disable	启用或禁用商品编码
变更记录	GET	/bc-goods/change-log/{id}	查询正式表记录的变更历史

商品采集

接口名称	请求方式	URL	描述
全量采集	POST	/bc-goods/collect-all	触发全量采集任务（后端异步执行）
采集页分页查询	POST	/bc-goods/collect-page	查询采集记录列表
重新采集	POST	/bc-goods/re-collect	对指定记录重新采集详情
批量同步	POST	/bc-goods/batch-sync	将采集数据同步到正式表
同步差异对比	GET	/bc-goods/collect-diff/{collectId}	查看采集数据与正式数据的差异
状态统计	GET	/bc-goods/status-count	获取各状态记录数

一、商品管理接口

1. 管理页分页查询

URL：POST /bc-goods/page

Content-Type：application/x-www-form-urlencoded

请求参数：

字段名	类型	必填	描述
pageNum	Integer	否	页码，默认1
pageSize	Integer	否	每页条数，默认20，最大200
code	String	否	商品编码（模糊搜索）
nameCn	String	否	基础品名（模糊搜索）
enable	Integer	否	是否启用（0:禁用 1:启用）
isExpired	Boolean	否	是否过期筛选
isZeroTaxRefund	Boolean	否	是否0退税筛选

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "current": 1,
    "size": 20,
    "total": 13000,
    "records": [
      {
        "id": 1,
        "code": "0101210010",
        "nameCn": "改良种用的纯种繁殖马",
        "remark": "包括赛马",
        "declarationElements": "1:品名;2:用途;3:品牌类型",
        "legalUnit1": "035-头",
        "legalUnit2": "-",
        "isDangerous": false,
        "supervisionCond": "AB",
        "inspectionCategory": "PQ",
        "taxRefundRate": "0.0",
        "versionNo": "20250519",
        "enable": 1,
        "isExpired": false,
        "createTime": "2025-05-19 10:30:00",
        "updateTime": "2025-05-19 10:30:00"
      }
    ]
  }
}

响应字段说明（records 中每条记录）：

字段名	类型	描述
id	Long	主键
code	String	商品编码(HS Code)
nameCn	String	基础品名(中文)
remark	String	商品备注
declarationElements	String	要素申报规范（已格式化）
legalUnit1	String	法一单位（格式：编码-名称）
legalUnit2	String	法二单位（格式：编码-名称）
isDangerous	Boolean	是否危险品
supervisionCond	String	监管条件代码
inspectionCategory	String	检验检疫类别
taxRefundRate	String	退税率
versionNo	String	版本号(yyyyMMdd)
enable	Integer	是否启用（0:禁用 1:启用）
isExpired	Boolean	是否过期
createTime	String	创建时间
updateTime	String	更新时间

2. 启用/禁用

URL：POST /bc-goods/enable-or-disable

Content-Type：application/json

请求参数：

字段名	类型	必填	描述
id	Long	是	商品编码ID（bc_goods.id）
enable	Integer	是	目标状态（0:禁用 1:启用）

请求示例：

{
  "id": 1,
  "enable": 0
}

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

msg	说明
参数ID不能为空	id为空
商品不存在	id对应记录不存在
启用/禁用状态值不合法	enable值不是0或1

3. 变更记录

URL：GET /bc-goods/change-log/{id}

说明：查询正式表某条记录的历史变更记录。

路径参数：

字段名	类型	必填	描述
id	Long	是	正式表记录ID（bc_goods.id）

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "code": "0101210010",
      "paramId": 100,
      "fieldName": "退税率",
      "oldValue": "9.0",
      "newValue": "13.0",
      "oldVersionNo": "20250115",
      "newVersionNo": "20250519",
      "createByName": "系统自动",
      "createTime": "2025-05-19 10:30:00"
    }
  ]
}

响应字段说明：

字段名	类型	描述
id	Long	日志ID
code	String	商品编码
paramId	Long	正式表记录ID
fieldName	String	变更字段中文名
oldValue	String	原值
newValue	String	新值
oldVersionNo	String	旧版本号
newVersionNo	String	新版本号
createByName	String	变更人名称
createTime	String	变更时间

二、商品采集接口

1. 全量采集

URL：POST /bc-goods/collect-all

说明：触发后台异步全量采集任务，接口立即返回(前端页面使用接口返回的msg做为页面提示)。

请求参数（Query Params）：

字段名	类型	必填	描述
forceRefresh	Boolean	否	是否强制全量刷新，后端默认false，前端无需再传

请求示例：

POST /bc-goods/collect-all
POST /bc-goods/collect-all?forceRefresh=true

响应示例（成功）：

{
  "code": 200,
  "msg": "全量采集任务已提交，正在后台执行，请稍后刷新查看采集进度",
  "data": null
}

响应示例（任务正在执行中）：

{
  "code": 500,
  "msg": "全量采集任务正在执行中，请勿重复触发",
  "data": null
}

2. 采集页分页查询

URL：POST /bc-goods/collect-page

Content-Type：application/x-www-form-urlencoded

请求参数：

字段名	类型	必填	描述
pageNum	Integer	否	页码，默认1
pageSize	Integer	否	每页条数，默认20，最大200
code	String	否	商品编码（模糊搜索）
isExpired	Boolean	否	是否过期筛选
status	Integer	否	采集状态筛选（0-5）

采集状态枚举：

值	含义
0	待采集
1	采集失败
2	待同步
3	已同步
4	无差异
5	采集中

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "current": 1,
    "size": 20,
    "total": 13000,
    "records": [
      {
        "id": 1,
        "code": "0101210010",
        "nameCn": "改良种用的纯种繁殖马",
        "remark": "包括赛马",
        "declarationElements": "1:品名;2:用途;3:品牌类型",
        "legalUnit1": "035-头",
        "legalUnit2": "-",
        "isDangerous": false,
        "supervisionCond": "AB",
        "inspectionCategory": "PQ",
        "taxRefundRate": "0.0",
        "versionNo": "20250519",
        "isExpired": false,
        "status": 3,
        "statusName": "已同步",
        "syncTime": "2025-05-19 10:30:00",
        "collectTime": "2025-05-19 10:25:00",
        "errorMsg": null,
        "createTime": "2025-05-19 10:20:00"
      }
    ]
  }
}

响应字段说明（records 中每条记录）：

字段名	类型	描述
id	Long	采集记录ID
code	String	商品编码(HS Code)
nameCn	String	基础品名(中文)
remark	String	商品备注
declarationElements	String	要素申报规范（已格式化）
legalUnit1	String	法一单位（格式：编码-名称）
legalUnit2	String	法二单位（格式：编码-名称）
isDangerous	Boolean	是否危险品
supervisionCond	String	监管条件代码
inspectionCategory	String	检验检疫类别
taxRefundRate	String	退税率
versionNo	String	版本号(yyyyMMdd)
isExpired	Boolean	是否过期
status	Integer	采集状态码(0-5)
statusName	String	采集状态名称
syncTime	String	同步时间
collectTime	String	采集时间
errorMsg	String	采集失败原因（仅status=1时有值）
createTime	String	创建时间

3. 重新采集

URL：POST /bc-goods/re-collect

Content-Type：application/json

说明：对指定记录重新拉取详情。仅对状态非「待采集」和「采集中」的记录生效。

请求参数：

字段名	类型	必填	描述
ids	List<Long>	是	采集记录ID列表

请求示例：

{
  "ids": [1, 2, 3]
}

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

msg	说明
请先选择商品	ids为空

4. 批量同步

URL：POST /bc-goods/batch-sync

Content-Type：application/json

说明：将采集数据同步到正式表。仅对状态为「待同步」的记录生效。

请求参数：

字段名	类型	必填	描述
ids	List<Long>	是	采集记录ID列表

请求示例：

{
  "ids": [1, 2, 3]
}

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

msg	说明
请先选择商品	ids为空

5. 同步差异对比

URL：GET /bc-goods/collect-diff/{collectId}

说明：查看采集数据与正式表数据的字段差异，用于同步前的确认弹窗。

路径参数：

字段名	类型	必填	描述
collectId	Long	是	采集记录ID

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "collectCode": "0101210010",
    "systemVersionNo": "20250115",
    "collectVersionNo": "20250519",
    "diffs": [
      {
        "fieldName": "基础品名",
        "oldValue": "改良种用的纯种马",
        "newValue": "改良种用的纯种繁殖马"
      },
      {
        "fieldName": "退税率",
        "oldValue": "9.0",
        "newValue": "13.0"
      }
    ]
  }
}

响应字段说明：

字段名	类型	描述
collectCode	String	商品编码
systemVersionNo	String	系统当前版本号（正式表无该编码时为null）
collectVersionNo	String	采集版本号
diffs	List	差异字段列表
diffs[].fieldName	String	变更字段中文名
diffs[].oldValue	String	原值（新增场景为空字符串）
diffs[].newValue	String	新值

6. 状态统计

URL：GET /bc-goods/status-count

说明：获取采集表各状态的记录数，用于页面顶部统计展示和进度轮询。

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 13000,
    "pendingCollect": 500,
    "collecting": 200,
    "collectFailed": 10,
    "pendingSync": 300,
    "synced": 11000,
    "noDiff": 990
  }
}

响应字段说明：

字段名	类型	描述
total	Long	全部记录数
pendingCollect	Long	待采集数量
collecting	Long	采集中数量
collectFailed	Long	采集失败数量
pendingSync	Long	待同步数量
synced	Long	已同步数量
noDiff	Long	无差异数量

海关商品接口文档

模块概述#

接口列表#

商品管理#

商品采集#

一、商品管理接口#

1. 管理页分页查询#

2. 启用/禁用#

3. 变更记录#

二、商品采集接口#

1. 全量采集#

2. 采集页分页查询#

3. 重新采集#

4. 批量同步#

5. 同步差异对比#

6. 状态统计#

模块概述

接口列表

商品管理

商品采集

一、商品管理接口

1. 管理页分页查询

2. 启用/禁用

3. 变更记录

二、商品采集接口

1. 全量采集

2. 采集页分页查询

3. 重新采集

4. 批量同步

5. 同步差异对比

6. 状态统计