Danmo Trade 开发者平台

构建贸易规则应用

面向软件团队的美国 HTS 和贸易措施版本化数据。

01 / 快速开始

几分钟完成第一次请求

公开 API 使用稳定的 v1 契约,生产请求需要 API Key。

  1. 在 Account 页面创建测试 API Key。
  2. 只显示一次的 Key 请保存到密钥管理器。
  3. 调用带来源追溯的端点并检查响应元数据。
curl https://trade.danmo.tech/api/v1/us/tariff-lines/8541.10.00 -H "Authorization: Bearer sk-test-your_key"

02 / 身份认证

测试和生产 Key 分离

测试 Key 用于集成,生产 Key 用于正式业务。Key 只显示一次,不能放在 URL 中。

Authorization: Bearer sk-test-your_key

03 / API 参考

接口少而明确

GET/api/v1/us/tariff-lines/{hs_code}

查询包含版本和来源的 HTS 税则线。

请求参数

参数位置必填说明
hs_code路径是美国 HTS 税则线编码,8-10 位。点号可省略:8541.10.00 与 85411000 解析为同一条记录。未收录编码返回 HTTP 200 且 coverage_status 为 not_covered。85411000

响应字段

字段说明示例
hs_code官方发布的规范 HTS 编码(含点号)。8541.10.00
description来源提供的官方商品描述。Diodes, other than photosensitive or light emitting
unit_of_quantity申报计量单位;"No." 表示按个数计。No.
general_rate普通(最惠国)税率:"Free"、百分比(如 "2.6%"),来源未列税率时为 "Not available"。Free
version记录所属的已发布数据集版本,如 HTS-2026-21。HTS-2026-21
valid_from记录在来源中的生效日期。2026-10-13
coverage_statuscovered = 已收录在发布数据集;not_covered = 当前数据集未收录(HTTP 仍为 200)。covered
source · source_url用于核验的官方来源名称与链接。https://hts.usitc.gov/
retrieved_at · source_document_id采集时间与可追溯的来源文档 ID。usitc:api:getRates:8541
GET/api/v1/trade-measures

按编码、原产国和日期过滤措施。

请求参数

参数位置必填说明
hs_code查询否可选。措施适用的 HTS 编码,匹配时忽略点号。8541.10.00
origin_country查询否可选。原产国 ISO 3166-1 两位码,不区分大小写(如 CN)。CN
effective_on查询否可选。ISO 日期(YYYY-MM-DD)。只返回 effective_from 不晚于该日的措施。2026-10-13

响应字段

字段说明示例
measure_type措施类别,如 section_301 表示 301 条款关税行动。section_301
hs_code官方发布的规范 HTS 编码(含点号)。8541.10.00
origin_country措施适用的原产国(ISO 3166-1 两位码)。CN
rate在普通税率之上加征的税率。25%
effective_from · effective_to生效区间;无截止日期的措施 effective_to 为 null。2024-01-01
source · source_url用于核验的官方来源名称与链接。https://ustr.gov/
POST/api/v1/public/classify

将商品描述分类为 HTS 候选编码。

请求参数

参数位置必填说明
product_description查询是用于分类的自由文本商品描述。Electric toothbrush with rechargeable battery
origin_country查询否可选。适用贸易措施的原产国(默认:CN)。CN
import_date查询否可选。进口日期以确定措施适用性(YYYY-MM-DD)。2026-10-16
attributes.material查询否可选。产品材质(如 plastic、metal、leather)。plastic
attributes.power_type查询否可选。动力类型(如 electric、manual、battery-powered)。electric
attributes.battery查询否可选。电池类型(如 rechargeable、disposable)。rechargeable

响应字段

字段说明示例
query_id唯一的分类查询标识符,用于跟踪。cls_a1b2c3d4e5f6
session_id将会话中相关查询链接在一起的会话 ID。sess_xyz789
candidates[].hts_code分类引擎匹配的 HTS 编码。9603.21.00
candidates[].description匹配编码的官方 HTS 描述。Toothbrushes, whether or not mechanical
candidates[].match_level匹配粒度:high(精确关键词)、medium(部分匹配)、low(弱匹配)。high
candidates[].confidence置信度:high(3+ 原因)、medium(2 个原因)、low(<2 个原因)。high
candidates[].match_reasons[]支持此分类的原因列表(关键词 + 属性匹配)。["keyword: toothbrush", "attribute: electric"]
candidates[].missing_information[]如果提供这些属性可以提高分类准确性。["battery type"]
candidates[].needs_human_reviewMVP 中始终为 true;生产使用建议人工审核。true
disclaimer分类结果仅为建议,不构成海关裁定。Classification results are suggestions only
POST/api/v1/public/hts/batch

批量查询多个 HS 编码及对应措施。

请求参数

参数位置必填说明
hs_codes[]查询是要查询的 HS 编码数组(公开 API 最多 5 个,认证用户最多 20 个)。["8541.10.00", "9603.21.00"]
origin_country查询否可选。原产国以获取额外贸易措施。CN
effective_on查询否可选。措施适用性的日期过滤。2026-10-16

响应字段

