Tài liệu tham chiếu API

API Tuân thủ Thương mại

Tích hợp phân loại HTS và tính toán thuế quan trực tiếp vào hệ thống của bạn. Gửi một mô tả sản phẩm và nước xuất xứ, nhận về mã HTS và toàn bộ phân tích chồng thuế quan chỉ trong một lệnh gọi REST.

Yêu cầu API Key thử nghiệm Quay lại tổng quan sản phẩm API

Hiệu năng

Thông lượng mà đội vận hành của bạn có thể lập kế hoạch dựa vào

Hàng trăm SKU? Hàng nghìn? Ginger phân loại tất cả chỉ trong vài phút.

Phân loại một sản phẩm

Phân loại một sản phẩm đơn lẻ chỉ với một lệnh gọi API.

Thời gian phản hồi

Thời gian phản hồi được đo trên lưu lượng production. Các bách phân vị thấp mô tả trải nghiệm điển hình, các bách phân vị cao mô tả trường hợp xấu nhất.

Trung bình

36s

Thời gian phản hồi trung bình trên tất cả các yêu cầu production.

Trung vị (p50)

30s

Một nửa số yêu cầu hoàn thành trong khoảng thời gian này.

p95

79s

95% số yêu cầu hoàn thành trong khoảng thời gian này, trường hợp xấu nhất điển hình.

p99

108s

99% số yêu cầu hoàn thành trong khoảng thời gian này, kể cả khi tải cao.

Phân loại theo lô

Phân loại tối đa 200 sản phẩm trong một lệnh gọi API.

Thông lượng

Được xây dựng cho các danh mục ở quy mô lớn. Một yêu cầu xử lý toàn bộ lô song song và hoàn thành trong vài phút.

Số mục mỗi lệnh gọi

200

Số sản phẩm tối đa cho mỗi lệnh gọi API theo lô.

Thời gian hoàn thành

3-5 phút

Thời gian điển hình để xử lý trọn một lô từ đầu đến cuối.

Công suất hằng ngày

200K+

Khối lượng phân loại hằng ngày ở bậc production. Các bậc doanh nghiệp tùy chỉnh có thể mở rộng đến 100K lượt phân loại mỗi giờ.

★

Tính thuế quan cho hàng hỗn hợp có mã tách

Các sản phẩm thuộc Chương 91 như đồng hồ đeo tay chịu thuế theo từng bộ phận, chứ không phải như một đơn vị duy nhất. API tự động tách chúng thành các bộ phận cấu thành và trả về một mảng components, mỗi bộ phận có mã HTS và phép tính thuế riêng. Hầu hết các API phân loại đơn giản là bỏ qua điều này, nhưng tuân thủ thương mại thực sự nghĩa là mọi sản phẩm đều được xử lý thuế đúng, không có ngoại lệ.

Một lệnh gọi vào, toàn bộ bức tranh thuế quan ra

GingerControl OpenAPI là một giao diện REST để phân loại HTS tự động và tính toán thuế quan. Gửi một mô tả sản phẩm và nước xuất xứ; một lệnh gọi trả về mã HTS và một bản phân tích thuế đầy đủ.

Kết quả phân loại là đầu ra nghiên cứu cho đội ngũ của bạn: trong bài kiểm chuẩn nội bộ của chúng tôi trên hơn 1.000 sản phẩm, bộ máy đạt độ chính xác 99,86%, và mỗi kết quả được thiết kế để đại lý hải quan có giấy phép xem xét trước khi khai báo.

Điểm cuối một sản phẩm

Một sản phẩm cho mỗi yêu cầu, kèm chi tiết thuế đầy đủ.

Điểm cuối theo lô

Tối đa 200 sản phẩm cho mỗi yêu cầu.

Hỗ trợ mã tách

Thuế quan ở cấp bộ phận cho các sản phẩm có mã tách.

Chồng thuế quan đầy đủ

Mức thuế General (MFN) và Special, Section 301, 232, 122, và mọi mục Chương 99 áp dụng.

Từ hợp đồng API đến production qua bốn bước

Bước 01

Đọc hợp đồng API

Hợp đồng bên dưới bao gồm các mẫu yêu cầu, cấu trúc phản hồi, ngữ nghĩa lỗi và giới hạn tốc độ. Hai mươi phút đọc tiết kiệm nhiều ngày gỡ lỗi.

X-Api-Key: ••••

Bước 02

Yêu cầu API Key thử nghiệm

Hãy liên hệ với chúng tôi và chúng tôi sẽ chuyển key thử nghiệm qua một kênh ngoại tuyến như email.

Cảnh báo

