Danmo Trade 开发者平台
构建贸易规则应用
面向软件团队的美国 HTS 和贸易措施版本化数据。
01 / 快速开始
几分钟完成第一次请求
公开 API 使用稳定的 v1 契约,生产请求需要 API Key。
- 在 Account 页面创建测试 API Key。
- 只显示一次的 Key 请保存到密钥管理器。
- 调用带来源追溯的端点并检查响应元数据。
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_key03 / 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_status | covered = 已收录在发布数据集;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_review | MVP 中始终为 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_rate | HTS 数据集中的普通税率。 | 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 · count | items 为变化记录列表;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 |
| status | published = 正式发布数据;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_code | USTR 实施代码,标识具体的 Section 301 行动。 | USTR-2018-0003 |
| measures[].rate | Section 301 加征税率。 | 25% |
| measures[].effective_from | Section 301 措施生效日期。 | 2018-09-24 |
| data_version | Section 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_version | API 契约版本,当前为 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 编码和预期结果,以便我们快速复现问题。