01 - Headless Commerce: Cos'è, Vantaggi, Svantaggi e Quando Ha Realmente Senso Adottarlo

Che cosa significa headless, in una frase e in un esempio

Headless commerce vuol dire che il sistema che gestisce prodotti, prezzi, carrelli, ordini e pagamenti non produce pagine web: espone dati e operazioni tramite API, e qualunque programma (un sito, un'app, un totem in negozio) le chiama per costruire la propria interfaccia. La «testa» (l'interfaccia) viene tagliata dal «corpo» (la logica commerciale), da qui il nome. Se hai già usato un tema WooCommerce o Shopify classico, hai visto l'opposto: lo stesso sistema decide il prezzo e disegna il bottone.

Un esempio quotidiano rende l'idea. Una torrefazione artigianale vende caffè sul proprio sito e vuole aprire anche un'app per gli abbonati e uno schermo nel locale che mostra la disponibilità delle miscele. Con un negozio classico dovrebbe mantenere tre copie del catalogo, o forzare l'app dentro una pagina web. Con un backend headless il catalogo resta uno solo e le tre interfacce lo leggono con la stessa richiesta. Il guadagno è la libertà di disegnare ciascun canale; il costo, come vedrai, è che le tre interfacce ora le costruisci tu.

In pratica una architettura headless ha tre parti: il backend commerce, che possiede i dati e le regole (cosa costa un prodotto, se è disponibile, come si calcola una spedizione); uno o più frontend, che non contengono regole di business ma solo presentazione; ed eventualmente un gateway che fa da porta d'ingresso unica per autenticazione e limiti di richieste. La regola che tiene insieme il disegno è che il prezzo di un articolo lo decide una volta sola, nel backend, e nessun frontend lo ricalcola per conto suo.

Come appare una chiamata reale: la Storefront API di Shopify

Per rendere concreto il discorso usiamo la Storefront API di Shopify, che è GraphQL: un solo indirizzo, e nella richiesta descrivi esattamente i campi che ti servono. Il listato qui sotto legge il catalogo a pagine da due prodotti. La query chiede per ciascun prodotto identificativo, titolo, handle (la parte dell'URL) e il prezzo minimo tra le varianti, più pageInfo, che dice se esiste una pagina successiva e da quale cursore ripartire. Il ciclo fetchAll continua finché hasNextPage è falso: è il modo standard di scorrere una collezione GraphQL, perché un catalogo reale si legge a pagine, non in una sola risposta.

export const PRODUCTS_QUERY = `
  query Products($first: Int!, $after: String) {
    products(first: $first, after: $after) {
      pageInfo { hasNextPage endCursor }
      nodes {
        id
        title
        handle
        priceRange { minVariantPrice { amount currencyCode } }
      }
    }
  }
`;

export type Product = {
  id: string;
  title: string;
  handle: string;
  priceRange: { minVariantPrice: { amount: string; currencyCode: string } };
};

type Page = { pageInfo: { hasNextPage: boolean; endCursor: string | null }; nodes: Product[] };

export async function fetchPage(endpoint: string, token: string, after?: string): Promise<Page> {
  const res = await fetch(endpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      // token PRIVATO: questo codice gira sul server, mai nel browser
      'Shopify-Storefront-Private-Token': token,
    },
    body: JSON.stringify({ query: PRODUCTS_QUERY, variables: { first: 2, after } }),
  });
  if (!res.ok) throw new Error(`Storefront API: HTTP ${res.status}`);
  const body = await res.json();
  // GraphQL risponde 200 anche quando la query e' sbagliata: gli errori stanno nel corpo
  if (body.errors) throw new Error(body.errors.map((e: { message: string }) => e.message).join('; '));
  return body.data.products;
}

export async function fetchAll(endpoint: string, token: string): Promise<Product[]> {
  const all: Product[] = [];
  let after: string | undefined;
  for (;;) {
    const page = await fetchPage(endpoint, token, after);
    all.push(...page.nodes);
    if (!page.pageInfo.hasNextPage) return all;
    after = page.pageInfo.endCursor ?? undefined;
  }
}

// Output:
// richieste HTTP: 2
// moka-3 -> 24.0 EUR
// macinacaffe -> 39.0 EUR
// filtro-v60 -> 12.5 EUR
// token errato: Storefront API: HTTP 401

Due righe contano più delle altre. La prima è l'intestazione Shopify-Storefront-Private-Token: la documentazione distingue un token pubblico, pensato per browser e app dove è visibile ai clienti, da un token privato, da usare solo da un server. Questo codice gira sul server, quindi usa il privato; se lo spedissi al browser, chiunque aprisse gli strumenti di sviluppo potrebbe copiarlo. La seconda è il controllo su body.errors: un server GraphQL può rispondere con stato 200 anche quando la query ha un errore, e senza quel controllo il programma andrebbe avanti con data vuoto senza avvisare nessuno.

L'uscita mostrata sopra non viene da un negozio Shopify: è stata ottenuta eseguendo con Node 24 lo stesso file contro un piccolo server locale che imita la forma della risposta, con tre prodotti e pagine da due (le due richieste HTTP sono le due pagine). Non prova quindi nulla sul comportamento di Shopify, e il token non vale per un negozio vero: è un test del ciclo di paginazione e della gestione dell'errore 401. Le versioni dell'API sono datate e trimestrali: nell'indirizzo ho messo 2026-10, la più recente stabile consultata il 2026-11-12 nella pagina sul versionamento, che garantisce ogni versione stabile per almeno dodici mesi. Significa che prima o poi devi aggiornare il numero e rileggere le note di rilascio.

Che cosa guadagni davvero