Key thử nghiệm có hạn ngạch nhỏ và hết hạn trong 7-30 ngày. Chúng chỉ dùng để phát triển và gỡ lỗi, không bao giờ dùng cho production.

{}

200

Bước 03

Phát triển và gỡ lỗi

Hầu hết các đội hoàn thành tích hợp cơ bản nhanh chóng, rồi dành phần thời gian còn lại để đấu nối dữ liệu trả về vào hệ thống của riêng họ.

Bước 04

Đưa lên production

Yêu cầu một key production khi bạn đã sẵn sàng vận hành. Chúng tôi định cỡ key theo các mẫu gọi, danh sách IP cho phép và QPS đỉnh của bạn.

Cảnh báo

Hãy giữ API key production của bạn an toàn. Ở giai đoạn hiện tại, API key là cơ sở duy nhất để tính phí.

Single-Product Endpoint

Method: POST

Path: /openapi/v1/tariff

Base URL: https://api.gingercontrol.com

Request Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`X-Api-Key`	Yes	Caller credential issued offline by GingerControl. Used for authentication, rate limiting, and quota control.
`X-Request-Id`	No	Request trace identifier for troubleshooting and log tracing. Server generates one if omitted.

Response Headers

Header	Description	Purpose
`Content-Type`	Always `application/json`	Indicates the response body format
`X-Request-Id`	Echoes the caller-provided value, or a server-generated value	Recommended for logging and troubleshooting
`Retry-After`	Returned only with `429 Too Many Requests`	Tells the caller how many seconds to wait before retrying

Request Body

Field	Type	Required	Description
`description`	string	Yes	Product description. Must not be empty; max 10,000 characters.
`country_of_origin`	string	Yes	ISO 3166-1 alpha-2 country code. `EU` (European Union) and `UK` (United Kingdom) are also accepted; `GB` is accepted and processed as `UK`.
`extra`	object	No	Additional input. The current version only consumes `steel_pour_country` and `aluminum_pour_country`; all other fields are ignored.
`extra.steel_pour_country`	string	No	Steel pour country. Same rules as `country_of_origin`.
`extra.aluminum_pour_country`	string	No	Aluminum pour country. Same rules as `country_of_origin`.

Request Example

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

Response Example

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

Successful Response

Field	Type	Meaning	Notes
`hts_code`	string	The HTS code determined for the product	Normally a 10-digit code; a split-code product may return an 8-digit parent code such as `9101.11.40`
`tariffs`	object \| null	The set of tariff-related data for the product	May be `null` for split-code products
`tariffs.general_rate`	string \| null	General rate	This may also be understood as MFN
`tariffs.special_rate`	string \| null	Special rate	The raw text is lightly normalized, for example by removing a trailing parenthetical note
`tariffs.<module_key>`	array	List of Chapter 99 entries for the module	Each element is `{code, rate}`
`tariffs.<module_key>[].code`	string	Chapter 99 code	For example, `9903.85.08`
`tariffs.<module_key>[].rate`	string	Rate	Percentage string such as `25%`
`components`	array	Component list for a split-code product	Omitted for ordinary products
`components[].hts_code`	string	Component HTS code	Always 10 digits
`components[].tariffs`	object \| null	Tariff data for the component

Error Response

Field	Type	Meaning	Notes
`detail`	object	Error object
`detail.code`	string	Error code	Intended for programmatic handling
`detail.message`	string	Error message	Intended for logging and troubleshooting

Error Response Example

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

Error Codes

HTTP Status	Code	Description
`401`	`missing_api_key`	X-Api-Key was not provided
`401`	`invalid_api_key`	API key validation failed
`403`	`api_key_revoked`	The API key has been revoked
`403`	`client_disabled`	The caller account has been disabled
`422`	`invalid_request`	Request body is malformed or fields do not satisfy the contract
`429`	`request_rate_limited`	Request-level protection was triggered
`429`	`item_rate_limited`	Item-level quota protection was triggered
`500`	`classification_failed`	HTS identification failed
`500`	`calculator_failed`	Tariff calculation failed
`500`	`internal_error`	An unclassified internal error occurred

Quick Test

Replace YOUR_API_KEY with the key issued to you, then run:

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"
    }
  }'

Batch Endpoint

Method: POST

Path: /openapi/v1/tariff/batch

Base URL: https://api.gingercontrol.com

Headers

Request and response headers are identical to the Single-Product Endpoint: Content-Type, X-Api-Key, and optional X-Request-Id on the request; X-Request-Id and Retry-After (on 429) on the response.

Request Body

