Tariffin

REST API 文档

Beta 全免费

Tariffin 提供 4 个核心 REST 接口：AI 归类、落地成本、关税查询、文本翻译。Beta 阶段对所有登录用户免费开放，无月度调用上限。

1. 鉴权（必填）

所有 API 都要求注册账号 + 签发密钥后才能调用,不接受匿名访问。在 Dashboard 中签发一把 API 密钥,把它放进 Authorization 请求头:

Authorization: Bearer tfk_xxxxxxxxxxxxxxxxxxxxxxxx

缺少密钥的请求会返回 HTTP 401。网页 UI 调用同一批 API 时会自动带上你的登录 cookie,无需额外密钥。

去签发密钥

2. 速率限制

端点API 密钥（按 key）登录会话（按用户）
/api/classify60 / min30 / min
/api/landed-cost60 / min30 / min
/api/tariff/{country}/{hs}120 / min60 / min
/api/translate60 / min30 / min

未登录或未带 API 密钥的请求一律返回 HTTP 401。超出速率限制时返回 HTTP 429,并在 retry-after 响应头中给出秒数,请使用指数退避重试。

3. 端点详情

POST
/api/classify

AI HS 编码归类

输入任意语言的商品描述，返回目标国家 6 到 10 位 HS 编码、置信度和归类推理。

JSON 请求体

{
  "query": "Portable bluetooth speaker, plastic housing, USB-C",
  "destination": "US"
}

cURL

curl -X POST https://tariffin.com/api/classify \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_API_KEY" \
  -d '{"query":"Portable bluetooth speaker","destination":"US"}'

响应示例

{
  "hs": "851829",
  "confidence": 0.92,
  "reasoning": "…",
  "candidates": [
    { "hs": "851829", "score": 0.92, "title": "Other loudspeakers" }
  ],
  "rate_limit": { "remaining": 59, "reset_at": "2026-05-26T01:23:45.000Z" }
}
POST
/api/landed-cost

落地成本计算

根据申报价值、运费、保险费、贸易术语，计算 MFN 关税、FTA 优惠、增值税/消费税以及国家专属附加费的总落地成本。

JSON 请求体

{
  "hs": "851829",
  "destination": "US",
  "origin": "CN",
  "declaredValueUsd": 1000,
  "freightUsd": 80,
  "insuranceUsd": 12,
  "incoterm": "FOB"
}

cURL

curl -X POST https://tariffin.com/api/landed-cost \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_API_KEY" \
  -d '{"hs":"851829","destination":"US","origin":"CN","declaredValueUsd":1000,"freightUsd":80,"incoterm":"FOB"}'

响应示例

{
  "totals": {
    "dutyUsd": 25.6,
    "vatUsd": 0,
    "landedCostUsd": 1117.6
  },
  "breakdown": {
    "mfnRate": 0.024,
    "ftaRate": null,
    "vatRate": 0
  },
  "tariff": { "hs": "851829", "mfn": 0.024, "verifiedAt": "2026-05-25T..." }
}
GET
/api/tariff/{country}/{hs}

关税明细查询

查询指定 HS 编码在指定目的地的关税明细，同时返回该 HS 在 13 个国家的对照矩阵。

URL 路径参数

country  ISO-2 country code, e.g. US, CN, EU, UK
hs       6-digit HS code, e.g. 851829

cURL

curl https://tariffin.com/api/tariff/US/851829 \
  -H "authorization: Bearer YOUR_API_KEY"

响应示例

{
  "hs": { "code": "851829", "title": "Other loudspeakers" },
  "country": { "code": "US", "name": "United States" },
  "tariff": {
    "mfn": 0.024,
    "fta": null,
    "vat": 0,
    "sourceUrl": "https://hts.usitc.gov/...",
    "verifiedAt": "2026-05-25T..."
  },
  "other_countries": [
    { "country": "CN", "mfn": 0.10 }, ...
  ]
}
POST
/api/translate

商品描述翻译

把任意输入文本同时翻译成英文与简体中文，便于在归类前先做文本规范化。

JSON 请求体

{
  "text": "便携蓝牙音箱，塑料外壳，USB-C 接口"
}

cURL

curl -X POST https://tariffin.com/api/translate \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_API_KEY" \
  -d '{"text":"便携蓝牙音箱"}'

响应示例

{
  "en": "Portable bluetooth speaker",
  "zh": "便携蓝牙音箱"
}

错误返回

所有端点出错时返回标准 JSON：

{ "error": "unauthorized", "message": "Authentication required...", "docs": "https://tariffin.com/api-docs" }
{ "error": "invalid_request", "details": { ... } }
{ "error": "unsupported_destination", "supported": ["US","CN","EU",...] }
{ "error": "rate_limited", "retry_after": 12, "reset_at": "..." }
{ "error": "unknown_hs" }

HTTP 状态码:400 (参数非法) / 401 (缺少鉴权:未登录或未带 API 密钥) / 404 (HS/国家未识别) / 429 (速率限制) / 500 (服务异常)。

准备好开始集成了吗？

登录后即可在 Dashboard 一键签发密钥。

签发密钥