Normalizzazione
Normalizza i dati grezzi di prodotto di shop e marketplace in testi puliti che il classificatore capisce. Usala quando vuoi controllare o salvare i dati normalizzati prima di classificare.
Normalize a product payload
Normalize a single product payload.
Accepts MarketRock Product or Generic Product payloads. Returns normalized text bundle and genericity detection.
Args: request: Normalization request with product payload
Returns: NormalizationResponse with request_id and normalized entity
Raises: HTTPException 422: If normalization fails HTTPException 400: If payload is invalid HTTPException 500: If unexpected error occurs
Scope richiesto: ai-engine:easydogana:normalize: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 NormalizationRequest
- Name
payload- Type
- MarketRockProduct | GenericProduct
- obbligatorio
- Description
Product payload (MarketRock Product or Generic)
- Name
request_id- Type
- string · può essere null
- Description
Optional request ID (generated if not provided)
Risposte
200Successful ResponseNormalizationResponse400Invalid input value.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 payload could not be normalised (detailis a string).HTTPValidationError | ErrorDetail500Unexpected engine error.ErrorDetail
Richiesta
Caricamento...
Risposta 200
{
"entity": {
"identifiers": {
"sku": "TS-001"
},
"is_generic": false,
"quality_score": 85,
"questions_for_operator": [],
"text_bundle": "[Apparel] Cotton T-shirt, crew neck: Short-sleeve crew-neck T-shirt, 100% cotton, jersey knit. (attrs: material: cotton, colour: white) [sku: TS-001]"
},
"request_id": "550e8400-e29b-41d4-a716-446655440002"
}Normalize up to 100 product payloads
Normalize multiple product payloads.
Processes 1-100 payloads per request. Returns HTTP 207 Multi-Status with per-item results. Set concurrency: true in the request body to process items concurrently.
Args: request: Batch normalization request with payloads array
Returns: BatchNormalizationResponse with request_id and per-item results
Raises: HTTPException 500: If unexpected error occurs
Scope richiesto: ai-engine:easydogana:normalize: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 BatchNormalizationRequest
- Name
concurrency- Type
- boolean
- Description
Enable concurrent processing (default: sequential)
Predefinito:
false.
- Name
payloads- Type
- array of MarketRockProduct | GenericProduct
- obbligatorio
- Description
Array of product payloads (1-100 items)
items ≥ 1, items ≤ 100.
- 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.BatchNormalizationResponse400Invalid input value.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 payload could not be normalised (detailis a string).HTTPValidationError | ErrorDetail500Unexpected engine error.ErrorDetail
Richiesta
Caricamento...
Risposta 207
{
"request_id": "550e8400-e29b-41d4-a716-446655440003",
"results": [
{
"entity": {
"identifiers": {
"sku": "TS-001"
},
"is_generic": false,
"quality_score": 85,
"questions_for_operator": [],
"text_bundle": "[Apparel] Cotton T-shirt, crew neck: Short-sleeve crew-neck T-shirt, 100% cotton, jersey knit. (attrs: material: cotton, colour: white) [sku: TS-001]"
},
"index": 0,
"processing_ms": 12.5,
"status": "success"
},
{
"error": "Failed to normalize product: Field 'description' is required",
"index": 1,
"processing_ms": 2.1,
"status": "error"
}
]
}Modelli
Oggetti usati dalle richieste e dalle risposte di questa pagina.
NormalizationRequest
Request for single product normalization.
- Name
payload- Type
- MarketRockProduct | GenericProduct
- obbligatorio
- Description
Product payload (MarketRock Product or Generic)
- Name
request_id- Type
- string · può essere null
- Description
Optional request ID (generated if not provided)
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
NormalizationResponse
Response for single product normalization.
- Name
entity- Type
- NormalizedEntity
- obbligatorio
- Description
Normalized product entity
- Name
request_id- Type
- string
- obbligatorio
- Description
Unique request ID for correlation
NormalizedEntity
Normalized product entity with text bundle and genericity detection.
- 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
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
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
BatchNormalizationRequest
Request for batch product normalization.
- Name
concurrency- Type
- boolean
- Description
Enable concurrent processing (default: sequential)
Predefinito:
false.
- Name
payloads- Type
- array of MarketRockProduct | GenericProduct
- obbligatorio
- Description
Array of product payloads (1-100 items)
items ≥ 1, items ≤ 100.
- Name
request_id- Type
- string · può essere null
- Description
Optional request ID (generated if not provided)
BatchNormalizationResponse
Response for batch normalization (HTTP 207 Multi-Status).
- Name
request_id- Type
- string
- obbligatorio
- Description
Unique request ID for correlation
- Name
results- Type
- array of BatchResultItem
- obbligatorio
- Description
Per-item results
BatchResultItem
Result for one item in batch normalization.
- Name
entity- Type
- NormalizedEntity · può essere null
- Description
Normalized entity if successful
- Name
error- Type
- string · può essere null
- Description
Error message if failed
- Name
index- Type
- integer
- obbligatorio
- Description
Index in original request array
- Name
processing_ms- Type
- number
- obbligatorio
- Description
Processing time in milliseconds
- Name
status- Type
- string
- obbligatorio
- Description
Processing status
Valori ammessi:
success,error.