Field	Type	Required	Description
`items`	array	Yes	List of products. Up to 200 items per request.
`items[].item_id`	string	Yes	Caller-defined unique identifier for result reconciliation. Must be unique within the request.
`items[].description`	string	Yes	Product description. Must not be empty; max 10,000 characters.
`items[].country_of_origin`	string	Yes	Same rules as the single-product `country_of_origin`.
`items[].extra`	object	No	Same rules as the single-product `extra` object.

Request Example

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

Response Example

{
  "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": [],
        "Section 122": [
          { "code": "9903.03.01", "rate": "10%" }
        ]
      }
    },
    {
      "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": [],
        "Section 122": [
          { "code": "9903.03.01", "rate": "10%" }
        ]
      }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

Successful Response

Field	Type	Meaning	Notes
`items`	array	List of batch processing results	The response order matches the request order
`items[].item_id`	string	Caller-provided unique identifier	Used for result reconciliation
`items[].status`	string	Processing status	Either `ok` or `failed`
`items[].hts_code`	string	HTS code for a successful item	Normally a 10-digit code; a split-code product may return an 8-digit parent code; present only when `status = ok`
`items[].tariffs`	object \| null	Tariff data for a successful item	May be `null` for split-code products; present only when `status = ok`
`items[].tariffs.general_rate`	string \| null	General rate	This may also be understood as MFN
`items[].tariffs.special_rate`	string \| null	Special rate	Lightly normalized before being returned
`items[].tariffs.<module_key>`	array	Module entries	Each element is `{code, rate}`
`items[].tariffs.<module_key>[].code`	string	Chapter 99 code
`items[].tariffs.<module_key>[].rate`	string	Rate
`items[].components`	array	Component list for a split-code product	Omitted for ordinary products; present only when `status = ok`
`items[].components[].hts_code`	string	Component HTS code	Always 10 digits
`items[].components[].tariffs`	object \| null	Tariff data for the component
`items[].code`	string	Failure code for a failed item	Present only when `status = failed`
`summary`	object	Summary information for the batch request
`summary.total`	integer	Total number of items in this request
`summary.succeeded`	integer	Number of successful items
`summary.failed`	integer	Number of failed items

Error Response

Field	Type	Meaning	Notes
`detail`	object	Error object
`detail.code`	string	Error code	Intended for programmatic handling
`detail.message`	string	Error message	Intended for logging and troubleshooting

Error Response Example

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

Error Codes

Batch-Level Error Codes

HTTP Status	Code	Description
`401`	`missing_api_key`	X-Api-Key was not provided in the request headers
`401`	`invalid_api_key`	API key validation failed
`403`	`api_key_revoked`	The API key has been revoked
`403`	`client_disabled`	The caller account has been disabled
`422`	`invalid_request`	The top-level structure is invalid, item_id values are duplicated, fields are missing, field types are incorrect, or field values do not satisfy the contract
`429`	`request_rate_limited`	Request-level protection was triggered
`429`	`item_rate_limited`	Item-level quota protection was triggered
`500`	`internal_error`	An unclassified batch-level internal error occurred

Item-Level Failure Codes

Code	Description
`classification_failed`	HTS identification failed for that item
`calculator_failed`	Tariff calculation failed for that item
`internal_error`	An unclassified internal error occurred for that item

Quick Test

Replace YOUR_API_KEY with the key issued to you, then run:

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

Rate Limits & Quotas

All API calls are subject to request-level protection. When request frequency is too high, the system returns 429 Too Many Requests.
Quota is consumed by the number of products processed. The single-product endpoint consumes 1 item, while batch consumes based on the number of items.
Both endpoints share the same item-level quota under the same API key.
Production API keys are sized to each customer's traffic model. Contact us for tier sizing.

Development Recommendations

Validate request bodies

If you receive 422, the request body structure, field types, or field values usually do not match the contract. Check the request body first.

Handle rate limits gracefully

If you receive 429, implement retry behavior using the Retry-After response header.

Log request IDs

Keep request logs and record the X-Request-Id for each call. This significantly reduces troubleshooting time.

Configure timeouts and retries

Configure reasonable timeouts, retries, and failure alerts so that network fluctuations can be handled robustly.

Security Recommendations

Do not embed your API key in frontend code, browser code, or any environment exposed to end users.

Do not use production API keys in test, development, or temporary debugging environments.

Store your API key in a secure configuration system, such as a secret manager or tightly controlled environment variables.

If an API key is lost, suspected to be leaked, or needs to be rotated, please contact us as soon as possible.

Contact

For integration support, testing, production rollout, or ongoing operations, please contact us:

Email: chen@gingercontrol.com