Introduzione

Questa sezione definisce gli schemi completi per ogni evento relativo ai prodotti su Webround Commerce.

Perché ascoltare gli eventi sui prodotti

L'integrazione degli eventi sui prodotti consente di gestire in tempo reale:

Sincronizzazione del catalogo su marketplace esterni (Amazon, eBay, etc.).
Aggiornamento automatico di feed marketing e social commerce.
Gestione centralizzata degli asset multimediali su CDN esterne.
Integrazione con sistemi gestionali (ERP) per la logistica e le anagrafiche tecniche.

Tabella Completa Eventi e Payload

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

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

Schema Prodotto (`productCreatedSchema`)

Campo	Tipo	Note
id	`uuid`	Obbligatorio
name	`string`	Obbligatorio
seoDescription	`string - null`	Descrizione per motori di ricerca
htmlDescription	`string - null`	Descrizione sanitizzata (HTML)
visible	`boolean`	Obbligatorio (Stato pubblicazione)
metadata	`object - null`	Metadati del prodotto
deliveryMethods	`string[]`	Obbligatorio (es. `["shipping", "digital"]`)
packageWeight	`number - null`	Peso in grammi (Intero)
packageLength	`number - null`	Lunghezza in mm (Intero)
packageWidth	`number - null`	Larghezza in mm (Intero)
packageHeight	`number - null`	Altezza in mm (Intero)
defaultTaxRate	`number - null`	Aliquota IVA predefinita (Intero)
defaultStripeTaxRateId	`string - null`	ID Aliquota Stripe
disableCoupons	`boolean`	Obbligatorio
createdAt	`isoDate`	Obbligatorio
updatedAt	`isoDate`	Obbligatorio
translations	`object - null`	Oggetto contenente le traduzioni localizzate

Esempio Prodotto

{
    "envelopeId": "57bb3d09-0a9b-4f00-a3b5-7ccee22ed9b3",
    "eventType": "product.created",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:15:00.000Z",
    "data": {
        "id": "5a90f5ed-2785-44df-958b-841d0148a711",
        "name": "T-Shirt Ufficiale Webround",
        "seoDescription": "La t-shirt ufficiale in cotone.",
        "htmlDescription": "<p>T-shirt <strong>100% cotone</strong>.</p>",
        "visible": true,
        "deliveryMethods": ["shipping"],
        "packageWeight": 250,
        "packageLength": 300,
        "packageWidth": 200,
        "packageHeight": 20,
        "defaultTaxRate": 22,
        "defaultStripeTaxRateId": "txr_...",
        "disableCoupons": false,
        "createdAt": "2026-02-22T21:15:00.000Z",
        "updatedAt": "2026-02-22T21:15:00.000Z",
        "translations": {
            "en": {
                "name": "Official Webround T-Shirt",
                "seoDescription": "The official organic cotton t-shirt."
            }
        }
    },
    "eventId": "54f3d2ac-7cf4-40ec-acef-38fffaf60c94"
}

Schema Prodotto Eliminato (`productDeletedSchema`)

Campo	Tipo	Note
id	`uuid`	Obbligatorio (ID del prodotto eliminato)

Esempio Prodotto Eliminato

{
    "envelopeId": "0b1c2d3e-4f5g-6h7i-8j9k-l0m1n2o3p4q5",
    "eventType": "product.deleted",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:20:00.000Z",
    "data": {
        "id": "a7b6c5d4-e3f2-1g0h-i9j8-k7l6m5n4o3p2"
    },
    "eventId": "f2e1d0c9-b8a7-4a7b-b8c9-d0e1f2a3b4c5"
}

Schema Asset Prodotto (`productAssetReplacedSchema`)

Questo evento viene emesso quando l'intera collezione di asset (immagini, video, documenti) di un prodotto viene aggiornata o sovrascritta.

Campo	Tipo	Note
productId	`uuid v4`	Obbligatorio
assets	`object[]`	Obbligatorio. Array di oggetti asset
assets[].id	`uuid v4`	Obbligatorio
assets[].url	`string`	Obbligatorio. URL pubblico dell'asset
assets[].type	`string`	Obbligatorio (es. `image/jpeg`, `video/mp4`)
assets[].fileName	`string - null`	Nome originale del file
assets[].size	`number - null`	Dimensione in byte
assets[].alt	`string - null`	Testo alternativo per l'accessibilità
assets[].thumbnail	`string - null`	URL della miniatura (se applicabile)
assets[].externalId	`string - null`	ID riferimento su storage esterno
assets[].createdAt	`isoDate`	Obbligatorio
assets[].updatedAt	`isoDate`	Obbligatorio

Esempio Asset Prodotto

