Classification + Tariff Calculation API API参考

一次调用，拿到HTS编码和关税。

两个POST接口，单个产品或默认每批120个，附全部字段、错误码和curl示例。

Classification + Tariff Calculation API参考

本页内容

API版本v1 · 基础URL：api.gingercontrol.com

Classification + Tariff Calculation API返回什么？

Classification + Tariff Calculation API（归类与关税计算API）是GingerControl提供的REST API，用于美国HTS编码（美国海关编码）归类和关税查询。您通过POST提交一段纯文本的商品描述及其原产国，API返回HTS编码、General税率和Special优惠税率，以及每一层第99章关税的税号和税率。一个产品用单个产品接口，多个产品用批量接口，默认每次调用120条（可按您的吞吐量申请调整）。API Key（API密钥）线下发放，返回结果用于报关准备，并由持牌报关行复核。

基础URL：https://api.gingercontrol.com
接口：POST /openapi/v1/tariff处理单个产品，POST /openapi/v1/tariff/batch最多处理120个
认证：在X-Api-Key请求头中携带API Key，由GingerControl线下发放
格式：请求体和响应均为JSON

如何获取权限并完成集成？

先阅读下面的接口规范，再预约沟通，按您的调用量申请API Key，然后把结果接入自有系统。

阅读接口规范

开始前请完整阅读下面各个接口的说明，内容涵盖调用方式、输入输出结构、错误码含义和限流规则，可以缩短集成和调试时间。

申请API Key

先预约一次沟通。我们会了解您的调用模式、IP白名单、峰值QPS和延迟要求，然后通过邮件等线下渠道把Key发给您。

集成

大多数团队很快就能完成基础集成，之后更多时间花在把返回数据接入自有系统上。

请妥善保管生产环境Key。现阶段，API Key是计费的唯一依据。

单个产品接口

提交一段商品描述及其原产国，返回HTS编码和关税数据。

POST/openapi/v1/tariffhttps://api.gingercontrol.com

请求头

请求头	必填	含义	用途
`Content-Type`	是	请求体格式，由调用方设置	必须为`application/json`
`X-Api-Key`	是	调用方凭证，由GingerControl线下发放	用于认证、限流和配额控制
`X-Request-Id`	否	请求追踪ID，建议由您的系统生成	用于排障、日志追踪和问题调查；不传时由服务端生成

响应头

响应头	说明	用途
`Content-Type`	始终为`application/json`	响应体格式
`X-Request-Id`	原样返回您传入的值，或由服务端生成	记录下来，便于排障
`Retry-After`	仅随`429 Too Many Requests`返回	重试前需要等待的秒数

请求体

字段	类型	必填	说明
`description`	string	是	商品描述。不能为空，最多10,000个字符
`country_of_origin`	string	是	ISO 3166-1 alpha-2国家代码（代码列表）。也接受`EU`（欧盟）和`UK`（英国）；`GB`按`UK`处理
`extra`	object	否	附加输入。只读取`steel_pour_country`和`aluminum_pour_country`，其他字段忽略
`extra.steel_pour_country`	string	否	钢材熔炼浇铸国（pour country），规则同`country_of_origin`
`extra.aluminum_pour_country`	string	否	铝材熔炼浇铸国，规则同`country_of_origin`

JSON请求示例

{
  "description": "Cotton knit short sleeve T-shirt",
  "country_of_origin": "DE",
  "extra": {
    "steel_pour_country": "IT",
    "aluminum_pour_country": "FR"
  }
}

成功响应

字段	类型	说明
`hts_code`	string	该产品的HTS编码。通常为10位；拆分编码产品可能返回8位上级编码，例如`9101.11.40`
`tariffs`	object或null	该产品的关税数据。拆分编码产品可能为`null`
`tariffs.general_rate`	string或null	General税率，可理解为最惠国税率
`tariffs.special_rate`	string或null	Special优惠税率，经过轻度规范化（例如去掉末尾的括号注释）
`tariffs.<module_key>`	array	该模块的第99章条目，每项为`{code, rate}`
`tariffs.<module_key>[].code`	string	第99章税号，例如`9903.85.08`
`tariffs.<module_key>[].rate`	string	百分比形式的税率字符串，例如`25%`
`components`	array	拆分编码产品的组件；普通产品不返回此字段
`components[].hts_code`	string	组件HTS编码，始终为10位
`components[].tariffs`	object或null	该组件的关税数据

