CartItem

L'oggetto CartItem rappresenta una singola voce all'interno del carrello. A differenza di un semplice SKU, è un'entità "arricchita" che aggrega dati logistici, fiscali e di spedizione calcolati in tempo reale per permettere una gestione precisa del checkout.

Definizione CartItem

Proprietà	Tipo	Descrizione
id	string (UUID)	Identificativo univoco della voce nel carrello.
skuId	string (UUID)	Identificativo dello SKU specifico aggiunto.
variantId	string (UUID)	Identificativo della variante di appartenenza.
productId	string (UUID)	Identificativo del prodotto radice.
variantName	string	Nome della variante visualizzato nel carrello.
variantSlug	string	Slug per il link alla pagina prodotto.
coverUrl	string	URL dell'immagine di copertina dell'articolo.
quantity	number	Quantità selezionata dall'utente.
available	number	Quantità effettivamente disponibile a magazzino.
isAvailable	boolean	Indica se l'articolo è attualmente acquistabile.

---

Prezzi e Valuta

I valori di prezzo riflettono lo stato al momento dell'aggiunta al carrello, includendo eventuali sconti di quantità (tier pricing) già calcolati.

Proprietà	Tipo	Descrizione
priceId	string (UUID)	ID del listino prezzi applicato.
originalPrice	number	Prezzo unitario base (lordo).
netAmount	number	Prezzo unitario netto.
totalAmount	number	Totale lordo della riga (prezzo unitario * quantità).
currencyCode	string	Codice valuta (es. EUR).
cadence	string	Frequenza di pagamento (es. once).

---

Logistica e Spedizione

Questi dati permettono al motore di webround.com di calcolare automaticamente i costi di spedizione e gestire i vincoli fisici del pacco.

Proprietà	Tipo	Descrizione
packageWeight	number	Peso del pacco espresso in grammi (es. 18500 = 18.5kg).
packageVolume	number	Volume del pacco (cm³).
deliveryMethods	string[]	Metodi di consegna supportati (es. shipping, pickup).
shippingZones	ShippingZone[]	Zone geografiche e relative maggiorazioni/tasse specifiche.
shippingMethods	ShippingMethod[]	Elenco dei corrieri disponibili con relativi costi e tempi di consegna (ETA).
taxZones	TaxZone[]	Elenco delle aliquote IVA applicabili in base al paese di destinazione.

Esempio di oggetto

{
    "skuId": "43add257-6334-4f25-b0bd-4db878dd9308",
    "priceId": "a4884383-52cc-419a-a605-69fe067f555f",
    "quantity": 1,
    "originalPrice": 100,
    "comparePrice": 0,
    "netAmount": 100,
    "totalAmount": 100,
    "currencyCode": "EUR",
    "defaultTaxRate": 0,
    "cadence": "once",
    "shippingZones": [
        {
            "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
            "zoneId": "0f27b303-4fa6-4469-948d-61a4f7103a66",
            "label": "Zona Italia",
            "countryCode": "IT",
            "surchargePricing": {},
            "taxRate": 22
        },
        {
            "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
            "zoneId": "c19ccb31-5556-4e4f-bc9a-51ff293bc262",
            "label": "Zona Francia",
            "countryCode": "FR",
            "surchargePricing": {
                "eur": {
                    "base": 0,
                    "percentage": 0
                }
            },
            "taxRate": 20
        }
    ],
    "shippingMethods": [
        {
            "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
            "methodId": "30ba1461-8f03-4586-a850-d69416aeef38",
            "label": "Spedizione Standard Italia",
            "provider": "Poste Italiane",
            "pricing": {
                "eur": {
                    "base": 8,
                    "perKg": 0.5,
                    "toWeight": 100000,
                    "perVolume": 0,
                    "fromWeight": 10000,
                    "enableFreeShipping": true,
                    "freeShippingThreshold": 250
                }
            },
            "availableCountries": [
                "IT",
                "SM",
                "CH"
            ],
            "etaMin": 3,
            "etaMax": 7,
            "enabled": true,
            "maxWeight": 100000,
            "maxVolume": 5000000
        },
        {
            "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
            "methodId": "e16fe755-8fce-4c9d-a157-f7e67a6dae9b",
            "label": "Spedizione Italiana economica",
            "provider": "Provider",
            "pricing": {
                "eur": {
                    "base": 10,
                    "perKg": 0,
                    "perVolume": 0
                }
            },
            "availableCountries": [
                "IT"
            ],
            "etaMin": 1,
            "etaMax": 3,
            "enabled": true,
            "maxWeight": 0,
            "maxVolume": 0
        },
        {
            "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
            "methodId": "1758fedd-111f-4b02-973c-5563a5e6a9f1",
            "label": "Spedizione Standard Francia",
            "provider": "France post",
            "pricing": {
                "eur": {
                    "base": 14,
                    "perKg": 0.85,
                    "toVolume": 0,
                    "toWeight": 100000,
                    "perVolume": 0,
                    "fromVolume": 0,
                    "fromWeight": 4000
                }
            },
            "availableCountries": [
                "FR"
            ],
            "etaMin": 3,
            "etaMax": 14,
            "enabled": true,
            "maxWeight": 0,
            "maxVolume": 0
        }
    ],
    "taxZones": [
        {
            "id": "84f26098-4823-4f3c-82d0-44733e4d9d5d",
            "countryCode": "IT",
            "rate": 22,
            "isDefault": true
        },
        {
            "id": "ebdbe0cb-93c7-4f47-8a51-513828f92b88",
            "countryCode": "FR",
            "rate": 20,
            "isDefault": false
        }
    ],
    "available": 9,
    "isAvailable": true,
    "variantId": "0f669b79-af65-4433-96e3-5eca8e1b8852",
    "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
    "variantSlug": "sbarra-multigrip-a-muro",
    "deliveryMethods": [
        "shipping",
        "pickup"
    ],
    "packageWeight": 18500,
    "packageLength": 100,
    "packageWidth": 30,
    "packageHeight": 30,
    "packageVolume": 90000,
    "allowBackorder": false,
    "purchaseRestock": true,
    "allowFreeShipping": true,
    "forceFreeShipping": false,
    "options": [],
    "variantName": "Sbarra multigrip a muro",
    "coverUrl": "https://webrounddev.b-cdn.net/rMa8bmEA2Yg9aYk5PgZPejecmIB2/a7734977-c5b1-49a4-911c-0b0bf745bd4f/commerce/images/1755068526900-9048_2-multigrip-bar-indoor-micacea-1536x1536.jpg",
    "id": "3afdc08d-e1e4-4a6d-b683-0c506d984deb"
}

Calcolo Dinamico

Grazie alla presenza di shippingMethods e taxZones all'interno di ogni CartItem, l'SDK calcola in tempo reale il totale del carrello e le spese di spedizione non appena l'utente cambia l'indirizzo di destinazione, senza necessità di ricaricare l'intera pagina.