# Casi d'uso delle API di commerce: sette realizzazioni impossibili con un widget

> Quando un widget di vetrina non è la forma giusta: commerce incorporato nei SaaS, cataloghi su più superfici, negozi white-label, UX personalizzata, agenti AI, BI su misura. Più esempi di codice dall'SDK JS di Shoprocket.

Ryan Badger - 4 agosto 2025 - 5 min di lettura

## A cosa serve un'API ecommerce per l'incorporamento

La maggior parte delle piattaforme ecommerce ti dà un widget. Incolli uno script, ottieni una vetrina. Funziona benissimo per il 95% dei negozi.

Un'API di commerce è ciò a cui ricorri quando vuoi fare qualcosa che un widget non fa: mostrare i prodotti dentro la tua interfaccia, incorporare il checkout in una dashboard SaaS, distribuire un catalogo su più superfici (web + mobile + voce), o costruire percorsi d'acquisto personalizzati che nessuna piattaforma offre di serie.

Shoprocket offre entrambi. Il [widget](https://v3.shoprocket.io/it/blog/headless-commerce-tre-livelli-opzioni-reali-quale-scegliere.md) è il default. L'[SDK `@shoprocket/core`](https://github.com/shoprocket/shoprocket-js) serve quando il widget ti sta stretto o non ti è mai servito.

## Casi d'uso che richiedono un'API, non un widget

Queste sono le realizzazioni in cui un widget non basta. Se la tua idea è in questa lista, sei in territorio API.

### 1. Commerce dentro il tuo prodotto SaaS

La dashboard del tuo SaaS ha già una sua interfaccia. Vuoi che i clienti acquistino componenti aggiuntivi, pacchetti di crediti, livelli premium o merchandising fisico senza lasciare la tua app.

Un widget sarebbe la forma sbagliata: non conosce i tuoi utenti, non si adatta al tuo design system e presuppone una vetrina a pagina intera. L'API ti permette di mostrare le schede prodotto con i tuoi componenti, chiamare `cart.addItem()` al clic di un pulsante e far comparire il tuo pannello di checkout (oppure reindirizzare a un checkout ospitato se vuoi rimandare il lavoro di conformità).

```
import { ShoprocketCore } from '@shoprocket/core'

const sr = new ShoprocketCore({ publicKey: 'pk_...' })

// Mostra le schede dei componenti aggiuntivi nella dashboard del tuo SaaS
const addons = await sr.products.list({ category: 'addons' })

// L'utente clicca il pulsante // User clicks "Add credits" buttonquot;Aggiungi crediti// User clicks "Add credits" buttonquot;
await sr.cart.addItem(addon.id, 1)
```

### 2. Catalogo su più superfici (web + app nativa + voce + chat)

Un solo catalogo di prodotti, mostrato in modo diverso in ogni posto. La vetrina web mostra il dettaglio completo, l'app iOS nativa una lista compatta, l'assistente vocale descrive gli articoli a voce, un'integrazione di chat risponde con un link acquistabile.

Tutte e quattro le superfici chiamano la stessa API. Quando aggiorni il prezzo di un prodotto nella dashboard di Shoprocket, ogni superficie lo riflette alla lettura successiva. Nessuna sincronizzazione dei contenuti per superficie.

### 3. Vetrine white-label / dei partner

Sei una piattaforma dove altre persone vendono i loro prodotti: un marketplace di community, una directory di partner, una rete in franchising con siti individuali per i rivenditori. Ogni partner ha un brand che è suo, non tuo.

Il sito di ogni partner usa il tuo framework ma chiama l'API di commerce con la sua `publicKey`. I suoi prodotti, i suoi ordini, i suoi pagamenti, tutto separato per account. Nessun widget si mette in mezzo al loro brand.

### 4. UX d'acquisto completamente personalizzata

Configuratori di prodotto interattivi (PC assemblati su misura, gioielli personalizzati, mobili su ordinazione). Visualizzatori di prodotto 3D. Gallerie fotografiche "compra la stanza" in cui cliccare su pixel di un'immagine aggiunge il prodotto al carrello. Pulsanti di riordino rapido dentro l'email.

Il widget non può fare nulla di tutto questo. L'API sì. Mostri l'interfaccia che il tuo designer ha immaginato; l'API gestisce la meccanica del commerce dietro le quinte.

### 5. Agenti AI e commercio agentico

Un agente AI (ChatGPT, Claude, un agente personalizzato) che può sfogliare i prodotti e completare gli acquisti per conto dell'utente. L'agente ha bisogno di accesso programmatico al tuo catalogo e al carrello, non di un widget DOM da analizzare.

Shoprocket offre feed per i protocolli di commercio AI oltre al normale accesso API. A un agente a cui chiedi "cosa c'è disponibile sotto i 50 $ con spedizione gratuita" arriva una risposta strutturata, non uno screen scraping.

### 6. Commerce incorporato negli strumenti di contenuto

Una pagina Notion in cui i blocchi possono essere acquistabili. Un design Framer con hotspot a clic per acquistare. Uno strumento di newsletter in cui gli iscritti toccano una scheda prodotto e pagano senza lasciare l'email. Tutto costruito sopra un'API.

### 7. Report su misura e dashboard di BI

La dashboard di Shoprocket mostra ricavi, conversione, prodotti principali. Quello che non mostra sono *le tue* metriche personalizzate: valore nel tempo per coorte di clienti, ordini per fonte di segnalazione, margine dopo il costo del fornitore. L'API espone i dati di ordini e clienti, così puoi convogliarli nel tuo strumento di BI, in un foglio di calcolo o in una dashboard interna.

## Cosa ti dà oggi l'SDK

Da `@shoprocket/core`:

```
// Products
sr.products.list({ limit, offset, sort, category })
sr.products.get(productId)

// Cart
sr.cart.get()
sr.cart.addItem(productId, quantity)
sr.cart.updateItem(itemId, quantity)
sr.cart.removeItem(itemId)

// Session
sr.session.create()
sr.setSessionToken(token)
```

Più l'intera API REST per tutto ciò che l'SDK non copre ancora (ordini, clienti, sconti, scrittura dei prodotti). Vedi [api.shoprocket.io/docs](https://api.shoprocket.io/docs) per il riferimento completo.

## Dove l'approccio API-first è un errore

Alcuni casi in cui il widget è la scelta giusta e l'API è eccessiva:

- **Una vetrina semplice con 10-200 prodotti.** Il widget la gestisce alla perfezione; scrivere la tua interfaccia del catalogo significa rifare un lavoro già risolto.
- **Non hai capacità di ingegneria frontend dedicata.** L'approccio API-first richiede di realizzare e mantenere i tuoi stati di caricamento, l'interfaccia delle varianti, la gestione degli errori, l'accessibilità, l'i18n in 21 lingue. Sono settimane di lavoro che il widget ti dà gratis.
- **La tua priorità è la velocità di lancio.** Il widget richiede minuti; l'API-first settimane come minimo.

Parti dal widget. Passa all'API quando incontri qualcosa che il widget non sa fare.

## Un primo progetto realistico

Il progetto "mi serve l'API" più comune: un prodotto SaaS che vuole vendere crediti, abbonamenti o componenti aggiuntivi una tantum dentro la propria dashboard.

Approccio:

1. Installa `@shoprocket/core` nel tuo frontend
2. Crea in Shoprocket una categoria chiamata "Componenti aggiuntivi" o simile
3. Aggiungi i prodotti con il prezzo e la descrizione esatti che vuoi
4. Mostra l'elenco dei prodotti nella tua dashboard usando la tua libreria di componenti
5. Al clic, aggiungi al carrello + reindirizza al checkout ospitato di Shoprocket (oppure incorpora il checkout inline se te la senti di fare il lavoro in più)
6. Configura un endpoint webhook per ricevere gli eventi `order.paid`, così puoi attivare ciò che l'acquisto sblocca (crediti, accesso, spedizione)

Fine. Una manciata di file, un giorno di lavoro per chi è abituato a chiamare API. Nessun widget, nessun iframe, nessun compromesso sull'interfaccia del tuo prodotto.

## Cosa non consigliamo

Non ricostruire un'intera interfaccia di catalogo che somigli molto a ciò che il widget già fa. Se passi settimane su "griglia di prodotti con filtri e ricerca", stai scrivendo ciò che il widget offre in pochi minuti. Usa il widget per quella forma, usa l'API per le forme davvero diverse.

> **Consiglio:** se stai pensando di passare all'API-first perché lo stile predefinito del widget non si adatta al tuo brand, prova prima gli [hook di stile del widget](https://github.com/shoprocket/shoprocket-js). Il widget accetta molta più personalizzazione CSS di quanto sembri. Ricostruire tutto con l'API è uno sforzo molto più pesante.

## In sintesi

- **Widget** = default, copre il 95% dei negozi
- **API / SDK** = quando il widget non è la forma giusta (commerce incorporato nei SaaS, multi-superficie, white-label, UX personalizzata, agenti AI, BI su misura)
- **Superficie dell'SDK oggi:** prodotti, carrello, sessioni; più l'intera API REST per ordini / clienti / sconti
- **Schema del primo progetto:** dashboard SaaS che vende crediti o componenti aggiuntivi tramite SDK + attivazione guidata dai webhook
- **Non ricostruire con l'API** ciò che il widget già fa bene; scegli la tua forma

[Inizia una prova gratuita](https://app-v3.shoprocket.io/signup) e prendi una chiave pubblica; l'SDK è gratuito su qualsiasi piano Shoprocket. 14 giorni, senza carta.

---

- HTML version: https://v3.shoprocket.io/it/blog/api-commerce-sette-casi-duso-che-un-widget-non-copre
- Language: Italiano (it)
- Also in: [العربية](https://v3.shoprocket.io/ar/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Deutsch](https://v3.shoprocket.io/de/blog/commerce-api-anwendungsfaelle-sieben-builds-ohne-widget.md), [Ελληνικά](https://v3.shoprocket.io/el/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [English](https://v3.shoprocket.io/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Español](https://v3.shoprocket.io/es/blog/casos-de-uso-api-de-comercio-siete-proyectos-que-un-widget-no-puede-hacer.md), [Français](https://v3.shoprocket.io/fr/blog/api-commerce-sept-cas-usage-impossibles-avec-un-widget.md), [עברית](https://v3.shoprocket.io/he/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [हिन्दी](https://v3.shoprocket.io/hi/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Bahasa Indonesia](https://v3.shoprocket.io/id/blog/kasus-penggunaan-commerce-api-tujuh-hal-yang-tidak-bisa-dilakukan-widget.md), [日本語](https://v3.shoprocket.io/ja/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Lietuvių](https://v3.shoprocket.io/lt/tinklarastis/prekybos-api-panaudojimo-atvejai-septyni-sprendimai-kuriu-nepadarysite-su-valdykle.md), [Norsk](https://v3.shoprocket.io/nb/blogg/handels-api-sju-ting-du-ikke-kan-bygge-med-en-widget.md), [Nederlands](https://v3.shoprocket.io/nl/blog/commerce-api-use-cases-zeven-projecten-zonder-widget.md), [Polski](https://v3.shoprocket.io/pl/blog/api-do-e-commerce-siedem-zastosowan-ktorych-nie-zrobisz-widzetem.md), [Português](https://v3.shoprocket.io/pt/blog/casos-de-uso-api-de-commerce-sete-projetos-que-widget-nao-faz.md), [Română](https://v3.shoprocket.io/ro/blog/cazuri-de-utilizare-api-comert-sapte-proiecte-fara-widget.md), [Русский](https://v3.shoprocket.io/ru/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [ไทย](https://v3.shoprocket.io/th/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Türkçe](https://v3.shoprocket.io/tr/blog/commerce-api-kullanim-senaryolari-widget-ile-yapilamayan-yedi-proje.md), [中文](https://v3.shoprocket.io/zh/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md)