JSON响应示例

{
  "hts_code": "6109.10.0012",
  "tariffs": {
    "general_rate": "16.5%",
    "special_rate": "Free",
    "Section 301": [],
    "Section 232 - Metals": []
  }
}

tariffs中的每个模块键（这里是Section 301和Section 232 - Metals）都对应一个{code, rate}条目列表。列表为空，表示该模块没有适用于此产品的第99章条目。

错误响应

字段	类型	说明
`detail`	object	错误对象
`detail.code`	string	错误码，供程序处理
`detail.message`	string	错误信息，用于日志和排障

JSON错误示例

{
  "detail": {
    "code": "invalid_request",
    "message": "Invalid request body."
  }
}

错误码

HTTP状态码	错误码	含义
`401 Unauthorized`	`missing_api_key`	请求头中未提供`X-Api-Key`
`401 Unauthorized`	`invalid_api_key`	API Key校验失败
`403 Forbidden`	`api_key_revoked`	API Key已被吊销
`403 Forbidden`	`client_disabled`	调用方账号已被停用
`422 Unprocessable Entity`	`invalid_request`	请求体格式错误、缺少字段、字段类型错误，或取值不符合接口规范
`429 Too Many Requests`	`request_rate_limited`	触发了请求级保护
`429 Too Many Requests`	`item_rate_limited`	触发了条目级配额保护
`500 Internal Server Error`	`classification_failed`	HTS识别失败
`500 Internal Server Error`	`calculator_failed`	关税计算失败
`500 Internal Server Error`	`internal_error`	发生其他内部错误

用curl试调用

把YOUR_API_KEY换成我们线下发给您的Key，然后直接运行命令。

cURL单个产品调用

curl -X POST 'https://api.gingercontrol.com/openapi/v1/tariff' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Request-Id: manual-single-001' \
  -d '{
    "description": "Cotton knit short sleeve T-shirt",
    "country_of_origin": "DE",
    "extra": {
      "steel_pour_country": "IT",
      "aluminum_pour_country": "FR"
    }
  }'

批量接口

一次调用最多提交120个产品，每个都带您自己的item_id；结果按提交顺序返回，各带自己的状态。

POST/openapi/v1/tariff/batchhttps://api.gingercontrol.com

请求头与响应头

批量接口接受与单个产品接口相同的请求头，也返回相同的响应头：传入Content-Type、X-Api-Key和可选的X-Request-Id；返回Content-Type、X-Request-Id，遇到429时还有Retry-After。

请求体

字段	类型	必填	说明
`items`	array	是	要处理的产品；当前版本最多120项
`items[].item_id`	string	是	您自己的标识，用于将每条结果与您的记录对应。同一请求内必须唯一
`items[].description`	string	是	商品描述。不能为空，最多10,000个字符
`items[].country_of_origin`	string	是	ISO 3166-1 alpha-2国家代码。也接受`EU`和`UK`；`GB`按`UK`处理
`items[].extra`	object	否	只读取`steel_pour_country`和`aluminum_pour_country`，其他字段忽略
`items[].extra.steel_pour_country`	string	否	钢材熔炼浇铸国，规则同`country_of_origin`
`items[].extra.aluminum_pour_country`	string	否	铝材熔炼浇铸国，规则同`country_of_origin`

JSON批量请求

{
  "items": [
    {
      "item_id": "SKU-DE-001",
      "description": "Cotton knit short sleeve T-shirt",
      "country_of_origin": "DE",
      "extra": {
        "steel_pour_country": "IT"
      }
    },
    {
      "item_id": "SKU-FR-002",
      "description": "Cotton crew neck T-shirt",
      "country_of_origin": "FR",
      "extra": {}
    }
  ]
}