{
    "envelopeId": "a1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product.assets.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:30:00.000Z",
    "data": {
        "productId": "a7b6c5d4-e3f2-41d4-a716-446655440000",
        "assets": [
            {
                "id": "e5f6g7h8-i9j0-4c3d-d4e5-f6g7h8i9j0k1",
                "url": "https://cdn.webround.com/assets/product-main.jpg",
                "type": "image/jpeg",
                "fileName": "tshirt-front.jpg",
                "size": 102400,
                "alt": "T-Shirt Front View",
                "thumbnail": null,
                "externalId": null,
                "createdAt": "2026-02-22T21:30:00.000Z",
                "updatedAt": "2026-02-22T21:30:00.000Z"
            }
        ]
    },
    "eventId": "f3e2d1c0-b9a8-4a7b-b8c9-d0e1f2a3b4c5"
}

Schema Attributi Prodotto (`productAttributeReplacedSchema`)

Questo schema viene utilizzato quando gli attributi tecnici di un prodotto (es. materiale, collezione, specifiche tecniche) vengono aggiornati massivamente.

Campo	Tipo	Note
productId	`uuid v4`	Obbligatorio
attributes	`object[]`	Obbligatorio. Elenco degli attributi associati
attributes[].attributeId	`uuid v4`	Obbligatorio. Riferimento all'anagrafica attributo
attributes[].value	`string`	Obbligatorio. Valore assegnato all'attributo

Esempio Attributi Prodotto

{
    "envelopeId": "b8c9d0e1-f2a3-4b4c-5d6e-7f8g9h0i1j2k",
    "eventType": "product.attributes.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:40:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "attributes": [
            {
                "attributeId": "a1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3",
                "value": "CODE_ABCDEF"
            },
            {
                "attributeId": "9f8e7d6c-5b4a-3f2e-1d0c-b9a8f7e6d5c4",
                "value": "2100"
            }
        ]
    },
    "eventId": "219c43f2-84c5-4889-9309-f2bd35f6b25d"
}

Schema Tag Prodotto (`productTagReplacedSchema`)

Questo evento viene emesso quando l'intero set di valori tag associati a un prodotto viene sovrascritto. I tag vengono utilizzati per la categorizzazione, i filtri e l'organizzazione logica del catalogo.

Campo	Tipo	Note
productId	`uuid v4`	Obbligatorio
tagValues	`object[]`	Obbligatorio. Array dei valori tag correnti
tagValues[].id	`uuid v4`	Obbligatorio. ID univoco del valore tag
tagValues[].tagId	`uuid v4`	Obbligatorio. ID della categoria tag di appartenenza
tagValues[].storeId	`uuid v4`	Obbligatorio
tagValues[].value	`string`	Obbligatorio. Il valore testuale del tag
tagValues[].alias	`string - null`	Slug/Alias per URL o riferimenti interni
tagValues[].visible	`boolean`	Obbligatorio. Visibilità sul frontend
tagValues[].createdAt	`isoDate`	Obbligatorio
tagValues[].updatedAt	`isoDate`	Obbligatorio

Esempio Tag Prodotto

{
    "envelopeId": "d1e2f3g4-h5i6-4a7b-b8c9-d0e1f2a3b4c5",
    "eventType": "product.tags.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:45:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "tagValues": [
            {
                "id": "e2f3g4h5-i6j7-k8l9-m0n1-o2p3q4r5s6t7",
                "tagId": "f3g4h5i6-j7k8-l9m0-n1o2-p3q4r5s6t7u8",
                "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
                "value": "Nuova Collezione",
                "alias": "nuova-collezione",
                "visible": true,
                "createdAt": "2026-02-22T21:40:00.000Z",
                "updatedAt": "2026-02-22T21:40:00.000Z"
            },
            {
                "id": "773d3d88-9c4a-52b8-0c45-93a2d19c5e88",
                "tagId": "337d3d88-9c4a-52b8-0c45-93a2d19c5e99",
                "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
                "value": "Eco-Friendly",
                "alias": "eco",
                "visible": true,
                "createdAt": "2026-02-22T21:42:00.000Z",
                "updatedAt": "2026-02-22T21:42:00.000Z"
            }
        ]
    },
    "eventId": "f4e3d2c1-b0a9-4131-8e9b-c5b7539f152a"
}

Schema Opzioni Prodotto (`productOptionValuesReplacedSchema`)

Definisce l'ordinamento e l'associazione delle opzioni del prodotto (es. Taglia, Colore) ai relativi valori tag.

Campo	Tipo	Note
productId	`uuid v4`	Obbligatorio
options	`object[]`	Obbligatorio. Array di configurazione opzioni
options[].optionId	`uuid v4`	Obbligatorio. ID dell'opzione
options[].tagValueId	`uuid v4 - null`	Riferimento al valore tag associato
options[].position	`number`	Obbligatorio. Indice di posizionamento

