服务市场 / 进口税金试算 API 开发文档

台湾进口税金试算 API · v1

进口税金试算 API 开发文档

依商品 (CCC 税则,或只给商品描述自动 AI 分类) + 外币金额,实时算出台湾进口税金:关税 (含 ECFA / 定额税)、营业税、推广费、货物税、烟酒税,并自动判断 NT$2,000 小额免税。专为 0337.tw 等跨境电商平台对接设计。

5 大税费

关税+营业税+推广费+货物税+烟酒税

NT$2,000

小额免税自动判断

AI 税则

给商品描述自动分类 CCC

每旬汇率

官方海关报关汇率换算

1 总览

让你的平台在前台直接显示「这件商品进口台湾要缴多少税」。

能做什么

税金试算 — 带入商品 (CCC 税则或商品描述) + 外币金额,回传完整税金明细 (关税 / 营业税 / 推广费 / 货物税 / 烟酒税) 与含税落地总成本。
查税率 — 依 CCC 税则号别查关税率、货物税 flag。
自动税则 — 没有 CCC 时,只给 product_description,系统用关务署 AI 模型自动推荐税则并计税。

计税币别:新台币 (TWD)。 你以外币 (如 CNY) 带入商品金额,系统以官方每旬海关报关汇率换算成新台币后计税,税额皆为新台币。

与运费 API 的关系: 税金试算回应中的 shipping_fee 为好运器新台币参考运费 (供落地成本估算)。实际向 0337.tw 收的集运费请改用运费 API (海快,人民币)。本 API 的税金本身不含运费 (税基=商品 FOB,便民口径;正式报关以海关核定 CIF 为准)。

2 认证与基本信息

所有请求需带 API Key (与运费 / 货况同一把密钥即可,需开通 tax:read 权限)。

Base URL

https://howbridge.cn/api/v1/tax

认证标头 (择一)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx
// 或
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

请由服务器端调用,勿暴露密钥于前端。速率限制以密钥为单位,回应标头 X-RateLimit-Remaining 回报剩余额度,超限回 HTTP 429。

3 端点:税金试算

GETPOST /api/v1/tax/estimate

建议用 POST + JSON。

请求参数

参数	类型	必填	说明
`currency_code`	string(3)	必填	外币币别,如 `CNY`。
`price_foreign`	number	必填	外币商品金额。
`product_description`	string	选填*	商品描述。没给 `hs_code` 时用 AI 自动推税则。
`hs_code`	string	选填*	CCC 税则号别 (8–11 码)。
`quantity`	int	选填	数量,预设 1。
`weight_kg` / `dimensions`	number / [3]	选填	重量 / 长宽高 (参考运费估算用)。
`over_exempt_limit`	bool	选填	半年 6 次免税已用完 → 强制课税。
`volume_liters` / `alcohol_degree` / `tobacco_sticks`	number/int	选填	酒/烟定额税计算用。

* hs_code 与 product_description 至少择一。

请求范例 (POST JSON)

curl -X POST https://howbridge.cn/api/v1/tax/estimate \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"product_description":"棉质女上衣","currency_code":"CNY","price_foreign":300,"quantity":1}'

回应 200 (节录)

{
  "success": true,
  "data": {
    "input": { "hs_code": "61061000", "currency_code": "CNY", "price_foreign": 300 },
    "exchange": { "rate_to_twd": 4.612, "price_twd": 1383.6 },
    "tariff_info": { "duty_rate": 10.5, "duty_rate_text": "10.5%", "ecfa_applied": false },
    "tax_base": 1383.6,
    "tax_breakdown": {
      "is_tax_exempt": true,            // 税基 ≤ NT$2,000 → 小额免税
      "duty": 0, "promo_fee": 0, "vat": 0, "total_tax": 0,
      "if_over_limit": {           // 若半年 6 次免税用完之应付
        "duty": 145.28, "vat": 76.44, "total_tax": 221.72
      }
    },
    "antidumping": [],
    "total_landed_cost": 1453.6,
    "disclaimer": "..."
  }
}

4 端点:查税率

GET /api/v1/tax/rate/{hsCode}

依 CCC 税则号别 (纯数字) 查关税率与货物税 flag。

