Introduzione

Questa sezione definisce gli schemi completi per ogni evento relativo alle Varianti Prodotto su Webround Commerce. Le varianti permettono una gestione granulare del catalogo, consentendo a ogni combinazione di opzioni (es. Taglia/Colore) di avere i propri dati specifici o di ereditarli dal prodotto padre.

Perché ascoltare gli eventi sulle varianti

L'integrazione degli eventi sulle varianti consente di gestire in tempo reale:

Sincronizzazione SKU: Gestione di inventari e codici a barre distinti per ogni combinazione.
Logistica Specifica: Definizione di pesi e dimensioni pacco per varianti che differiscono dal prodotto base.
Ereditarietà Dati: Monitoraggio dei flag di ereditarietà per capire quali dati sono sovrascritti (asset, tag, zone fiscali).
Automazione Marketplace: Aggiornamento delle schede prodotto figlie su piattaforme esterne.

Tabella Completa Eventi e Payload

Ecco la tabella completa con tutti i link ai relativi esempi JSON:

Evento	Payload Schema	Esempio JSON
`product-variant.created`	Variant Schema	Link
`product-variant.updated`	Variant Schema	Link
`product-variant.deleted`	Variant Deleted Schema	Link
`product-variant.assets.replaced`	Variant Assets Schema	Link
`product-variant.attributes.replaced`	Variant Attributes Schema	Link
`product-variant.tags.replaced`	Variant Tags Schema	Link
`product-variant.shipping-methods.replaced`	Variant Shipping Methods	Link
`product-variant.shipping-zones.replaced`	Variant Shipping Zones	Link
`product-variant.tax-zones.replaced`	Variant Tax Zones	Link

Schema Variante (`productVariantCreatedSchema`)

Campo	Tipo	Note
productId	`uuid`	Obbligatorio. ID del prodotto padre
variantId	`uuid`	Obbligatorio. ID univoco della variante
name	`string`	Obbligatorio. Nome della variante
slug	`string`	Obbligatorio. Slug per URL
visible	`boolean`	Obbligatorio. Stato pubblicazione
isFavourite	`boolean`	Obbligatorio. Flag per varianti in evidenza
inheritAssets	`boolean`	Eredita asset dal prodotto padre
inheritTagValues	`boolean`	Eredita i tag dal prodotto padre
inheritAttributes	`boolean`	Eredita attributi tecnici dal prodotto padre
inheritPackageDimensions	`boolean`	Eredita dimensioni pacco dal prodotto padre
inheritShippingMethods	`boolean`	Eredita metodi spedizione dal prodotto padre
inheritShippingZones	`boolean`	Eredita zone spedizione dal prodotto padre
inheritTaxZones	`boolean`	Eredita zone fiscali dal prodotto padre
inheritDisableCoupons	`boolean`	Eredita restrizioni coupon dal prodotto padre
disableCoupons	`boolean`	Forza disabilitazione coupon su questa variante
packageWeight	`number - null`	Peso specifico (grammi)
packageLength	`number - null`	Lunghezza specifica (mm)
packageWidth	`number - null`	Larghezza specifica (mm)
packageHeight	`number - null`	Altezza specifica (mm)
createdAt	`isoDate`	Obbligatorio
updatedAt	`isoDate`	Obbligatorio
metadata	`any`	Metadati custom
translations	`any`	Traduzioni localizzate

Esempio Variante

{
    "envelopeId": "6ded36ec-895c-4259-af34-1eda960a81c6",
    "eventType": "product-variant.created",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:30:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "name": "T-Shirt Webround - Blue - XL",
        "slug": "t-shirt-webround-blue-xl",
        "visible": true,
        "isFavourite": false,
        "inheritAssets": false,
        "inheritTagValues": true,
        "inheritAttributes": true,
        "inheritPackageDimensions": true,
        "inheritShippingMethods": true,
        "inheritShippingZones": true,
        "inheritTaxZones": true,
        "inheritDisableCoupons": true,
        "disableCoupons": false,
        "packageWeight": 300,
        "packageLength": null,
        "packageWidth": null,
        "packageHeight": null,
        "createdAt": "2026-02-22T22:30:00.000Z",
        "updatedAt": "2026-02-22T22:30:00.000Z",
        "metadata": null,
        "translations": {
            "en": { "name": "Webround T-Shirt - Blue - XL" }
        }
    },
    "eventId": "f4e3d2c1-b0a9-4131-8e9b-c5b7539f152a"
}

