Classification + Tariff Calculation API API 文件

一次呼叫，拿到 HTS 稅號和關稅。

兩個 POST 端點，單筆一項、批次預設120項，每個欄位、錯誤碼和 curl 範例都在這裡。

Classification + Tariff Calculation API 文件

本頁內容

API 版本 v1 · Base URL api.gingercontrol.com

Classification + Tariff Calculation API 會回傳什麼？

Classification + Tariff Calculation API（稅號判定加關稅試算 API）是 GingerControl 的 REST API，用來判定美國 HTS 稅號和查詢關稅。您用 POST 送出一段產品描述和原產地，API 回傳 HTS 稅號、一般稅率和優惠稅率，以及每一層第99章關稅的稅號和稅率。一項產品用單筆端點；批次端點預設每次120項（可依您的處理量另行調整）。金鑰由我們另行發放，結果用於報關準備，由持照報關行覆核。

Base URL：https://api.gingercontrol.com
端點：POST /openapi/v1/tariff 處理一項產品，POST /openapi/v1/tariff/batch 最多處理120項
身分驗證：在 X-Api-Key 標頭帶入 API 金鑰，金鑰由 GingerControl 另行發放
格式：請求本文和回應都是 JSON

怎麼取得使用權限並完成整合？

先讀完下面的 API 規格，預約通話取得依您流量設定的 API 金鑰，再把結果接進您自己的系統。

閱讀 API 規格

開始前，請完整讀過下面各端點的說明。內容涵蓋請求方式、輸入和輸出結構、錯誤的意義和速率限制，能縮短整合和除錯的時間。

申請 API 金鑰

預約一通電話。我們會詢問您的呼叫模式、IP 白名單、尖峰 QPS 和延遲時間要求，再透過 Email 等管道另行交付金鑰。

整合

多數團隊很快就完成基本整合，之後的時間多半花在把回傳資料接進自己的系統。

請妥善保管正式環境金鑰。現階段，API 金鑰是計費的唯一依據。

單筆端點

送出一段產品描述和原產地，拿回這項產品的 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	否	鋼材澆鑄國，規則同 `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	一般稅率，可視為最惠國待遇稅率（MFN）
`tariffs.special_rate`	string 或 null	優惠稅率，經過簡單整理（例如拿掉結尾括號裡的附註）
`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 金鑰驗證失敗
`403 Forbidden`	`api_key_revoked`	API 金鑰已撤銷
`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 換成我們另行發給您的金鑰，指令照原樣執行即可。

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	一般稅率，可視為最惠國待遇稅率（MFN）
`items[].tariffs.special_rate`	string 或 null	優惠稅率，經過簡單整理
`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 金鑰驗證失敗
`403 Forbidden`	`api_key_revoked`	API 金鑰已撤銷
`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 換成我們另行發給您的金鑰，指令照原樣執行即可。

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": {}
      }
    ]
  }'