Classificazione
Invia il titolo di un prodotto, un payload grezzo o un testo già normalizzato e ricevi i codici TARIC più probabili con confidenza, evidenze e riferimenti normativi. Aggiungi origine, valore doganale e peso per calcolare i dazi.
Classify a product
Classify a single product entity.
Accepts pre-normalized text bundles or raw payloads (with internal normalization). Returns top-10 TARIC code suggestions with confidence scores, evidence, hierarchy paths, and legal references.
Optional fields for duty resolution:
- origin_country: ISO 2-letter code → resolves applicable duties
- customs_value_eur: CIF value in EUR → calculates ad valorem amounts
- weight_kg: Net weight in kg → calculates specific duty amounts
- quantity: Item count → calculates per-unit duty amounts
- volume_litres: Volume in litres → calculates volume-based duty amounts (HLT, LTR)
- energy_gj: Energy in gigajoules → calculates energy-based duty amounts (ENC ENP)
- alcohol_volume_pct: Alcohol % by volume → calculates ASV-based duty amounts
Note: Duties data is automatically omitted when neither origin_country nor destination_country is provided, regardless of the include_duties flag.
Scope richiesto: ai-engine:easydogana:classify:read
Parametri
- Name
ParceLabs-Version- Type
- string
- Description
API version as a date (
YYYY-MM-DD). Omit it to get the oldest supported version; it never moves to a newer one on its own. An unknown value is answered with 400UNSUPPORTED_VERSION, a retired one with 410VERSION_RETIRED. Every response echoes the resolved version in the same header.Valori ammessi:
2026-10-23. Predefinito:2026-10-23.
Corpo della richiesta ClassificationRequest
- Name
alcohol_volume_pct- Type
- number · può essere null
- Description
Alcohol by volume percentage. Needed for alcohol-based specific duties (ASV X).
≥ 0, ≤ 100.
- Name
caller_type- Type
- string
- Description
Identifies the caller as an operator (customs clearance professional) or a customer. Operator interactions are used for prompt learning.
Valori ammessi:
operator,customer. Predefinito:customer.
- Name
customs_value_eur- Type
- number · può essere null
- Description
CIF customs value in EUR. When provided with origin_country, calculates duty amounts.
≥ 0.
- Name
destination_country- Type
- string · può essere null
- Description
ISO 2-letter destination country code (e.g. 'RU', 'KP'). When provided, resolves applicable export controls.
- Name
energy_gj- Type
- number · può essere null
- Description
Energy content in gigajoules (GJ). Needed for energy-based specific duties (ENC ENP).
≥ 0.
- Name
excluded_hs_codes- Type
- array of string
- Description
Optional list of HS/CN/TARIC prefixes to exclude from ranking (e.g. ['8518.30', '8518300090']). Useful for iterative operator refinement.
- Name
hs_code_hint- Type
- string · può essere null
- Description
Optional partial or full HS code hint (e.g. '8518', '8518.30', '8518300090'). When provided, result whose code starts with this prefix is promoted to #1. Accepts dotted or plain digit format; dots are stripped automatically.
- Name
image- Type
- ProductImage · può essere null
- Description
Optional product image (URL or base64) to boost AI normalization. Works with all input types. The image is never stored.
- Name
include_duties- Type
- boolean
- Description
When False, skips all duty resolution and TARIC enrichment fetches for a faster response. Returns only HS codes, confidence scores, hierarchy, and evidence. Automatically set to False when neither origin_country nor destination_country is provided, since duty data is not actionable without geographic context.
Predefinito:
true.
- Name
input- Type
- PreNormalizedInput | RawPayloadInput | TitleOnlyInput
- obbligatorio
- Description
Classification input (pre-normalized or raw payload)
- Name
max_results- Type
- integer
- Description
Maximum number of classification suggestions to return (1–10, default 1).
Predefinito:
1. ≥ 1, ≤ 10.
- Name
origin_country- Type
- string · può essere null
- Description
ISO 2-letter origin country code (e.g. 'CN', 'VN'). When provided, resolves applicable duties.
- Name
preferred_language- Type
- string
- Description
Preferred language for descriptions (ISO 2-letter code)
Predefinito:
EN.
- Name
quantity- Type
- integer · può essere null
- Description
Number of items. Needed for per-unit specific duties (NAR).
≥ 0.
- Name
request_id- Type
- string · può essere null
- Description
Optional request ID (generated if not provided)
- Name
volume_litres- Type
- number · può essere null
- Description
Volume in litres. Needed for volume-based specific duties (HLT=hectolitres, LTR=litres).
≥ 0.
- Name
weight_kg- Type
- number · può essere null
- Description
Net weight in kilograms. Needed for specific duties (per-tonne, per-kg rates).
≥ 0.
Risposte
200Successful ResponseClassificationResponse400Invalid input value (e.g. unusable country or HS hint).ErrorDetail401Missing, malformed, expired or wrongly-scoped credentials.ErrorDetail403The token is valid but carries none of the required scopes.ErrorDetail422Request body failed schema validation (detailis a list of errors), or the engine could not classify the input (detailis a string).HTTPValidationError | ErrorDetail500Unexpected engine error.ErrorDetail
Richiesta
Caricamento...
Title only
{
"input": {
"payload_type": "title_only",
"title": "Cotton T-shirt"
}
}With duty resolution
{
"customs_value_eur": 120,
"destination_country": "IT",
"input": {
"payload_type": "title_only",
"title": "Bluetooth over-ear headphones"
},
"max_results": 3,
"origin_country": "CN",
"preferred_language": "EN"
}Risposta 200
{
"genericity_flag": false,
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"results": [
{
"cn_code": "6109.10.00",
"confidence_flag": "high",
"confidence_reason": "clear",
"confidence_score": 92,
"evidence": {
"matched_terms": [
"t-shirt",
"cotton"
],
"product_attributes": {
"material": "cotton"
}
},
"hierarchy_path": [
{
"code": "61",
"description": "Articles of apparel and clothing accessories, knitted or crocheted"
},
{
"code": "6109",
"description": "T-shirts, singlets and other vests, knitted or crocheted"
}
],
"hs_code": "6109.10",
"taric_code": "6109.10.00.10"
}
],
"retrieval_mode": "hybrid"
}Classify up to 100 products
Classify multiple product entities.
Processes 1-100 inputs per request. Returns HTTP 207 Multi-Status with per-item results. Set concurrency: true in the request body to process items concurrently.
Scope richiesto: ai-engine:easydogana:classify:read
Parametri
- Name
ParceLabs-Version- Type
- string
- Description
API version as a date (
YYYY-MM-DD). Omit it to get the oldest supported version; it never moves to a newer one on its own. An unknown value is answered with 400UNSUPPORTED_VERSION, a retired one with 410VERSION_RETIRED. Every response echoes the resolved version in the same header.Valori ammessi:
2026-10-23. Predefinito:2026-10-23.
Corpo della richiesta BatchClassificationRequest
- Name
concurrency- Type
- boolean
- Description
Enable concurrent processing (default: sequential)
Predefinito:
false.
- Name
inputs- Type
- array of PreNormalizedInput | RawPayloadInput | TitleOnlyInput
- obbligatorio
- Description
Array of classification inputs (1-100 items)
items ≥ 1, items ≤ 100.
- Name
preferred_language- Type
- string
- Description
Preferred language for descriptions (ISO 2-letter code)
Predefinito:
EN.
- Name
request_id- Type
- string · può essere null
- Description
Optional request ID (generated if not provided)
Risposte
207Multi-Status: the batch ran; each item carries its ownstatusand result or error. The call returns HTTP 207, not 200.BatchClassificationResponse400Invalid input value (e.g. unusable country or HS hint).ErrorDetail401Missing, malformed, expired or wrongly-scoped credentials.ErrorDetail403The token is valid but carries none of the required scopes.ErrorDetail422Request body failed schema validation (detailis a list of errors), or the engine could not classify the input (detailis a string).HTTPValidationError | ErrorDetail500Unexpected engine error.ErrorDetail
Richiesta
Caricamento...
Risposta 207
{
"request_id": "550e8400-e29b-41d4-a716-446655440001",
"results": [
{
"index": 0,
"processing_ms": 1840.2,
"results": [
{
"cn_code": "6109.10.00",
"confidence_flag": "high",
"confidence_reason": "clear",
"confidence_score": 92,
"evidence": {
"matched_terms": [
"t-shirt",
"cotton"
],
"product_attributes": {
"material": "cotton"
}
},
"hierarchy_path": [
{
"code": "61",
"description": "Articles of apparel and clothing accessories, knitted or crocheted"
},
{
"code": "6109",
"description": "T-shirts, singlets and other vests, knitted or crocheted"
}
],
"hs_code": "6109.10",
"taric_code": "6109.10.00.10"
}
],
"retrieval_mode": "hybrid",
"status": "success"
},
{
"error": "Failed to classify entity: no usable product text",
"index": 1,
"processing_ms": 3.1,
"status": "error"
}
]
}Refine a previous classification
Refine a previous classification request via operator conversation.
Uses stored conversation context (initial request and prior turns) and applies operator-provided exclusions and/or confirmed hint updates.
Scope richiesto: ai-engine:easydogana:classify:read
Parametri
- Name
request_id- Type
- string
- obbligatorio
- Description
- Name
ParceLabs-Version- Type
- string
- Description
API version as a date (
YYYY-MM-DD). Omit it to get the oldest supported version; it never moves to a newer one on its own. An unknown value is answered with 400UNSUPPORTED_VERSION, a retired one with 410VERSION_RETIRED. Every response echoes the resolved version in the same header.Valori ammessi:
2026-10-23. Predefinito:2026-10-23.
Corpo della richiesta RefinementRequest
- Name
caller_type- Type
- string
- Description
Identifies the caller as an operator or customer.
Valori ammessi:
operator,customer. Predefinito:customer.
- Name
confirmed_hs_hint- Type
- string · può essere null
- Description
Optional operator-confirmed code hint to apply in this turn. AI-proposed hints are not applied unless this is provided.
- Name
excluded_hs_codes- Type
- array of string
- Description
Code prefixes to explicitly exclude in this refinement turn.
- Name
feedback_reason- Type
- string · può essere null
- Description
Optional structured reason tag (e.g. wrong_category, wrong_material_split, too_generic).
- Name
max_results- Type
- integer · può essere null
- Description
Optional override of max results for this refinement turn.
≥ 1, ≤ 10.
- Name
operator_message- Type
- string
- obbligatorio
- Description
Operator free-text feedback explaining why current suggestions are wrong or what should be preferred.
length ≥ 3, length ≤ 2000.
Risposte
200Successful ResponseRefinementResponse400Invalid input value (e.g. unusable country or HS hint).ErrorDetail401Missing, malformed, expired or wrongly-scoped credentials.ErrorDetail403The token is valid but carries none of the required scopes.ErrorDetail404request_idunknown, expired, or not owned by the caller.ErrorDetail422Request body failed schema validation (detailis a list of errors), or the engine could not classify the input (detailis a string).HTTPValidationError | ErrorDetail500Unexpected engine error.ErrorDetail
Richiesta
Caricamento...
Risposta 200
{
"genericity_flag": false,
"proposed_hs_hints": [],
"refine_turn": 1,
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"results": [
{
"cn_code": "6109.10.00",
"confidence_flag": "high",
"confidence_reason": "clear",
"confidence_score": 92,
"evidence": {
"matched_terms": [
"t-shirt",
"cotton"
],
"product_attributes": {
"material": "cotton"
}
},
"hierarchy_path": [
{
"code": "61",
"description": "Articles of apparel and clothing accessories, knitted or crocheted"
},
{
"code": "6109",
"description": "T-shirts, singlets and other vests, knitted or crocheted"
}
],
"hs_code": "6109.10",
"taric_code": "6109.10.00.10"
}
],
"retrieval_mode": "hybrid"
}Look up an HS code
Look up a specific HS code with full duty and cost breakdown.
Given an HS / CN / TARIC code (full or partial), returns:
- TARIC description in the requested language
- Full classification hierarchy path
- Applicable import duties resolved for the origin country
- Applicable export controls for the destination country
- A detailed shipment cost breakdown when goods/shipping values are provided
The `hs_code` field accepts any of:
- Dotted TARIC10: `
8518.30.00.90` - Dotted CN8: `
8518.30.00` - Dotted HS6: `
8518.30` - Plain digits: `
8518300090,851830,8518`
Scope richiesto: ai-engine:easydogana:classify:read
Parametri
- Name
ParceLabs-Version- Type
- string
- Description
API version as a date (
YYYY-MM-DD). Omit it to get the oldest supported version; it never moves to a newer one on its own. An unknown value is answered with 400UNSUPPORTED_VERSION, a retired one with 410VERSION_RETIRED. Every response echoes the resolved version in the same header.Valori ammessi:
2026-10-23. Predefinito:2026-10-23.
Corpo della richiesta LookupRequest
- Name
alcohol_volume_pct- Type
- number · può essere null
- Description
Alcohol by volume %. Needed for alcohol-based duties (ASV X).
≥ 0, ≤ 100.
- Name
customs_value_eur- Type
- number · può essere null
- Description
Explicit CIF customs value in EUR. Takes precedence over goods_value_eur + shipping_cost_eur + insurance_eur if both are provided.
≥ 0.
- Name
destination_country- Type
- string · può essere null
- Description
ISO 2-letter destination country code. Required to resolve export controls.
- Name
energy_gj- Type
- number · può essere null
- Description
Energy content in gigajoules. Needed for energy-based duties (ENC ENP).
≥ 0.
- Name
goods_value_eur- Type
- number · può essere null
- Description
Value of goods in EUR (ex-works / invoice value). Combined with shipping_cost_eur and insurance_eur to compute CIF.
≥ 0.
- Name
hs_code- Type
- string
- obbligatorio
- Description
HS code to look up. Accepts dotted (8518.30.0090), plain digits (8518300090), or partial (8518, 851830). Minimum 4 digits. Dots and spaces are stripped automatically.
- Name
include_duties- Type
- boolean
- Description
When False, skips all duty resolution and TARIC enrichment fetches for a faster response. Returns only HS code description, hierarchy, and legal refs. Use when you only need to confirm a code exists and get its description.
Predefinito:
true.
- Name
insurance_eur- Type
- number · può essere null
- Description
Insurance cost in EUR (defaults to 0 if omitted).
≥ 0.
- Name
origin_country- Type
- string · può essere null
- Description
ISO 2-letter origin country code (e.g. 'CN', 'VN'). Required to resolve applicable duties.
- Name
preferred_language- Type
- string
- Description
Preferred language for descriptions (ISO 2-letter code)
Predefinito:
EN.
- Name
quantity- Type
- integer · può essere null
- Description
Number of items. Needed for per-unit duties (NAR, MIL).
≥ 0.
- Name
shipping_cost_eur- Type
- number · può essere null
- Description
Freight / shipping cost in EUR.
≥ 0.
- Name
volume_litres- Type
- number · può essere null
- Description
Volume in litres. Needed for volume-based duties (HLT, LTR).
≥ 0.
- Name
weight_kg- Type
- number · può essere null
- Description
Net weight in kg. Needed for specific duties (TNE, DTN, KGM).
≥ 0.
Risposte
200Successful ResponseLookupResponse401Missing, malformed, expired or wrongly-scoped credentials.ErrorDetail403The token is valid but carries none of the required scopes.ErrorDetail404No TARIC entry matches the code in the active snapshot.ErrorDetail422Validation ErrorHTTPValidationError
Richiesta
Caricamento...
Partial code
{
"hs_code": "8518"
}Risposta 200
{
"cn_code": "8518.30.00",
"description": "Headphones and earphones, whether or not combined with a microphone",
"hierarchy_path": [
{
"code": "85",
"description": "Electrical machinery and equipment"
}
],
"hs_code": "8518.30",
"taric_code": "8518.30.00.00"
}Search the TARIC nomenclature by free text
Search by text or code prefix without LLMs or classification usage.
Destination and origin are accepted and echoed; they do not affect ranking in v1.
Scope richiesto: ai-engine:easydogana:classify:read
Parametri
- Name
ParceLabs-Version- Type
- string
- Description
API version as a date (
YYYY-MM-DD). Omit it to get the oldest supported version; it never moves to a newer one on its own. An unknown value is answered with 400UNSUPPORTED_VERSION, a retired one with 410VERSION_RETIRED. Every response echoes the resolved version in the same header.Valori ammessi:
2026-10-23. Predefinito:2026-10-23.
Corpo della richiesta SearchRequest
- Name
destination- Type
- string · può essere null
- Description
ISO2; echoed, not used for ranking in v1.
- Name
language- Type
- string
- Description
Predefinito:
EN.
- Name
limit- Type
- integer
- Description
Predefinito:
5. ≥ 1, ≤ 20.
- Name
origin- Type
- string · può essere null
- Description
ISO2; echoed, not used for ranking in v1.
- Name
query- Type
- string
- obbligatorio
- Description
length ≥ 1, length ≤ 200.
Risposte
200Successful ResponseSearchResponse401Missing or invalid credentials.ErrorDetail403Required scope is missing.ErrorDetail422Request body failed schema validation.503Search is temporarily unavailable.ErrorDetail
Richiesta
Caricamento...
Search descriptions
{
"language": "EN",
"query": "wireless headphones"
}Risposta 200
{
"engine_version": "search-v1+2026-11-monthly",
"language": "EN",
"language_fallback": false,
"query_language": "EN",
"results": [
{
"code": "8518300090",
"code_formatted": "8518.30.00.90",
"declarable": true,
"description": "Audio equipment — Headphones",
"level": "taric10",
"match": 1,
"path": [
"Audio equipment",
"Headphones"
]
}
],
"snapshot_id": "2026-11-monthly",
"took_ms": 12
}Modelli
Oggetti usati dalle richieste e dalle risposte di questa pagina.
ClassificationRequest
Request for single entity classification.
- Name
alcohol_volume_pct- Type
- number · può essere null
- Description
Alcohol by volume percentage. Needed for alcohol-based specific duties (ASV X).
≥ 0, ≤ 100.
- Name
caller_type- Type
- string
- Description
Identifies the caller as an operator (customs clearance professional) or a customer. Operator interactions are used for prompt learning.
Valori ammessi:
operator,customer. Predefinito:customer.
- Name
customs_value_eur- Type
- number · può essere null
- Description
CIF customs value in EUR. When provided with origin_country, calculates duty amounts.
≥ 0.
- Name
destination_country- Type
- string · può essere null
- Description
ISO 2-letter destination country code (e.g. 'RU', 'KP'). When provided, resolves applicable export controls.
- Name
energy_gj- Type
- number · può essere null
- Description
Energy content in gigajoules (GJ). Needed for energy-based specific duties (ENC ENP).
≥ 0.
- Name
excluded_hs_codes- Type
- array of string
- Description
Optional list of HS/CN/TARIC prefixes to exclude from ranking (e.g. ['8518.30', '8518300090']). Useful for iterative operator refinement.
- Name
hs_code_hint- Type
- string · può essere null
- Description
Optional partial or full HS code hint (e.g. '8518', '8518.30', '8518300090'). When provided, result whose code starts with this prefix is promoted to #1. Accepts dotted or plain digit format; dots are stripped automatically.
- Name
image- Type
- ProductImage · può essere null
- Description
Optional product image (URL or base64) to boost AI normalization. Works with all input types. The image is never stored.
- Name
include_duties- Type
- boolean
- Description
When False, skips all duty resolution and TARIC enrichment fetches for a faster response. Returns only HS codes, confidence scores, hierarchy, and evidence. Automatically set to False when neither origin_country nor destination_country is provided, since duty data is not actionable without geographic context.
Predefinito:
true.
- Name
input- Type
- PreNormalizedInput | RawPayloadInput | TitleOnlyInput
- obbligatorio
- Description
Classification input (pre-normalized or raw payload)
- Name
max_results- Type
- integer
- Description
Maximum number of classification suggestions to return (1–10, default 1).
Predefinito:
1. ≥ 1, ≤ 10.
- Name
origin_country- Type
- string · può essere null
- Description
ISO 2-letter origin country code (e.g. 'CN', 'VN'). When provided, resolves applicable duties.
- Name
preferred_language- Type
- string
- Description
Preferred language for descriptions (ISO 2-letter code)
Predefinito:
EN.
- Name
quantity- Type
- integer · può essere null
- Description
Number of items. Needed for per-unit specific duties (NAR).
≥ 0.
- Name
request_id- Type
- string · può essere null
- Description
Optional request ID (generated if not provided)
- Name
volume_litres- Type
- number · può essere null
- Description
Volume in litres. Needed for volume-based specific duties (HLT=hectolitres, LTR=litres).
≥ 0.
- Name
weight_kg- Type
- number · può essere null
- Description
Net weight in kilograms. Needed for specific duties (per-tonne, per-kg rates).
≥ 0.
ProductImage
Optional product image to boost AI normalization.
Provide *either* a URL or a base64-encoded image — not both. The image is never stored; it is forwarded inline to the LLM vision API and discarded after the normalization step.
- Name
base64- Type
- string · può essere null
- Description
Base64-encoded image bytes (JPEG / PNG / WebP / GIF)
- Name
media_type- Type
- string · può essere null
- Description
MIME type of the base64 image (e.g. 'image/jpeg'). Required when 'base64' is provided. Ignored when 'url' is provided.
- Name
url- Type
- string · può essere null
- Description
Publicly accessible URL of the product image (HTTPS recommended)
PreNormalizedInput
Pre-normalized text bundle input for classification.
- Name
identifiers- Type
- map of string
- Description
Product identifiers (SKU, EAN, etc.)
- Name
is_generic- Type
- boolean
- obbligatorio
- Description
True if product is too generic for accurate classification
- Name
payload_type- Type
- "normalized"
- Description
Payload type discriminator for pre-normalized input
Predefinito:
normalized.
- Name
quality_score- Type
- integer
- obbligatorio
- Description
Quality score 0-100
≥ 0, ≤ 100.
- Name
questions_for_operator- Type
- array of string
- Description
Questions to improve data quality
- Name
text_bundle- Type
- string
- obbligatorio
- Description
Searchable text bundle in sectioned format
RawPayloadInput
Raw product payload for internal normalization before classification.
- Name
payload- Type
- MarketRockProduct | GenericProduct
- obbligatorio
- Description
Product payload (MarketRock Product or Generic)
- Name
payload_type- Type
- "raw"
- obbligatorio
- Description
Payload type discriminator for raw payload
MarketRockProduct
MarketRock Product payload model (payload.json structure).
- Name
long_description- Type
- string
- obbligatorio
- Description
Extended product description
- Name
payload_type- Type
- "product"
- obbligatorio
- Description
Payload type discriminator for MarketRock Product
- Name
product_category- Type
- string
- obbligatorio
- Description
Product category
- Name
product_id- Type
- string
- obbligatorio
- Description
Unique product identifier
- Name
specs- Type
- map of string
- Description
Product specifications
- Name
title- Type
- string
- obbligatorio
- Description
Product title
GenericProduct
Generic Product payload model (standard contract).
- Name
attributes- Type
- map of string
- Description
Product attributes
- Name
category- Type
- string
- obbligatorio
- Description
Product category
- Name
description- Type
- string
- obbligatorio
- Description
Product description
- Name
identifiers- Type
- map of string
- Description
Product identifiers (SKU, EAN, etc.)
- Name
payload_type- Type
- "generic"
- obbligatorio
- Description
Payload type discriminator for Generic Product
- Name
title- Type
- string
- obbligatorio
- Description
Product title
TitleOnlyInput
Minimal input: just a product title. AI normalizes it before classification.
- Name
payload_type- Type
- "title_only"
- obbligatorio
- Description
Payload type discriminator for AI-normalized title input
- Name
source_language- Type
- string · può essere null
- Description
ISO 2-letter language code of the title (e.g. 'ZH', 'JA', 'RU'). Omit or set to null to let the AI detect the language automatically.
- Name
title- Type
- string
- obbligatorio
- Description
Product title or short description in any language
length ≥ 2, length ≤ 500.
ClassificationResponse
Response for single entity classification.
- Name
degraded_stages- Type
- array of DegradedStage
- Description
Pipeline stages that fell back to a degraded mode, if any.
- Name
genericity_flag- Type
- boolean
- Description
True if input is too generic
Predefinito:
false.
- Name
questions_for_operator- Type
- array of string
- Description
Questions to improve data quality
- Name
request_id- Type
- string
- obbligatorio
- Description
Unique request ID for correlation
- Name
results- Type
- array of Suggestion
- obbligatorio
- Description
Classification suggestions (up to max_results)
items ≥ 0, items ≤ 10.
- Name
retrieval_mode- Type
- string
- Description
Caller-facing summary of the retrieval fan-out: 'hybrid' means all retrievers contributed; 'bm25_only' means the vector stage degraded and results are served from BM25+anchor alone.
Valori ammessi:
hybrid,bm25_only. Predefinito:hybrid.
- Name
warnings- Type
- array of LanguageWarning
- Description
Language availability warnings
DegradedStage
A single pipeline stage that fell back to a degraded mode.
reason MUST be a fixed category string (e.g. "index_not_found", "request_error", "exception") — never raw exception text or other caller-supplied detail. Raw failure detail belongs in server logs only (see threat T-04-I1).
- Name
reason- Type
- string
- obbligatorio
- Description
Fixed category string describing why the stage degraded
- Name
stage- Type
- string
- obbligatorio
- Description
Pipeline stage that degraded, e.g. 'vector'
Suggestion
Individual classification suggestion with confidence and evidence.
- Name
agricultural_duties- Type
- array of object
- Description
Agricultural component duties (EA) for this goods code
- Name
applicable_duties- Type
- ApplicableDuties · può essere null
- Description
Resolved duties for the specified origin country (only when origin_country is provided)
- Name
applicable_export_controls- Type
- ApplicableExportControls · può essere null
- Description
Resolved export controls for the destination country (only when destination_country is provided)
- Name
cn_code- Type
- string
- obbligatorio
- Description
8-digit CN code
- Name
confidence_flag- Type
- string · può essere null
- Description
Calibrated confidence level: 'high', 'medium', or 'low'. 'high' means strong match with clear gap from runner-up. 'medium' means decent match but ambiguous. 'low' means weak or uncertain classification.
- Name
confidence_reason- Type
- string · può essere null
- Description
Dominant reason behind the calibrated confidence_flag: 'operator_confirmed' or 'hs_hint' (operator-promoted, authoritative), 'degraded:<stage>' (retrieval/rerank degraded), 'narrow_gap' (ambiguous #1-#2 gap), 'low_llm_relevance' (weak LLM relevance signal), or 'clear' (no penalty fired).
- Name
confidence_score- Type
- integer
- obbligatorio
- Description
Confidence score 0-100
≥ 0, ≤ 100.
- Name
duties_export- Type
- array of object
- Description
Export duty entries for this goods code
- Name
duties_import- Type
- array of object
- Description
Import duty entries for this goods code
- Name
evidence- Type
- Evidence
- obbligatorio
- Description
Matched terms grouped by section
- Name
feedback_confirmed- Type
- boolean
- Description
True when an operator previously confirmed this code for a matching product and it was hard-promoted to the top (confidence_score 99, confidence_reason 'operator_confirmed'). False for semantic boosts and when no feedback applied.
Predefinito:
false.
- Name
feedback_match_type- Type
- string · può essere null
- Description
How operator feedback affected this suggestion. 'exact': the confirmed code was promoted to #1 (feedback_confirmed is true). 'semantic': a similar confirmed product raised the confidence_score without promoting it. Null when no feedback applied.
Valori ammessi:
exact,semantic.
- Name
hierarchy_path- Type
- array of HierarchyPath
- Description
Path from HS6 to TARIC10
- Name
hint_disagreed- Type
- boolean
- Description
True when the request's hs_code_hint named a different line than this suggestion. Set on the top suggestion whichever side won — see hint_outcome for which. Always false when no hint was supplied.
Predefinito:
false.
- Name
hint_outcome- Type
- string · può essere null
- Description
What happened to the request's hs_code_hint. Top suggestion only; null when no hint was supplied.
'agreed' — the hinted code is this suggestion. Two independent sources; confidence_reason reads 'hs_hint'. 'overridden' — the hinted code was among the candidates, retrieval was clean, and another line ranked above it. A real judgement against the hint. 'deferred' — the hinted code was among the candidates but retrieval degraded, so this suggestion IS the hinted code rather than the classifier's own pick. confidence_reason reads 'hs_declared'. 'not_in_candidates' — the hinted code never surfaced, so it could not be weighed. The classifier's pick stands. This is disagreement WITHOUT evidence against the hint: do not present it as the hint being refuted, and read confidence_flag for how much to trust the pick.
Valori ammessi:
agreed,overridden,deferred,not_in_candidates.
- Name
hs_code- Type
- string
- obbligatorio
- Description
6-digit HS code
- Name
image_signal- Type
- ImageSignal · può essere null
- Description
Per-candidate image-derived audit record (CBP reasonable-care), populated only when an image was provided and the vision cross-check ran (IMG-02).
- Name
is_leaf- Type
- boolean
- Description
True if the code is a fully specific TARIC10 leaf (hier_pos >= 10). False means only a parent subheading or CN8 level was matched.
Predefinito:
true.
- Name
leaf_selection_reason- Type
- string · può essere null
- Description
Explanation of why this hierarchy level was selected (e.g. 'Most specific declarable TARIC10 code' or 'Resolved from parent CN8 to leaf based on best keyword overlap')
- Name
legal_refs- Type
- array of LegalRef
- Description
Footnotes and legal bases
- Name
measure_conditions- Type
- array of object
- Description
Measure conditions (certificates, licenses required)
- Name
measure_exclusions- Type
- array of object
- Description
Measure exclusions (countries excluded from measures)
- Name
measure_footnotes- Type
- array of object
- Description
Measure-specific footnotes
- Name
taric_code- Type
- string
- obbligatorio
- Description
10-digit TARIC code
ApplicableDuties
Resolved duties for a specific origin country.
- Name
anti_dumping_duties- Type
- array of DutyEntry
- Description
Anti-dumping/countervailing/safeguard duties (applied on top)
- Name
best_applicable_duty- Type
- DutyEntry · può essere null
- Description
Best (lowest) applicable rate for this origin
- Name
import_controls- Type
- array of ImportControl
- Description
Import controls, restrictions, certificates required
- Name
missing_parameters- Type
- array of MissingParameter
- Description
Parameters needed to calculate duty amounts that were not provided in the request
- Name
origin_country- Type
- string
- obbligatorio
- Description
ISO 2-letter origin country code
- Name
preferential_duties- Type
- array of DutyEntry
- Description
Preferential/quota rates available for this origin
- Name
third_country_duty- Type
- DutyEntry · può essere null
- Description
MFN third country duty (baseline rate)
DutyEntry
A single resolved duty rate.
- Name
amount_eur- Type
- number · può essere null
- Description
Calculated duty in EUR (if customs value/weight provided)
- Name
geographical_area- Type
- string
- Description
Origin country/group name (e.g. 'Chile', 'ERGA OMNES', 'CARIFORUM')
Predefinito:
.
- Name
geographical_area_id- Type
- string
- Description
Origin country/group code (e.g. 'CL', '1011', '1033')
Predefinito:
.
- Name
is_quota- Type
- boolean
- Description
Whether this rate is subject to a tariff quota (limited volume)
Predefinito:
false.
- Name
legal_base- Type
- string
- Description
Legal base regulation
Predefinito:
.
- Name
legal_base_url- Type
- string · può essere null
- Description
EUR-Lex URL for the legal base regulation
- Name
measure_type- Type
- string
- Description
Measure type name
Predefinito:
.
- Name
measure_type_code- Type
- string
- Description
Measure type code
Predefinito:
.
- Name
order_number- Type
- string · può essere null
- Description
Tariff quota order number
- Name
quota_url- Type
- string · può essere null
- Description
EU tariff quota balance consultation URL
- Name
rate- Type
- string
- obbligatorio
- Description
Duty expression (e.g. '6.500 %', '16.910 EUR TNE')
ImportControl
An import control or restriction.
- Name
detail- Type
- string · può essere null
- Description
Condition/certificate details
- Name
geographical_area- Type
- string
- Description
Origin country/group name
Predefinito:
.
- Name
geographical_area_id- Type
- string
- Description
Origin country/group code
Predefinito:
.
- Name
measure_type- Type
- string
- Description
Control type name
Predefinito:
.
- Name
measure_type_code- Type
- string
- Description
Control type code
Predefinito:
.
MissingParameter
Feedback about a missing parameter needed for duty calculation.
- Name
parameter- Type
- string
- obbligatorio
- Description
Name of the missing request parameter
- Name
reason- Type
- string
- obbligatorio
- Description
Why this parameter is needed and what to provide
ApplicableExportControls
Resolved export controls for a specific destination country.
- Name
destination_country- Type
- string
- obbligatorio
- Description
ISO 2-letter destination country code
- Name
export_controls- Type
- array of ExportControl
- Description
Export controls/restrictions applicable for this destination
ExportControl
An export control, restriction, or authorization.
- Name
destination- Type
- string
- Description
Destination country/group name
Predefinito:
.
- Name
destination_code- Type
- string
- Description
Destination code
Predefinito:
.
- Name
detail- Type
- string · può essere null
- Description
Condition/certificate details
- Name
legal_base- Type
- string
- Description
Legal base regulation
Predefinito:
.
- Name
legal_base_url- Type
- string · può essere null
- Description
EUR-Lex URL for the legal base regulation
- Name
measure_type- Type
- string
- Description
Export control type name
Predefinito:
.
- Name
measure_type_code- Type
- string
- Description
Export control type code
Predefinito:
.
Evidence
Classification evidence for explainability.
- Name
matched_terms- Type
- array of string
- Description
Keywords from the product that matched the TARIC description
- Name
product_attributes- Type
- map of string
- Description
Structured product attributes considered during classification
HierarchyPath
Code and description pair for hierarchy path with provenance.
- Name
code- Type
- string
- obbligatorio
- Description
HS6, CN8, or TARIC10 code
- Name
description- Type
- string
- obbligatorio
- Description
Code description
- Name
source_snapshot_id- Type
- string · può essere null
- Description
Snapshot ID that contributed this description
ImageSignal
Audit record of image-derived signals used in this classification (CBP H350722 "reasonable care" discipline, IMG-02). Every field is either directly what the VLM said or a deterministic derivation — nothing is inferred silently. All fields default so an all-empty signal (no image, or image never used) is valid.
- Name
caption_attributes- Type
- map of string
- Description
Structured attributes the VLM extracted from the image (material, form, packaging, visible_labels, etc.) — the same dict merged into the query text.
- Name
confidence_delta_pct- Type
- number · può essere null
- Description
Signed percentage change applied to confidence_score by the image signal (positive = bump, negative = penalty). None when no cross-check ran.
- Name
cross_check_agreement- Type
- string · può essere null
- Description
Whether the cross-check's best_hs_code agreed or conflicted with the text-derived top pick.
Valori ammessi:
agree,conflict.
- Name
cross_check_best_hs_code- Type
- string · può essere null
- Description
HS code the vision cross-check model identified as the best match, if it ran.
- Name
cross_check_confidence- Type
- string · può essere null
- Description
Confidence the vision cross-check model reported for its best_hs_code pick.
Valori ammessi:
low,medium,high.
- Name
cross_check_ran- Type
- boolean
- Description
True if the multimodal rerank cross-check executed (image + shortlisted candidates).
Predefinito:
false.
- Name
sparse_text_triggered- Type
- boolean
- Description
True if the image caption was weighted as the PRIMARY search signal because the supplied product text was below the sparsity threshold.
Predefinito:
false.
LegalRef
Legal reference (footnote or legal base).
- Name
id- Type
- string
- obbligatorio
- Description
Footnote or legal base ID
- Name
text- Type
- string
- obbligatorio
- Description
Legal reference text
LanguageWarning
Warning about language availability.
Used to communicate language-related issues in classification responses and snapshot metadata. Supports two warning types:
- language_carried_forward: Description carried from previous snapshot
- language_unavailable: Language not available in any snapshot
- Name
from_snapshot- Type
- string · può essere null
- Description
Source snapshot for carried_forward warnings
- Name
lang- Type
- string
- obbligatorio
- Description
Language code (e.g., IT, DE, FR, ES)
- Name
message- Type
- string
- obbligatorio
- Description
Human-readable warning message
- Name
timestamp- Type
- string · può essere null
- Description
ISO timestamp when warning was generated
- Name
type- Type
- string
- obbligatorio
- Description
Warning type: language_carried_forward or language_unavailable
ErrorDetail
Body of every error returned through FastAPI's `HTTPException`.
- Name
detail- Type
- string
- obbligatorio
- Description
Human-readable reason. Not a stable machine code.
HTTPValidationError
- Name
detail- Type
- array of ValidationError
- Description
ValidationError
- Name
ctx- Type
- object
- Description
- Name
input- Type
- any
- Description
- Name
loc- Type
- array of string | integer
- obbligatorio
- Description
- Name
msg- Type
- string
- obbligatorio
- Description
- Name
type- Type
- string
- obbligatorio
- Description
BatchClassificationRequest
Request for batch classification.
- Name
concurrency- Type
- boolean
- Description
Enable concurrent processing (default: sequential)
Predefinito:
false.
- Name
inputs- Type
- array of PreNormalizedInput | RawPayloadInput | TitleOnlyInput
- obbligatorio
- Description
Array of classification inputs (1-100 items)
items ≥ 1, items ≤ 100.
- Name
preferred_language- Type
- string
- Description
Preferred language for descriptions (ISO 2-letter code)
Predefinito:
EN.
- Name
request_id- Type
- string · può essere null
- Description
Optional request ID (generated if not provided)
BatchClassificationResponse
Response for batch classification (HTTP 207 Multi-Status).
- Name
request_id- Type
- string
- obbligatorio
- Description
Unique request ID for correlation
- Name
results- Type
- array of BatchClassificationItem
- obbligatorio
- Description
Per-item results
BatchClassificationItem
Result for one item in batch classification.
- Name
degraded_stages- Type
- array of DegradedStage
- Description
Pipeline stages that fell back to a degraded mode for this item, if any.
- Name
error- Type
- string · può essere null
- Description
Error message if failed
- Name
genericity_flag- Type
- boolean
- Description
True if input is too generic
Predefinito:
false.
- Name
index- Type
- integer
- obbligatorio
- Description
Index in original request array
- Name
processing_ms- Type
- number
- obbligatorio
- Description
Processing time in milliseconds
- Name
questions_for_operator- Type
- array of string
- Description
Questions to improve data quality
- Name
results- Type
- array of Suggestion · può essere null
- Description
Classification suggestions if successful
- Name
retrieval_mode- Type
- string
- Description
Caller-facing summary of the retrieval fan-out for this item: 'hybrid' means all retrievers contributed; 'bm25_only' means the vector stage degraded and results are served from BM25+anchor alone.
Valori ammessi:
hybrid,bm25_only. Predefinito:hybrid.
- Name
status- Type
- string
- obbligatorio
- Description
Processing status
Valori ammessi:
success,error.
- Name
warnings- Type
- array of LanguageWarning
- Description
Language availability warnings
RefinementRequest
Request for conversational refinement of an existing classification request.
- Name
caller_type- Type
- string
- Description
Identifies the caller as an operator or customer.
Valori ammessi:
operator,customer. Predefinito:customer.
- Name
confirmed_hs_hint- Type
- string · può essere null
- Description
Optional operator-confirmed code hint to apply in this turn. AI-proposed hints are not applied unless this is provided.
- Name
excluded_hs_codes- Type
- array of string
- Description
Code prefixes to explicitly exclude in this refinement turn.
- Name
feedback_reason- Type
- string · può essere null
- Description
Optional structured reason tag (e.g. wrong_category, wrong_material_split, too_generic).
- Name
max_results- Type
- integer · può essere null
- Description
Optional override of max results for this refinement turn.
≥ 1, ≤ 10.
- Name
operator_message- Type
- string
- obbligatorio
- Description
Operator free-text feedback explaining why current suggestions are wrong or what should be preferred.
length ≥ 3, length ≤ 2000.
RefinementResponse
Response for a conversational refinement turn.
- Name
applied_hs_hint- Type
- string · può essere null
- Description
Operator-confirmed hint applied in this turn (if any).
- Name
degraded_stages- Type
- array of DegradedStage
- Description
Pipeline stages that fell back to a degraded mode, if any.
- Name
genericity_flag- Type
- boolean
- Description
True if input is too generic
Predefinito:
false.
- Name
proposed_hs_hints- Type
- array of string
- Description
AI-proposed code hints for operator consideration.
- Name
questions_for_operator- Type
- array of string
- Description
Questions to improve data quality
- Name
refine_turn- Type
- integer
- obbligatorio
- Description
Turn number in the conversation.
- Name
request_id- Type
- string
- obbligatorio
- Description
Unique request ID for correlation
- Name
results- Type
- array of Suggestion
- obbligatorio
- Description
Classification suggestions (up to max_results)
items ≥ 0, items ≤ 10.
- Name
retrieval_mode- Type
- string
- Description
Caller-facing summary of the retrieval fan-out: 'hybrid' means all retrievers contributed; 'bm25_only' means the vector stage degraded and results are served from BM25+anchor alone.
Valori ammessi:
hybrid,bm25_only. Predefinito:hybrid.
- Name
warnings- Type
- array of LanguageWarning
- Description
Language availability warnings
LookupRequest
Request for direct HS code lookup with duty and cost calculation.
- Name
alcohol_volume_pct- Type
- number · può essere null
- Description
Alcohol by volume %. Needed for alcohol-based duties (ASV X).
≥ 0, ≤ 100.
- Name
customs_value_eur- Type
- number · può essere null
- Description
Explicit CIF customs value in EUR. Takes precedence over goods_value_eur + shipping_cost_eur + insurance_eur if both are provided.
≥ 0.
- Name
destination_country- Type
- string · può essere null
- Description
ISO 2-letter destination country code. Required to resolve export controls.
- Name
energy_gj- Type
- number · può essere null
- Description
Energy content in gigajoules. Needed for energy-based duties (ENC ENP).
≥ 0.
- Name
goods_value_eur- Type
- number · può essere null
- Description
Value of goods in EUR (ex-works / invoice value). Combined with shipping_cost_eur and insurance_eur to compute CIF.
≥ 0.
- Name
hs_code- Type
- string
- obbligatorio
- Description
HS code to look up. Accepts dotted (8518.30.0090), plain digits (8518300090), or partial (8518, 851830). Minimum 4 digits. Dots and spaces are stripped automatically.
- Name
include_duties- Type
- boolean
- Description
When False, skips all duty resolution and TARIC enrichment fetches for a faster response. Returns only HS code description, hierarchy, and legal refs. Use when you only need to confirm a code exists and get its description.
Predefinito:
true.
- Name
insurance_eur- Type
- number · può essere null
- Description
Insurance cost in EUR (defaults to 0 if omitted).
≥ 0.
- Name
origin_country- Type
- string · può essere null
- Description
ISO 2-letter origin country code (e.g. 'CN', 'VN'). Required to resolve applicable duties.
- Name
preferred_language- Type
- string
- Description
Preferred language for descriptions (ISO 2-letter code)
Predefinito:
EN.
- Name
quantity- Type
- integer · può essere null
- Description
Number of items. Needed for per-unit duties (NAR, MIL).
≥ 0.
- Name
shipping_cost_eur- Type
- number · può essere null
- Description
Freight / shipping cost in EUR.
≥ 0.
- Name
volume_litres- Type
- number · può essere null
- Description
Volume in litres. Needed for volume-based duties (HLT, LTR).
≥ 0.
- Name
weight_kg- Type
- number · può essere null
- Description
Net weight in kg. Needed for specific duties (TNE, DTN, KGM).
≥ 0.
LookupResponse
Response for direct HS code lookup.
- Name
agricultural_duties- Type
- array of object
- Description
Agricultural component duties (EA)
- Name
applicable_duties- Type
- ApplicableDuties · può essere null
- Description
Resolved duties for the specified origin country
- Name
applicable_export_controls- Type
- ApplicableExportControls · può essere null
- Description
Resolved export controls for the specified destination country
- Name
cn_code- Type
- string
- obbligatorio
- Description
CN8 code (dotted, e.g. '8518.30.00')
- Name
description- Type
- string
- obbligatorio
- Description
TARIC description in the requested language
- Name
duties_export- Type
- array of object
- Description
Raw export duty entries
- Name
duties_import- Type
- array of object
- Description
Raw import duty entries
- Name
hierarchy_path- Type
- array of HierarchyPath
- Description
Classification hierarchy from HS4 heading to the matched code
- Name
hs_code- Type
- string
- obbligatorio
- Description
HS6 code (dotted, e.g. '8518.30')
- Name
legal_refs- Type
- array of LegalRef
- Description
Footnotes and legal bases attached to this code
- Name
measure_conditions- Type
- array of object
- Description
Certificate / license requirements
- Name
measure_exclusions- Type
- array of object
- Description
Country exclusions from measures
- Name
measure_footnotes- Type
- array of object
- Description
Measure-specific footnotes
- Name
shipment_costs- Type
- ShipmentCosts · può essere null
- Description
Detailed cost breakdown (only when goods/shipment values are provided)
- Name
taric_code- Type
- string
- obbligatorio
- Description
TARIC10 code (dotted, e.g. '8518.30.00.90')
- Name
warnings- Type
- array of LanguageWarning
- Description
Language availability warnings
ShipmentCosts
Detailed cost breakdown for a shipment under a given HS code.
- Name
customs_value_eur- Type
- number
- obbligatorio
- Description
CIF customs value in EUR — basis for ad valorem duty calculation (= goods + shipping + insurance, or explicitly provided)
- Name
duty_amount_eur- Type
- number · può essere null
- Description
Calculated customs duty amount in EUR (from best applicable rate)
- Name
goods_value_eur- Type
- number · può essere null
- Description
Value of goods (ex-works / FOB) in EUR
- Name
insurance_eur- Type
- number · può essere null
- Description
Insurance cost in EUR
- Name
shipping_cost_eur- Type
- number · può essere null
- Description
Freight / shipping cost in EUR
- Name
total_landed_cost_eur- Type
- number · può essere null
- Description
Total landed cost = goods + shipping + insurance + duty in EUR
- Name
vat_base_eur- Type
- number · può essere null
- Description
Customs value + duty in EUR — the base on which import VAT is typically applied
SearchRequest
Countries are accepted for caller context and do not affect v1 ranking.
- Name
destination- Type
- string · può essere null
- Description
ISO2; echoed, not used for ranking in v1.
- Name
language- Type
- string
- Description
Predefinito:
EN.
- Name
limit- Type
- integer
- Description
Predefinito:
5. ≥ 1, ≤ 20.
- Name
origin- Type
- string · può essere null
- Description
ISO2; echoed, not used for ranking in v1.
- Name
query- Type
- string
- obbligatorio
- Description
length ≥ 1, length ≤ 200.
SearchResponse
Language metadata makes an English fallback visible to the caller.
- Name
destination- Type
- string · può essere null
- Description
- Name
engine_version- Type
- string
- obbligatorio
- Description
- Name
language- Type
- string
- obbligatorio
- Description
- Name
language_fallback- Type
- boolean
- obbligatorio
- Description
- Name
origin- Type
- string · può essere null
- Description
- Name
query_language- Type
- string
- obbligatorio
- Description
- Name
results- Type
- array of SearchResult
- obbligatorio
- Description
- Name
snapshot_id- Type
- string · può essere null
- obbligatorio
- Description
- Name
took_ms- Type
- integer
- obbligatorio
- Description
SearchResult
Relative lexical relevance accompanies nomenclature hierarchy metadata.
- Name
code- Type
- string
- obbligatorio
- Description
- Name
code_formatted- Type
- string
- obbligatorio
- Description
- Name
declarable- Type
- boolean
- obbligatorio
- Description
- Name
description- Type
- string
- obbligatorio
- Description
- Name
level- Type
- string
- obbligatorio
- Description
Valori ammessi:
chapter,heading,subheading,cn8,taric10.
- Name
match- Type
- number
- obbligatorio
- Description
Relative adjusted lexical score, rounded to 3 decimals.
> 0, ≤ 1.
- Name
path- Type
- array of string
- obbligatorio
- Description