Schema Variante Eliminata (`productVariantDeletedSchema`)

Campo	Tipo	Note
productId	`uuid`	Obbligatorio
variantId	`uuid`	Obbligatorio

Esempio Variante Eliminata

{
    "envelopeId": "121bf365-57cf-45b2-a9ba-6e0b008d3bb8",
    "eventType": "product-variant.deleted",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:35:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3"
    },
    "eventId": "f2e1d0c9-b8a7-4a7b-b8c9-d0e1f2a3b4c5"
}

Schema Asset Variante (`productVariantAssetReplacedSchema`)

Campo	Tipo	Note
productId	`uuid`	Obbligatorio
variantId	`uuid`	Obbligatorio
assets	`object[]`	Obbligatorio. Array di oggetti asset specifici per la variante
assets[].id	`uuid`	Obbligatorio
assets[].url	`string`	Obbligatorio. URL pubblico dell'asset
assets[].type	`string`	Obbligatorio (es. `image/png`)
assets[].fileName	`string - null`	Nome originale del file
assets[].size	`number - null`	Dimensione in byte
assets[].alt	`string - null`	Testo alternativo
assets[].thumbnail	`string - null`	URL miniatura
assets[].externalId	`string - null`	Riferimento storage esterno

Esempio Asset Variante

{
    "envelopeId": "121bf365-57cf-45b2-a9ba-6e0b008d3bb8",
    "eventType": "product-variant.assets.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:40:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "assets": [
            {
                "id": "e87c6806-fa7f-442a-b002-ab2765d6ce6d",
                "url": "https://cdn.webround.com/assets/variant-blue.jpg",
                "type": "image/jpeg",
                "fileName": "blue.jpg",
                "size": 150000,
                "alt": "T-Shirt Blue View",
                "thumbnail": null,
                "externalId": null
            }
        ]
    },
    "eventId": "219c43f2-84c5-4889-9309-f2bd35f6b25d"
}

Schema Attributi Variante (`productVariantAttributeReplacedSchema`)

Campo	Tipo	Note
productId	`uuid`	Obbligatorio
variantId	`uuid`	Obbligatorio
attributes	`object[]`	Obbligatorio. Attributi tecnici della variante
attributes[].attributeId	`uuid`	Obbligatorio. ID anagrafica attributo
attributes[].value	`string`	Obbligatorio. Valore dell'attributo

Esempio Attributi Variante

{
    "envelopeId": "d6e7f8g9-h0i1-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-variant.attributes.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:45:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "attributes": [
            {
                "attributeId": "a1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3",
                "value": "2000"
            }
        ]
    },
    "eventId": "320d54f3-95d6-5990-0410-03ce46g7c36e"
}

Schema Tag Variante (`productVariantTagReplacedSchema`)

Campo	Tipo	Note
productId	`uuid`	Obbligatorio
variantId	`uuid`	Obbligatorio
tagValues	`object[]`	Obbligatorio. Array dei valori tag correnti della variante
tagValues[].id	`uuid`	Obbligatorio. ID univoco del valore tag
tagValues[].tagId	`string`	Obbligatorio. ID della categoria tag
tagValues[].storeId	`string`	Obbligatorio
tagValues[].value	`string`	Obbligatorio. Valore testuale
tagValues[].alias	`string - null`	Slug per URL o riferimenti interni
tagValues[].visible	`boolean`	Obbligatorio. Visibilità frontend

Esempio Tag Variante

{
    "envelopeId": "0aaefdc7-237b-4aa5-9747-ddfb3e328e7c",
    "eventType": "product-variant.tags.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:05:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "tagValues": [
            {
                "id": "fd273b45-4332-4b82-a142-347efb60f30d",
                "tagId": "3f1bb99f-eea1-4bf7-8dfd-710c86dea0b2",
                "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
                "value": "Edizione Limitata",
                "alias": "limited-edition",
                "visible": true,
                "createdAt": "2026-02-22T23:00:00.000Z",
                "updatedAt": "2026-02-22T23:00:00.000Z"
            }
        ]
    },
    "eventId": "e87c6806-fa7f-442a-b002-ab2765d6ce6d"
}

