> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usi comuni dell'API di Upcart

> Scopri come mettere all'opera la Public API di Upcart con esempi pratici da copiare e incollare.

<div id="how-the-api-pattern-works">
  ## Come funziona il pattern dell'API
</div>

La maggior parte degli script dell'API di Upcart segue lo stesso semplice pattern:

Ascolta un evento del carrello → Verifica una condizione → Esegui un'azione

Ad esempio: "Quando il carrello si carica → controlla se è vuoto → nascondi il pulsante sticky."

💡 **Nuovo alle API?** Inizia con [Cos'è un'API?](/it/upcart/what_is_an_api) prima di passare agli esempi qui sotto.

***

<div id="where-to-add-your-scripts">
  ## Dove aggiungere i tuoi script
</div>

Tutti gli script qui sotto vanno in:

**Cart Editor → Settings → Custom HTML → Scripts (before load)**

Racchiudi ogni snippet in tag `<script>...</script>` e salva. Per testare, apri la console degli Strumenti per sviluppatori del tuo browser (`F12`) e cerca eventuali messaggi `console.log`.

***

<div id="a-note-on-legacy-vs-modern-callbacks">
  ## Una nota sulle callback legacy e moderne
</div>

Upcart ha due modi per ascoltare gli eventi del carrello:

| Stile                 | Esempio                          | Stato                                          |
| --------------------- | -------------------------------- | ---------------------------------------------- |
| Moderno (consigliato) | `upcartSubscribeAddedToCart(fn)` | Attuale                                        |
| Legacy (deprecato)    | `upcartOnAddToCart = fn`         | Funziona ancora, registra un avviso in console |

Tutti gli esempi qui sotto usano l'API moderna. Gli script esistenti che usano il vecchio stile continueranno a funzionare.

***

<div id="example-1-hide-the-sticky-cart-button-when-the-cart-is-empty">
  ## Esempio 1: nascondere il pulsante sticky del carrello quando il carrello è vuoto
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeCartLoaded(function(event) {
    var stickyBtn = document.querySelector("#upCartStickyButton");
    if (stickyBtn) {
      var totalQty = event.cart.items.reduce(function(sum, item) {
        return sum + item.quantity;
      }, 0);
      stickyBtn.style.display = totalQty === 0 ? "none" : "block";
    }
  });
</script>
```

**Come funziona:** `upcartSubscribeCartLoaded` viene attivato ogni volta che il carrello viene caricato. La callback riceve un `event` con un oggetto `cart` che contiene un array `items`. Sommiamo la `quantity` di ogni articolo per determinare se il carrello è vuoto.

⚠️ **IMPORTANTE:** `event.cart` NON ha una proprietà `item_count`. Devi calcolare il totale iterando `event.cart.items`.

***

<div id="example-2-log-when-an-item-is-added-to-the-cart">
  ## Esempio 2: registrare quando un articolo viene aggiunto al carrello
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    console.log("Added to cart:", event.item.title, "| Qty:", event.item.quantityAdded);
  });
</script>
```

**Proprietà disponibili su `event.item`:**

| Proprietà                  | Descrizione                                         |
| -------------------------- | --------------------------------------------------- |
| `event.item.title`         | Titolo del prodotto                                 |
| `event.item.quantityAdded` | Numero di unità aggiunte in questa azione           |
| `event.item.quantity`      | Quantità totale di questo articolo ora nel carrello |
| `event.item.variantId`     | ID variante Shopify                                 |
| `event.item.handle`        | Handle del prodotto                                 |
| `event.item.productId`     | ID prodotto Shopify                                 |
| `event.item.finalPrice`    | Prezzo finale dopo gli sconti                       |
| `event.item.image`         | URL dell'immagine del prodotto                      |

***

<div id="example-3-integrate-with-a-third-party-analytics-app-eg-triplewhale">
  ## Esempio 3: integrazione con un'app di analytics di terze parti (ad es. TripleWhale)
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.TriplePixel('AddToCart', {
      item: event.item.variantId,
      q: event.item.quantityAdded
    });
  });