字段说明示例
results[].hs_code批量请求中的原始 HS 编码。8541.10.00
results[].coverage_status覆盖状态:covered 或 not_covered。covered
results[].base_rateHTS 数据集中的普通税率。Free
results[].additional_measures[]适用的贸易措施数组(如 Section 301 关税)。[{"type": "section_301", "rate": "25%"}]
total_processed此批次中处理的 HS 编码数量。2
GET/api/v1/changes?since=

发现已经发布的规则变化。

请求参数

参数位置必填说明
since查询否可选。ISO 日期(YYYY-MM-DD)。只返回 published_on 晚于该日的变化;省略则返回全部已发布变化。2026-10-01

响应字段

字段说明示例
items · countitems 为变化记录列表;count 为返回条数。count: 1
items[].change_id稳定的变化标识,可用于去重。hts-2026-21-8541
items[].change_type变化类别,如 version_published 表示新数据版本发布。version_published
items[].published_on发布日期;since 过滤即基于该字段。2026-10-09
items[].effective_on变化的正式生效日期。2026-10-09
items[].version记录所属的已发布数据集版本,如 HTS-2026-21。HTS-2026-21
items[].impact变化的可读摘要。Tariff line updated
items[].source · source_url用于核验的官方来源名称与链接。https://hts.usitc.gov/
GET/api/v1/sources/status

查看数据源新鲜度和状态。

无参数。返回当前活动数据源清单与新鲜度。

响应字段

字段说明示例
source官方来源名称,如 USITC HTS REST API。USITC HTS REST API
version记录所属的已发布数据集版本,如 HTS-2026-21。trade_rules:1
last_synced_at该来源最近一次采集时间。2026-10-13T03:57:00Z
statuspublished = 正式发布数据;demo = 演示样例数据。published
known_delay上游来源已知的发布延迟;未记录时为 null。null
source_url用于核验的官方来源名称与链接。https://hts.usitc.gov/
document_id · checksum · license_status溯源信息:文档 ID、SHA-256 校验和与许可审查状态。usitc:api:getRates:8541
GET/api/v1/section301/check

检查某 HS 编码是否受 Section 301 措施影响。

请求参数

参数位置必填说明
hs_code查询是要检查 Section 301 措施的 HS 编码。8541.10.00

响应字段

字段说明示例
hs_code检查 Section 301 措施的 HS 编码。8541.10.00
measures[].implementation_codeUSTR 实施代码,标识具体的 Section 301 行动。USTR-2018-0003
measures[].rateSection 301 加征税率。25%
measures[].effective_fromSection 301 措施生效日期。2018-09-24
data_versionSection 301 数据集版本标识。section301:2026-10-16

响应包装

所有响应都由 data 和 meta 包装。

{
  "data": { ... },
  "meta": {
    "api_version": "v1",
    "data_version": "trade_rules:1",
    "retrieved_at": "2026-10-13T08:00:00+00:00"
  }
}
字段说明
meta.api_versionAPI 契约版本,当前为 v1。
meta.data_version响应所用已发布数据集的版本标识,每次发布新数据集时递增(如 trade_rules:1);与单条记录内的 version 字段(HTS 修订版本,如 HTS-2026-21)含义不同。未发布版本时为 null。
meta.retrieved_at响应生成时间(UTC,ISO 8601)。

04 / 错误处理

错误信息可操作

每个错误都包含稳定的错误码和请求 ID。

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "request_id": "req_..."
  }
}

coverage_status: not_covered 表示该编码不在当前精选数据集中。

401 表示 API Key 缺失、无效、已撤销或不适用于当前环境。

422 表示请求参数无效。

429 表示当前请求或套餐额度已达到限制。

05 / 覆盖与新鲜度

新鲜度也是响应的一部分

MVP 覆盖精选美国 HTS 和中国原产贸易措施,响应包含版本、获取时间和来源 URL。

  • 覆盖范围为精选美国 HTS 记录和中国原产贸易措施。
  • API 不构成海关裁定或最终税费计算引擎。
  • 已发布记录包含来源、版本和获取时间元数据。
  • 使用 /api/v1/sources/status 检查当前活动数据源状态。

06 / 更新日志

变化清晰可见

2026-10-12 · v1 preview

公开 v1 预览发布,包含来源可追溯的 HTS、贸易措施和变化端点。

2026-10-12 · trade_rules:1

新增 USITC 原始响应保存,支持可回放解析和版本化发布。

FAQ

常见的 API 问题

Danmo Trade API 是什么?
一个用于美国进口报价前核查的 REST API:美国 HTS 税则行、Section 301 贸易措施与版本化规则变更。每条记录都带有来源、版本和获取时间元数据。
数据来自哪些来源?
来自已发布的美国政府数据源:税则行取自 USITC HTS,Section 301 措施取自 USTR。响应包含 source_url 与 data_version,可回溯到具体发布版本。
如何鉴权?
在账户页创建测试 API Key,然后在 Authorization 请求头中以 Bearer token 形式发送。
覆盖哪些 HS 编码?
覆盖精选美国 HTS 记录以及中国原产贸易措施。当前数据集之外的编码会返回 coverage_status: not_covered,而不是给出估算。

07 / 支持

需要接入支持?

请提供请求 ID、HTS 编码和预期结果,以便我们快速复现问题。