Schema Metodi Spedizione Variante (`productVariantShippingMethodsReplacedSchema`)

Campo	Tipo	Note
productId	`uuid`	Obbligatorio
variantId	`uuid`	Obbligatorio
shippingMethods	`object[]`	Obbligatorio. Metodi di spedizione specifici
shippingMethods[].label	`string`	Nome del metodo
shippingMethods[].availableCountries	`string[]`	Codici ISO paesi abilitati
shippingMethods[].pricing	`any`	Configurazione tariffe
shippingMethods[].enabled	`boolean`	Obbligatorio

Esempio Metodi Spedizione Variante

{
    "envelopeId": "0aaefdc7-237b-4aa5-9747-ddfb3e328e7c",
    "eventType": "product-variant.shipping-methods.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:50:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "shippingMethods": [
            {
                "id": "57bb3d09-0a9b-4f00-a3b5-7ccee22ed9b3",
                "label": "Corriere Espresso Variante",
                "provider": "DHL",
                "availableCountries": ["IT"],
                "etaMin": 24,
                "etaMax": 48,
                "pricing": {},
                "enabled": true,
                "maxWeight": 5000,
                "maxVolume": null,
                "assetId": null
            }
        ]
    },
    "eventId": "fbb514c4-9266-4a84-9ae5-01b1e012bd04"
}

Schema Zone Spedizione Variante (`productVariantShippingZonesReplacedSchema`)

Campo	Tipo	Note
productId	`uuid`	Obbligatorio
variantId	`uuid`	Obbligatorio
shippingZones	`object[]`	Obbligatorio. Zone di spedizione specifiche
shippingZones[].countryCode	`string`	Obbligatorio. Codice ISO nazione
shippingZones[].taxRate	`number`	Obbligatorio. Aliquota per la zona

Esempio Zone Spedizione Variante

{
    "envelopeId": "f8g9h0i1-j2k3-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-variant.shipping-zones.replaced",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:55:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "shippingZones": [
            {
                "id": "8e83373e-3ff7-48c7-bf32-ef0677835446",
                "label": "Italia Continentale",
                "countryCode": "IT",
                "surchargePricing": null,
                "taxRate": 22,
                "stripeTaxRateId": "txr_123"
            }
        ]
    },
    "eventId": "1a6a5220-4964-4708-9c99-1c1860448676"
}

Schema Zone Fiscali Variante (`productVariantTaxZonesReplacedSchema`)

Campo	Tipo	Note
productId	`uuid`	Obbligatorio
variantId	`uuid`	Obbligatorio
taxZones	`object[]`	Obbligatorio. Configurazione fiscale specifica
taxZones[].rate	`number`	Obbligatorio. Percentuale tassa
taxZones[].isDefault	`boolean`	Obbligatorio

Esempio Zone Fiscali Variante

{
    "envelopeId": "33ec26e5-f8bd-40fa-ac1d-c5a3a207a330",
    "eventType": "product-variant.tax-zones.replaced",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:58:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "taxZones": [
            {
                "id": "af3e7355-d663-4a6b-a295-decd8d87dbdc",
                "label": "IVA Agevolata Variante",
                "rate": 10,
                "stripeId": "txr_456",
                "countryCode": "IT",
                "isDefault": false
            }
        ]
    },
    "eventId": "1a6a5220-4964-4708-9c99-1c1860448676"
}

Perché ascoltare gli eventi sulle varianti

Tabella Completa Eventi e Payload

Schema Variante (productVariantCreatedSchema)​

Esempio Variante​

Schema Variante Eliminata (productVariantDeletedSchema)​

Esempio Variante Eliminata​

Schema Asset Variante (productVariantAssetReplacedSchema)​

Esempio Asset Variante​

Schema Attributi Variante (productVariantAttributeReplacedSchema)​

Esempio Attributi Variante​

Schema Tag Variante (productVariantTagReplacedSchema)​

Esempio Tag Variante​

Schema Metodi Spedizione Variante (productVariantShippingMethodsReplacedSchema)​

Esempio Metodi Spedizione Variante​

Schema Zone Spedizione Variante (productVariantShippingZonesReplacedSchema)​

Esempio Zone Spedizione Variante​

Schema Zone Fiscali Variante (productVariantTaxZonesReplacedSchema)​

Esempio Zone Fiscali Variante​