Integrazione del carrello

Il widget trasforma una disposizione finita in righe carrello concrete e le consegna al tuo negozio. Il tuo negozio resta responsabile di prezzi, sconti, stock e checkout.

Payload del callback

Quando l'acquirente clicca su Aggiungi al carrello, il widget chiama onAddToCart con:

{
  lines: [
    { sku: 'TILE-600-300', qty: 5, unit: 'box' },
  ],
  layoutFingerprint: '…',
  layoutToken: '…',
}

lines sono gli articoli da aggiungere. Ogni riga è uno SKU di catalogo, una quantità numerica e un'unità. La risposta include sempre una riga di piastrelle — il totale di piastrelle da acquistare, espresso in cartoni.

I materiali di consumo sono opzionali

Colla, stucco e primer sono sempre calcolati e mostrati nel preventivo a schermo e nel Blueprint PDF. Se vengano sincronizzati anche al carrello è un'impostazione opzionale, abilitata per i commercianti che vendono quegli articoli. Quando è attiva, quelle righe si aggiungono accanto alla piastrella:

{
  lines: [
    { sku: 'TILE-600-300', qty: 5, unit: 'box' },
    { sku: 'ADHESIVE-25', qty: 12.5, unit: 'kg' },
    { sku: 'GROUT-2KG', qty: 3, unit: 'kg' },
    { sku: 'PRIMER-10L', qty: 1, unit: 'l' },
  ],
  layoutFingerprint: '…',
  layoutToken: '…',
}

Parlaci se vendi materiali di consumo e vuoi includerli — li abilitiamo per il tuo negozio durante la configurazione.

layoutFingerprint è un identificatore stabile della disposizione. layoutToken è un token firmato che puoi conservare per riaprire in seguito la disposizione esatta — ad esempio, per allegare il piano a un ordine.

Aggiunta al tuo carrello

Il tuo callback aggiunge le righe tramite l'API del tuo negozio:

onAddToCart(payload) {
  payload.lines.forEach((line) => {
    yourStore.addToCart({
      sku: line.sku,
      quantity: line.qty,
      unit: line.unit,
    });
  });
}

Per WooCommerce significa una chiamata cart/add-item per riga; per Shopify, una mutation del carrello; per un negozio personalizzato, il tuo servizio carrello. Il widget non chiama mai il tuo negozio direttamente — lo fai tu, con gli SKU e le quantità che ha risolto.

Il prezzo resta nel tuo negozio

Il widget non invia mai un prezzo. Può mostrare i prezzi di listino del tuo catalogo nel preventivo a titolo informativo, ma prezzo finale, tasse, promozioni e sconti fedeltà sono tutti applicati dal tuo checkout quando le righe vengono aggiunte. Così resta un solo motore di prezzi ed eviti qualsiasi scostamento tra widget e carrello.

Lo stock resta nel tuo negozio

Il widget aggiunge ciò che la disposizione richiede. Il tuo negozio valida lo stock di quegli SKU esattamente come per qualsiasi altro «aggiungi al carrello». Se uno SKU è basso o non disponibile, il tuo flusso esistente di riordino e notifica si applica invariato.

Endpoint di intento carrello

Per integrazioni headless o lato server esiste un endpoint di intento carrello che restituisce le stesse righe risolte. Il tuo server lo chiama con la disposizione e aggiunge il risultato al carrello di sessione:

curl -X POST "https://embed.scalarcut.com/v1/tiling/cart-intent" \
  -H "Authorization: Bearer $WIDGET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "catalog": "YOUR_CATALOG_SLUG",
    "sku": "TILE-600-300",
    "layoutFingerprint": "…",
    "quantities": { "boxes": 5 }
  }'

Risposta:

{
  "lines": [
    { "sku": "TILE-600-300", "qty": 5, "unit": "box" }
  ],
  "layoutFingerprint": "…",
  "layoutToken": "…"
}

Con i materiali di consumo abilitati per il tuo negozio, la richiesta può portare anche adhesiveKg, groutKg e primerL, e la risposta guadagna le righe corrispondenti.

Vedi il riferimento API per il contratto completo dell'endpoint.