Esempio Opzioni Prodotto

{
    "envelopeId": "e1f2g3h4-i5j6-4a7b-b8c9-d0e1f2a3b4c5",
    "eventType": "product.option-values.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:50:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "options": [
            {
                "optionId": "b1b2b3b4-b5b6-4b7b-b8b9-b0b1b2b3b4b5",
                "tagValueId": "e2f3g4h5-i6j7-k8l9-m0n1-o2p3q4r5s6t7",
                "position": 0
            }
        ]
    },
    "eventId": "12345678-1234-4321-abcd-1234567890ab"
}

Schema Metodi di Spedizione (`productShippingMethodsReplacedSchema`)

Campo	Tipo	Note
productId	`uuid v4`	Obbligatorio
shippingMethods	`object[]`	Obbligatorio. Metodi di spedizione abilitati
shippingMethods[].label	`string`	Nome del metodo
shippingMethods[].pricing	`any`	Configurazione prezzi/regole
shippingMethods[].enabled	`boolean`	Obbligatorio

Esempio Metodi Spedizione

{
    "envelopeId": "f1g2h3i4-j5k6-4a7b-b8c9-d0e1f2a3b4c5",
    "eventType": "product.shipping-methods.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "shippingMethods": [
            {
                "id": "s1s2s3s4-s5s6-4s7s-s8s9-s0s1s2s3s4s5",
                "label": "Corriere Espresso",
                "availableCountries": ["IT", "FR", "DE"],
                "enabled": true,
                "createdAt": "2026-02-22T21:55:00.000Z",
                "updatedAt": "2026-02-22T21:55:00.000Z"
            }
        ]
    },
    "eventId": "87654321-4321-1234-dcba-ba0987654321"
}

Schema Zone di Spedizione (`productShippingZonesReplacedSchema`)

Campo	Tipo	Note
productId	`uuid v4`	Obbligatorio
shippingZones[].countryCode	`string`	Obbligatorio. Codice ISO nazione
shippingZones[].taxRate	`number`	Obbligatorio. Aliquota per la zona

Esempio Zone Spedizione

{
    "envelopeId": "g1h2i3j4-k5l6-4a7b-b8c9-d0e1f2a3b4c5",
    "eventType": "product.shipping-zones.replaced",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "shippingZones": [
            {
                "id": "z1z2z3z4-z5z6-4z7z-z8z9-z0z1z2z3z4z5",
                "label": "Italia Continentale",
                "countryCode": "IT",
                "taxRate": 22,
                "createdAt": "2026-02-22T21:58:00.000Z",
                "updatedAt": "2026-02-22T21:58:00.000Z"
            }
        ]
    },
    "eventId": "abcdef12-3456-7890-abcd-ef1234567890"
}

Schema Zone Fiscali (`productTaxZonesReplacedSchema`)

Campo	Tipo	Note
productId	`uuid v4`	Obbligatorio
taxZones[].rate	`number`	Obbligatorio. Percentuale tassa
taxZones[].isDefault	`boolean`	Obbligatorio

Esempio Zone Fiscali

{
    "envelopeId": "h1i2j3k4-l5m6-4a7b-b8c9-d0e1f2a3b4c5",
    "eventType": "product.tax-zones.replaced",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "taxZones": [
            {
                "id": "t1t2t3t4-t5t6-4t7t-t8t9-t0t1t2t3t4t5",
                "label": "IVA Standard",
                "rate": 22,
                "isDefault": true,
                "createdAt": "2026-02-22T22:00:00.000Z",
                "updatedAt": "2026-02-22T22:00:00.000Z"
            }
        ]
    },
    "eventId": "fdecba98-7654-3210-fedc-ba9876543210"
}

Perché ascoltare gli eventi sui prodotti

Tabella Completa Eventi e Payload

Schema Prodotto (productCreatedSchema)​

Esempio Prodotto​

Schema Prodotto Eliminato (productDeletedSchema)​

Esempio Prodotto Eliminato​

Schema Asset Prodotto (productAssetReplacedSchema)​

Esempio Asset Prodotto​

Schema Attributi Prodotto (productAttributeReplacedSchema)​

Esempio Attributi Prodotto​

Schema Tag Prodotto (productTagReplacedSchema)​

Esempio Tag Prodotto​

Schema Opzioni Prodotto (productOptionValuesReplacedSchema)​

Esempio Opzioni Prodotto​

Schema Metodi di Spedizione (productShippingMethodsReplacedSchema)​

Esempio Metodi Spedizione​

Schema Zone di Spedizione (productShippingZonesReplacedSchema)​

Esempio Zone Spedizione​

Schema Zone Fiscali (productTaxZonesReplacedSchema)​

Esempio Zone Fiscali​