curl https://howbridge.cn/api/v1/tax/rate/6109100000 \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "hs_code": "6109100000",
    "duty_rate": 10.5,
    "duty_rate_text": "10.5%",
    "is_commodity_tax": false,
    "name_zh": "棉制Ｔ恤衫、汗衫…",
    "source": "tariffs_db"
  }
}

5 回应字段说明 (data)

字段	说明
`exchange.rate_to_twd`	采用的每旬海关报关汇率 (外币 → 新台币)。
`exchange.price_twd`	商品金额换算新台币。
`tariff_info.duty_rate`	采用的关税率 (%);ECFA 适用时为第二栏。
`tax_base`	税基 (新台币) = 商品 FOB × 数量 (不含运费)。
`tax_breakdown.is_tax_exempt`	是否小额免税 (税基 ≤ NT$2,000 且非烟酒)。
`tax_breakdown.duty`	关税 (新台币)。
`tax_breakdown.promo_fee`	推广贸易服务费 (0.04%,未达 NT$100 不收)。
`tax_breakdown.commodity_tax`	货物税 (家电等;一般成衣为 0)。
`tax_breakdown.alcohol_tax`	烟酒税 (定额)。
`tax_breakdown.vat`	营业税 5%。
`tax_breakdown.total_tax`	应缴税金总额 (新台币)。
`tax_breakdown.if_over_limit`	免税情境下,若半年 6 次免税用完之预估应付税金。
`antidumping`	反倾销 / 平衡税提示 (依来源国,仅提示不并入 total)。
`total_landed_cost`	含税落地总成本 (税基 + 参考运费 + 税金)。

6 税金公式

税基 = 商品 FOB (外币 × 汇率) × 数量
小额免税 = 税基 ≤ NT$2,000 且非烟酒 → 税金 0 (半年限 6 次)
关税 = 税基 × 关税率 (或定额税取高者)
推广费 = 税基 × 0.04% (未达 NT$100 不收)
货物税 = (税基 + 关税) × 货物税率 (适用品项)
营业税 = (税基 + 关税 + 货物税 + 烟酒税) × 5%
应缴税金 = 关税 + 推广费 + 货物税 + 烟酒税 + 营业税

法规依据:关税法、加值型及非加值型营业税法、贸易法 (推广贸易服务费)、货物税条例、烟酒税法。实际税额以海关核定为准。

7 错误码

HTTP	`error` / 情况	说明
401	missing_api_key / invalid_api_key	未带 / 无效 API Key。
403	insufficient_scope	密钥未开通 `tax:read`。
422	缺 currency_code / price_foreign	必填参数缺漏或格式错。
422	缺税则	未给 hs_code 且 product_description 无法分类。
422	无此币别汇率	该 currency_code 尚未提供汇率,请联系客服。
429	rate_limit_exceeded	超过每分钟上限。

8 程序范例

$client = new GuzzleHttp\Client(['base_uri' => 'https://howbridge.cn']);
$res = $client->post('/api/v1/tax/estimate', [
    'headers' => ['Authorization' => 'Bearer ' . env('LUCKY_FREIGHT_KEY')],
    'json' => [
        'product_description' => '棉质女上衣',
        'currency_code' => 'CNY',
        'price_foreign' => 300,
    ],
]);
$tax = json_decode($res->getBody(), true)['data']['tax_breakdown'];
echo '应缴税金 NT$' . $tax['total_tax'];

const r = await fetch('https://howbridge.cn/api/v1/tax/estimate', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.LUCKY_FREIGHT_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ product_description: '棉质女上衣', currency_code: 'CNY', price_foreign: 300 }),
});
const { data } = await r.json();
console.log(data.tax_breakdown.total_tax);

curl -X POST https://howbridge.cn/api/v1/tax/estimate \
  -H "Authorization: Bearer $LUCKY_FREIGHT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_description":"棉质女上衣","currency_code":"CNY","price_foreign":300}'

9 支持与版本

技术支持: howyunqisoftware@gmail.com

API 版本: v1 (稳定)。

变更纪录: 2026-06-01 — 进口税金试算 API v1 上线。

运费 API 货况 API 申请 API 密钥