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.

POST/easydogana/normalize

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 400 UNSUPPORTED_VERSION, a retired one with 410 VERSION_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

Richiesta

POST
/easydogana/normalize
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"
}
POST/easydogana/normalize/batch

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 400 UNSUPPORTED_VERSION, a retired one with 410 VERSION_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 own status and result or error. The call returns HTTP 207, not 200.BatchNormalizationResponse
  • 400Invalid input value.ErrorDetail
  • 401Missing, malformed, expired or wrongly-scoped credentials.ErrorDetail
  • 403The token is valid but carries none of the required scopes.ErrorDetail
  • 422Request body failed schema validation (detail is a list of errors), or the payload could not be normalised (detail is a string).HTTPValidationError | ErrorDetail
  • 500Unexpected engine error.ErrorDetail

Richiesta

POST
/easydogana/normalize/batch
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

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.

Was this page helpful?