成功响应

字段	类型	说明
`items`	array	结果，顺序与请求一致
`items[].item_id`	string	您的标识，用于核对结果
`items[].status`	string	`ok`或`failed`
`items[].hts_code`	string	成功项的HTS编码。通常为10位；拆分编码产品可能返回8位上级编码。仅在`status`为`ok`时返回
`items[].tariffs`	object或null	成功项的关税数据；拆分编码产品可能为`null`。仅在`status`为`ok`时返回
`items[].tariffs.general_rate`	string或null	General税率，可理解为最惠国税率
`items[].tariffs.special_rate`	string或null	Special优惠税率，经过轻度规范化
`items[].tariffs.<module_key>`	array	模块条目，每项为`{code, rate}`
`items[].tariffs.<module_key>[].code`	string	第99章税号
`items[].tariffs.<module_key>[].rate`	string	税率
`items[].components`	array	拆分编码产品的组件；普通产品不返回此字段。仅在`status`为`ok`时返回
`items[].components[].hts_code`	string	组件HTS编码，始终为10位
`items[].components[].tariffs`	object或null	该组件的关税数据
`items[].code`	string	失败项的错误码。仅在`status`为`failed`时返回
`summary`	object	批量请求汇总
`summary.total`	integer	本次请求的条目数
`summary.succeeded`	integer	成功的条目数
`summary.failed`	integer	失败的条目数

JSON批量响应

{
  "items": [
    {
      "item_id": "SKU-DE-001",
      "status": "ok",
      "hts_code": "6109.10.0012",
      "tariffs": {
        "general_rate": "16.5%",
        "special_rate": "Free",
        "Section 301": [],
        "Section 232 - Metals": []
      }
    },
    {
      "item_id": "SKU-FR-002",
      "status": "ok",
      "hts_code": "6109.10.0004",
      "tariffs": {
        "general_rate": "16.5%",
        "special_rate": "Free",
        "Section 301": [],
        "Section 232 - Metals": []
      }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

错误响应

批量级错误使用与单个产品接口相同的detail对象，包含detail.code和detail.message。

JSON批量错误

{
  "detail": {
    "code": "item_rate_limited",
    "message": "Item quota exceeded."
  }
}

错误码

批量级错误会让整个请求失败：

HTTP状态码	错误码	含义
`401 Unauthorized`	`missing_api_key`	请求头中未提供`X-Api-Key`
`401 Unauthorized`	`invalid_api_key`	API Key校验失败
`403 Forbidden`	`api_key_revoked`	API Key已被吊销
`403 Forbidden`	`client_disabled`	调用方账号已被停用
`422 Unprocessable Entity`	`invalid_request`	顶层结构无效、`item_id`重复、缺少字段、字段类型错误，或取值不符合接口规范
`429 Too Many Requests`	`request_rate_limited`	触发了请求级保护
`429 Too Many Requests`	`item_rate_limited`	触发了条目级配额保护
`500 Internal Server Error`	`internal_error`	发生其他批量级内部错误

条目级失败会在成功响应中返回：该条目标为status: failed，并附code：

错误码	含义
`classification_failed`	该条目HTS识别失败
`calculator_failed`	该条目关税计算失败
`internal_error`	该条目发生其他内部错误

用curl试调用

把YOUR_API_KEY换成我们线下发给您的Key，然后直接运行命令。

cURL批量调用

curl -X POST 'https://api.gingercontrol.com/openapi/v1/tariff/batch' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Request-Id: manual-batch-001' \
  -d '{
    "items": [
      {
        "item_id": "SKU-DE-001",
        "description": "Cotton knit short sleeve T-shirt",
        "country_of_origin": "DE",
        "extra": {
          "steel_pour_country": "IT"
        }
      },
      {
        "item_id": "SKU-FR-002",
        "description": "Cotton crew neck T-shirt",
        "country_of_origin": "FR",
        "extra": {}
      }
    ]
  }'