Le Vanià

Panoramica

Il negozio online di un laboratorio fiorentino di zoccoli di lusso fatti a mano, costruito come e-commerce completamente headless: uno storefront Next.js su misura sopra un back end WooCommerce, con pagamenti Stripe.

Stack

Next.js 16 (App Router), TypeScript, WooCommerce REST API (headless), CoCart, Stripe (Payment Element, Express Checkout, webhook), NextAuth, Twilio Verify, GSAP, Vercel, Cloudflare R2

Cosa ho realizzato

• Architettura headless: server component con isole client, WooCommerce raggiunto solo tramite la sua REST API, pagine prodotto in cache e rivalidate ogni cinque minuti, e una sessione carrello lato server tramite CoCart.
• Checkout Stripe senza l'SDK lato server: prima viene creato l'ordine WooCommerce, poi un PaymentIntent per il totale calcolato da WooCommerce, con una chiave di idempotenza. Carte, Apple Pay, Google Pay, Link, PayPal e Klarna passano da Stripe Elements ed Express Checkout, anche direttamente dalla pagina prodotto.
• Un webhook Stripe con una propria verifica della firma (HMAC-SHA256, confronto a tempo costante, una finestra anti-replay) che controlla importo e PaymentIntent rispetto all'ordine, ignora gli eventi duplicati e non riporta mai indietro un ordine pagato.
• Un proxy API che nega tutto per default davanti a WooCommerce: solo route in allowlist, un controllo di proprietà su ogni cliente e ordine, e corpi delle richieste ricostruiti dai soli campi ammessi, così nessuno può scrivere una password, un'email, un ruolo o i dati di un altro utente.
• Un configuratore per lo zoccolo modulare: base, due tomaie e taglia come un unico prodotto variabile WooCommerce, con la configurazione scelta condivisibile tramite URL.
• Account con email e password tramite WordPress più accesso con Google, storico ordini protetto da controlli di proprietà, checkout come ospite e la procedura di recesso online richiesta dalla normativa UE, registrata in modo idempotente.
• SEO per un negozio: JSON-LD Product con politiche di spedizione e reso, breadcrumb, una sitemap dinamica e redirect 301 dai vecchi URL WordPress.

Scelte chiave

• L'importo addebitato viene sempre dal totale dell'ordine WooCommerce, ricalcolato sul server. Un prezzo arrivato dal browser non è mai considerato affidabile, e un prezzo non valido genera un errore invece di diventare zero.
• Lo stato del pagamento lo decide il webhook. La conferma dal browser può solo completare un ordine ancora in attesa.
• Un incidente in produzione risolto dai log: il livello anti-bot dell'hosting bloccava le chiamate API (671 errori su 63 utenti). È diventato un tipo di errore a sé con backoff esponenziale e jitter, le richieste dei prodotti sono state raggruppate in una sola, e gli header dei visitatori non vengono più inoltrati.
• Il pagamento alla consegna era protetto da un codice SMS, verificato da un cookie firmato e monouso legato all'acquirente. È andato in produzione ed è stato poi disattivato.
• È nato su Vite ed è passato a Next.js, e da Cloudflare Pages a Vercel: 356 commit e circa 23.000 righe di TypeScript.