</script>
```

> **Nota:** ogni app di terze parti è diversa. Verifica con il team di supporto della tua app il formato corretto degli eventi.

***

<div id="example-4-open-the-cart-automatically-after-a-product-is-added">
  ## Esempio 4: aprire il carrello automaticamente dopo l'aggiunta di un prodotto
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>
```

> **Nota:** se "Open cart drawer on add to cart" è già abilitato in **Cart Editor → Settings → Cart settings**, non hai bisogno di questo script.

***

<div id="quick-reference-subscribe-functions-modern-api">
  ## Riferimento rapido: funzioni Subscribe (API moderna)
</div>

| Funzione                                               | Quando si attiva                             | La callback riceve                                                                                  |
| ------------------------------------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `upcartSubscribeCartLoaded(fn)`                        | I dati del carrello si caricano              | `{ cart }` - cart ha `.items[]`, `.total`, `.currency`                                              |
| `upcartSubscribeAddedToCart(fn)`                       | Articolo aggiunto al carrello                | `{ item }` - item ha `.title`, `.variantId`, `.quantityAdded`, `.quantity`                          |
| `upcartSubscribeCartOpened(fn)`                        | Il cart drawer si apre                       | `{}` (oggetto vuoto)                                                                                |
| `upcartSubscribeCartClosed(fn)`                        | Il cart drawer si chiude                     | `{}` (oggetto vuoto)                                                                                |
| `upcartSubscribeCartUpdated(fn)`                       | Il contenuto del carrello cambia             | `{ cart }`                                                                                          |
| `upcartSubscribeItemRemoved(fn)`                       | Articolo rimosso                             | `{ item }`                                                                                          |
| `upcartSubscribeCheckoutClicked(fn)`                   | Pulsante di checkout cliccato                | `{ event }` - MouseEvent del browser                                                                |
| `upcartSubscribeUpsellsAddedToCart(fn)`                | Articolo upsell aggiunto                     | `{ variant }` - ha `.id` e `.title`                                                                 |
| `upcartSubscribeUpsellsRendered(fn)`                   | Gli upsell vengono renderizzati nel carrello | `{ item, element }` - item è il prodotto, element è il nodo DOM                                     |
| `upcartSubscribeNotesTextChanged(fn)`                  | Note del carrello aggiornate                 | `{ newNotesText, oldNotesText }` - la nuova stringa delle note e quella precedente                  |
| `upcartSubscribeRewardsMilestonesCompletedChanged(fn)` | Lo stato di un traguardo premio cambia       | `{ numOfMilestonesCompleted, status }` - `status` è `"promotion"`, `"demotion"` o `"initial-state"` |

***

<div id="direct-action-functions">
  ## Funzioni di azione diretta
</div>

| Funzione                           | Cosa fa                                                          |
| ---------------------------------- | ---------------------------------------------------------------- |
| `window.upcartOpenCart()`          | Apre il cart drawer                                              |
| `window.upcartCloseCart()`         | Chiude il cart drawer                                            |
| `window.upcartRefreshCart()`       | Aggiorna i dati del carrello                                     |
| `window.upcartGetCart()`           | Restituisce l'oggetto carrello corrente                          |
| `window.upcartRegisterAddToCart()` | Registra l'add-to-cart per i page builder (Replo, PageFly, ecc.) |
| `window.upcartFormatMoney()`       | Formatta un prezzo usando il formato valuta del tuo negozio      |

Per la documentazione completa dell'API, consulta la [documentazione della Public API di Upcart](https://rokt.notion.site/upcart-public-api).

***

<div id="troubleshooting">
  ## Risoluzione dei problemi
</div>

* **Lo script non viene eseguito?** Ricontrolla il posizionamento: dovrebbe essere in *Scripts (before load)*, non after load.
* **Elemento non trovato?** Assicurati che il selettore (ad es. `#upCartStickyButton`) corrisponda all'ID effettivo dell'elemento nel tuo carrello.
* **Qualcosa si è rotto?** Commenta il tuo script aggiungendo `//` all'inizio di ogni riga, salva e aggiorna.
* **Sei ancora bloccato?** Consulta le [FAQ sull'API](/it/upcart/upcart_api_frequently_asked_questions) per ulteriori passaggi di risoluzione dei problemi.