API-Referenz

Trade-Compliance-API

Integrieren Sie HTS-Einreihung und Zollberechnung direkt in Ihre Systeme. Senden Sie eine Produktbeschreibung und ein Ursprungsland, erhalten Sie den HTS-Code und die vollständige Aufschlüsselung des Zollstapels in einem einzigen REST-Aufruf.

Test-API-Schlüssel anfordern Zurück zur API-Produktübersicht

Leistung

Durchsatz, mit dem Ihr Operations-Team planen kann

Hunderte von SKUs? Tausende? Ginger reiht sie alle in Minuten ein.

Einzelprodukt-Einreihung

Reihen Sie ein einzelnes Produkt mit einem API-Aufruf ein.

Antwortzeit

Antwortzeiten, gemessen über den Produktivverkehr. Niedrigere Perzentile beschreiben die typische Erfahrung, höhere Perzentile den ungünstigsten Fall.

Durchschnitt

36 s

Mittlere Antwortzeit über alle Produktivanfragen.

Median (p50)

30 s

Die Hälfte aller Anfragen wird innerhalb dieser Zeit abgeschlossen.

p95

79 s

95 % der Anfragen werden innerhalb dieser Zeit abgeschlossen, der typische ungünstigste Fall.

p99

108 s

99 % der Anfragen werden innerhalb dieser Zeit abgeschlossen, selbst unter Last.

Stapel-Einreihung

Reihen Sie bis zu 200 Produkte in einem API-Aufruf ein.

Durchsatz

Gebaut für Kataloge im großen Maßstab. Eine Anfrage verarbeitet den gesamten Stapel parallel und schließt innerhalb von Minuten ab.

Positionen pro Aufruf

200

Maximale Anzahl Produkte pro Stapel-API-Aufruf.

Abschlusszeit

3-5 Min.

Typische Zeit zur durchgängigen Verarbeitung eines vollständigen Stapels.

Tageskapazität

200K+

Tägliches Einreihungsvolumen der Produktionsstufe. Individuelle Enterprise-Stufen skalieren auf bis zu 100.000 Einreihungen pro Stunde.

★

Zollberechnung für zusammengesetzte Waren mit aufgeteiltem Code

Produkte aus Kapitel 91 wie Armbanduhren werden nach Komponenten verzollt, nicht als eine einzelne Einheit. Die API teilt sie automatisch in ihre Bestandteile auf und liefert ein components-Array zurück, wobei jeder Teil seinen eigenen HTS-Code und seine eigene Zollberechnung hat. Die meisten Einreihungs-APIs überspringen das schlicht, aber echte Trade Compliance bedeutet, dass jedes Produkt die korrekte Zollbehandlung erhält, ohne Ausnahme.

Ein Aufruf hinein, das vollständige Zollbild heraus

Die GingerControl OpenAPI ist eine REST-Schnittstelle für automatisierte HTS-Einreihung und Zollberechnung. Senden Sie eine Produktbeschreibung und ein Ursprungsland; ein Aufruf liefert den HTS-Code und eine vollständige Zollaufschlüsselung.

Einreihungsergebnisse sind Rechercheausgaben für Ihr Team: In unserem internen Benchmark über mehr als 1.000 Produkte erreichte die Engine eine Genauigkeit von 99,86 %, und jedes Ergebnis ist darauf ausgelegt, vor der Einreichung von einem zugelassenen Zollagenten geprüft zu werden.

Einzelprodukt-Endpunkt

Ein Produkt pro Anfrage, mit vollständigem Zolldetail.

Stapel-Endpunkt

Bis zu 200 Produkte pro Anfrage.

Unterstützung für aufgeteilte Codes

Zölle auf Komponentenebene für Produkte mit aufgeteiltem Code.

Vollständiger Zollstapel

Allgemeine (MFN) und Sondersätze, Section 301, 232, 122 sowie alle zutreffenden Kapitel-99-Einträge.

Vom API-Vertrag zur Produktion in vier Schritten

Schritt 01

Den API-Vertrag lesen

Der nachstehende Vertrag deckt Anfragemuster, Antwortstrukturen, Fehlersemantik und Ratenbegrenzungen ab. Zwanzig Minuten Lektüre sparen Tage des Debuggings.

X-Api-Key: ••••

Schritt 02

Einen Test-API-Schlüssel anfordern

Kontaktieren Sie uns, und wir liefern einen Testschlüssel über einen Offline-Kanal wie E-Mail.

Warnung

Testschlüssel haben ein kleines Kontingent und laufen in 7-30 Tagen ab. Sie sind nur für Entwicklung und Debugging bestimmt, niemals für die Produktion.

{}

200

Schritt 03

Entwickeln und debuggen

Die meisten Teams schließen die grundlegende Integration schnell ab und verbringen die restliche Zeit damit, die zurückgegebenen Daten in ihre eigenen Systeme einzubinden.

Schritt 04

In Produktion gehen

Fordern Sie einen Produktionsschlüssel an, wenn Sie bereit sind, live zu gehen. Wir dimensionieren ihn nach Ihren Aufrufmustern, der IP-Allowlist und der Spitzen-QPS.

Warnung

Bewahren Sie Ihren Produktions-API-Schlüssel sicher auf. Im aktuellen Stadium ist der API-Schlüssel die alleinige Grundlage für die Abrechnung.

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