服務市場 / 進口稅金試算 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://0523.tw/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://0523.tw/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://0523.tw/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://0523.tw']);
$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://0523.tw/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://0523.tw/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 金鑰