Introduzione

Questa sezione definisce gli schemi completi per ogni evento relativo agli SKU (Stock Keeping Unit) su Webround Commerce. Lo SKU rappresenta l'unità minima vendibile e tracciabile a magazzino, collegata univocamente a una variante di prodotto. Qui vengono gestite le informazioni critiche su prezzi, disponibilità stock e logiche di vendita.

Perché ascoltare gli eventi sugli SKU

L'integrazione degli eventi sugli SKU consente di gestire in tempo reale:

Sincronizzazione Stock Multi-Magazzino: Aggiornamento immediato delle quantità disponibili tra Webround e i tuoi sistemi gestionali (ERP/WMS).
Gestione Prezzi e Valute: Monitoraggio dei listini prezzi, dei prezzi di confronto (saldi) e delle diverse cadenze di pagamento.
Logiche di Vendita e Backorder: Automazione dei processi basati sulla disponibilità dei prodotti, inclusi i giorni di backorder e i limiti di quantità per ordine.
Integrazione Fiscale (Stripe): Allineamento dei codici fiscali esterni per il calcolo automatico delle tasse a checkout.

Tabella Completa Eventi e Payload

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

Evento	Payload Schema	Esempio JSON
`product-sku.created`	SKU Schema	Link
`product-sku.updated`	SKU Schema	Link
`product-sku.deleted`	SKU Deleted Schema	Link
`product-sku.stock.replaced`	SKU Stock Schema	Link
`product-sku.prices.replaced`	SKU Prices Schema	Link

Schema SKU (`productSkuCreatedSchema`)

Campo	Tipo	Note
id	`uuid`	Obbligatorio. ID univoco dello SKU
storeId	`uuid`	Obbligatorio. ID dello store di appartenenza
productId	`uuid`	Obbligatorio. ID del prodotto padre
variantId	`uuid`	Obbligatorio. ID della variante collegata
sku	`string`	Obbligatorio. Codice identificativo (Stock Keeping Unit)
isFavourite	`boolean`	Obbligatorio. Flag preferito
externalId	`string - null`	ID di riferimento in sistemi esterni (es. ERP)
useStripeTax	`boolean`	Calcolo automatico tasse tramite Stripe Tax
taxCodeExternalId	`string - null`	Codice fiscale esterno (Stripe Tax Code)
purchaseRestock	`boolean`	Abilita rifornimento stock su acquisto
allowBackorder	`boolean`	Permette l'acquisto anche se lo stock è esaurito
allowFreeShipping	`boolean`	Abilita la possibilità di spedizione gratuita
forceFreeShipping	`boolean`	Forza sempre la spedizione gratuita per questo SKU
backorderDays	`number`	Giorni stimati per il riassortimento in backorder
maxOrderQuantity	`number`	Quantità massima acquistabile per singolo ordine
createdAt	`isoDate`	Obbligatorio
updatedAt	`isoDate`	Obbligatorio

Esempio SKU

{
    "envelopeId": "a1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-sku.created",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:10:00.000Z",
    "data": {
        "id": "c1d2e3f4-g5h6-4a5b-b6c7-d8e9f0a1b2c3",
        "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "sku": "WR-TSHIRT-BLU-XL",
        "isFavourite": true,
        "externalId": "SKU-9988-EXT",
        "useStripeTax": true,
        "taxCodeExternalId": "txcd_99999999",
        "purchaseRestock": true,
        "allowBackorder": false,
        "allowFreeShipping": true,
        "forceFreeShipping": false,
        "backorderDays": 0,
        "maxOrderQuantity": 10,
        "createdAt": "2026-02-22T23:10:00.000Z",
        "updatedAt": "2026-02-22T23:10:00.000Z"
    },
    "eventId": "e4f5g6h7-i8j9-4a5b-b6c7-d8e9f0a1b2c3"
}

Schema SKU Eliminato (`productSkuDeletedSchema`)

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

Esempio SKU Eliminato

{
    "envelopeId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-sku.deleted",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:15:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "skuId": "c1d2e3f4-g5h6-4a5b-b6c7-d8e9f0a1b2c3"
    },
    "eventId": "f5g6h7i8-j9k0-4a5b-b6c7-d8e9f0a1b2c3"
}

Schema Stock SKU (`productSkuStockReplacedSchema`)

Campo	Tipo	Note
productId	`uuid`	Obbligatorio
variantId	`uuid`	Obbligatorio
skuId	`uuid`	Obbligatorio
stock	`object[]`	Obbligatorio. Array delle giacenze per magazzino
stock[].warehouseId	`uuid`	Obbligatorio. ID del magazzino
stock[].quantity	`number`	Obbligatorio. Quantità intera disponibile

Esempio Stock SKU

{
    "envelopeId": "c3d4e5f6-g7h8-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-sku.stock.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:20:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "skuId": "c1d2e3f4-g5h6-4a5b-b6c7-d8e9f0a1b2c3",
        "stock": [
            {
                "warehouseId": "w1z2x3c4-v5b6-4n7m-8a9s-d0f1g2h3j4k5",
                "quantity": 150
            },
            {
                "warehouseId": "w9z8x7c6-v5b4-4n3m-2a1s-d0f9g8h7j6k5",
                "quantity": 45
            }
        ]
    },
    "eventId": "g6h7i8j9-k0l1-4a5b-b6c7-d8e9f0a1b2c3"
}

Schema Prezzi SKU (`productSkuPricesReplacedSchema`)

Campo	Tipo	Note
productId	`uuid`	Obbligatorio
variantId	`uuid`	Obbligatorio
skuId	`uuid`	Obbligatorio
prices	`object[]`	Obbligatorio. Elenco dei listini prezzi applicati
prices[].currencyCode	`string`	Obbligatorio. Codice ISO valuta (es. "EUR")
prices[].cadence	`string`	Obbligatorio. Frequenza di pagamento (es. "once", "month")
prices[].amount	`string`	Obbligatorio. Prezzo in formato stringa decimale
prices[].comparePrice	`string - null`	Prezzo originale per visualizzazione sconti
prices[].externalId	`string - null`	ID del prezzo su sistemi esterni (es. Stripe Price ID)
prices[].isDefault	`boolean`	Obbligatorio. Identifica il prezzo principale
prices[].quantityTable	`any - null`	Tabella per sconti quantità (Tiered Pricing)

Esempio Prezzi SKU

{
    "envelopeId": "d4e5f6g7-h8i9-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-sku.prices.replaced",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:25:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "skuId": "c1d2e3f4-g5h6-4a5b-b6c7-d8e9f0a1b2c3",
        "prices": [
            {
                "currencyCode": "EUR",
                "cadence": "once",
                "amount": "29.90",
                "comparePrice": "39.90",
                "externalId": "price_1Gs9X2L...",
                "isDefault": true,
                "quantityTable": null
            }
        ]
    },
    "eventId": "h7i8j9k0-l1m2-4a5b-b6c7-d8e9f0a1b2c3"
}

Perché ascoltare gli eventi sugli SKU

Tabella Completa Eventi e Payload

Schema SKU (productSkuCreatedSchema)​

Esempio SKU​

Schema SKU Eliminato (productSkuDeletedSchema)​

Esempio SKU Eliminato​

Schema Stock SKU (productSkuStockReplacedSchema)​

Esempio Stock SKU​

Schema Prezzi SKU (productSkuPricesReplacedSchema)​

Esempio Prezzi SKU​