I vantaggi sono quattro e vanno tenuti distinti, perché solo alcuni valgono per te.

• Libertà sul frontend: puoi scegliere React, Vue, Angular, Svelte o un'app nativa, e testare l'interfaccia come qualunque altro software.
• Un backend, più canali: sito, app, punto vendita e integrazioni B2B leggono lo stesso catalogo e scrivono sullo stesso sistema ordini.
• Scalabilità separata: pagine statiche su una CDN reggono il traffico indipendentemente dal backend, che lavora soprattutto sui carrelli e sui pagamenti.
• Prestazioni controllabili: decidi tu che cosa pre-generare, che cosa mettere in cache e quante immagini caricare.

Il primo e l'ultimo sono due facce della stessa cosa: controllo su ciò che il browser riceve. Conta solo se hai qualcuno che sa sfruttarlo, perché un frontend scritto male su un backend headless è più lento di un buon tema. Il secondo vale solo se i canali esistono davvero: tre canali ipotetici non giustificano il costo. Sulle prestazioni la soglia di riferimento è quella di web.dev: un buon Largest Contentful Paint è di 2,5 secondi o meno, misurato al 75° percentile dei caricamenti reali. Non esiste una percentuale di conversione garantita dal passaggio a headless: le cifre che girano nei report di settore sono di parte e qui non le riporto, perché nessuna fonte primaria le sostiene in modo generale. Misura prima il LCP del tuo negozio attuale: se è già sotto soglia, il guadagno sarà piccolo. Come si misura sul campo e come si porta sotto soglia lo trovi nell'articolo su Core Web Vitals e SEO.

Che cosa paghi: i costi che le guide omettono

Il costo principale è che tutto ciò che il tema classico faceva da solo ora lo scrivi tu: il carrello persistente, la pagina di checkout, le email transazionali, i dati strutturati per i motori di ricerca, la gestione dei cookie, l'anteprima dei contenuti (se la affidi a un CMS, vedi l'articolo sul content commerce). Non ho una cifra attendibile sul rapporto tra il costo di un progetto headless e quello di un tema, e preferisco non inventarla: il rapporto dipende da quanto personalizzi e da chi lavora. Posso però dirti dove si accumula la spesa.

• Più sistemi, più punti di guasto: frontend, backend commerce, eventuale CMS e servizi di ricerca vanno rilasciati e monitorati separatamente.
• Competenze: serve chi conosce bene il framework scelto e le sue regole di rendering, non solo chi sa configurare un tema.
• Funzioni integrate che spariscono: email di recupero carrello, programmi fedeltà e chat spesso stavano nei plugin del monolite e vanno reintegrati.
• Aggiornamenti di versione: l'API del backend cambia nel tempo (come visto, Shopify rilascia una versione ogni trimestre) e il frontend deve seguirla.

Se devi ricordarne uno solo, ricorda il terzo: è quello che si scopre tardi. Prima del progetto, fai l'elenco di tutte le funzioni che il negozio attuale svolge senza che nessuno se ne accorga e per ognuna scrivi chi la fornirà dopo. Il tempo per farlo è una frazione del tempo per scoprire a metà lavoro che il recupero dei carrelli abbandonati non c'è più.

Come decidere: tre domande invece di soglie numeriche

Molte guide danno soglie del tipo «almeno tre sviluppatori» o «fatturato sopra un milione». Sono giudizi di chi scrive, non risultati di una ricerca, e cambiano da un settore all'altro. Preferisco tre domande a cui puoi rispondere tu, con i dati del tuo negozio.

Tre «sì» indicano che l'investimento ha una ragione; due «no» su tre, che sei in fase di ricerca del prodotto e ti conviene un negozio gestito dove cambiare il prezzo costa un clic. La strada intermedia è la più sottovalutata: puoi tenere il tema per il sito e usare le API solo per un canale nuovo, come l'app, oppure sostituire il frontend e lasciare il backend com'è. Si migra per gradi, e lo schema di migrazione graduale è il Strangler Fig descritto da Martin Fowler, che riprenderemo nell'articolo sull'architettura MACH.

Le piattaforme che incontrerai nella serie

Le piattaforme si dividono in due famiglie, e la differenza che conta per te è chi gestisce i server. Nei servizi gestiti (SaaS) paghi un canone e il fornitore mantiene l'infrastruttura: Shopify, con la Storefront API vista sopra, e commercetools, pensato per le grandi imprese. Nelle piattaforme open source installi e operi tu il software: Medusa (Node.js e TypeScript, modulare) e Saleor (Python e Django, GraphQL come interfaccia principale). Nel mezzo c'è WooCommerce, che ha una API REST ma nasce come negozio con il tema incluso, quindi usarlo senza testa è possibile ma poco naturale. Troverai i dettagli nei capitoli dedicati: Shopify Hydrogen, Medusa e Saleor.

La scelta tra le due famiglie è un trade-off tra tempo e controllo: il servizio gestito ti toglie l'infrastruttura e ti lega al suo modello di prezzo e ai suoi limiti, l'open source ti dà il codice e ti consegna aggiornamenti, backup e sicurezza. Non esiste una scelta migliore in assoluto; esiste quella coerente con il team che hai.

Che cosa sai fare adesso

Sai spiegare che cosa significa separare interfaccia e backend commerce, leggere una chiamata GraphQL a un catalogo con paginazione per cursore, distinguere un token pubblico da uno privato e riconoscere i costi che la separazione porta con sé. Soprattutto hai tre domande per decidere con i dati del tuo negozio invece che con i report di settore. Nel prossimo articolo vedremo come queste idee si organizzano in un’architettura completa.

Fonti