Prodotti e Funzionalità

Definisci cosa vendi. Crea prodotti con una o più varianti, associa funzionalità riutilizzabili per il controllo degli accessi basato su entitlement.

Proyecta Commerce si basa su tre concetti: prodotti, varianti e funzionalità.

• Prodotto — ciò che vendi (es. “Piano Pro”, “T-shirt”, “Consulenza Strategica”)
• Variante — un livello di prezzo o una configurazione di un prodotto (es. “Pro Mensile $29”, “Pro Annuale $290”, “T-shirt – Taglia Large”)
• Funzionalità — una chiave di entitlement riutilizzabile che la tua app verifica a runtime (es. pro_features, unlimited_projects, api_access)

Un prodotto può avere più varianti. A un prodotto è inoltre associata una o più risorse — di solito funzionalità — che concedono l’accesso quando un cliente si abbona.

Due modi per modellare ciò che vendi

Commerce si integra con il resto della piattaforma, quindi esistono due forme per “una cosa che vendi” — e Proyecta sceglie quella giusta per te:

• Prodotti nativi di Commerce — abbonamenti, piani, upgrade una tantum e funzionalità/entitlement. Definiti direttamente in Admin > Commerce > Products. Questo è il modello descritto nel resto di questa pagina.
• Un catalogo storefront basato su contenuti — articoli con foto, prezzi e descrizioni che il titolare dell’attività modifica quotidianamente. Questi risiedono nel CMS come collezione vendibile: ogni voce è il prodotto. Quando una voce viene pubblicata, Proyecta la integra automaticamente in Commerce come prodotto reale e acquistabile — creando il prodotto e la sua variante con prezzo, e copiando il prezzo direttamente dal campo del contenuto. Lo storefront mostra il prezzo del contenuto e il checkout addebita la variante collegata; poiché condividono un’unica sorgente, non possono mai divergere. Questi elementi si gestiscono come contenuto (nell’Admin della tua app, nel builder o sul sito pubblicato), non in Commerce > Products. Vedi Gestione dei Contenuti.

Un semplice catalogo che non accetta pagamenti con carta — un menu di sola consultazione, o un negozio il cui pulsante “acquista” apre un link di ordine su WhatsApp — è semplicemente contenuto ordinario — una collezione catalogo ordinaria, senza integrazione con Commerce. È il checkout con carta a rendere una collezione vendibile.

Creare un prodotto

In Admin > Commerce > Products, clicca su Create product (oppure chiedi all’AI: "Create a Pro plan at $29/month and a Business plan at $99/month."). Ogni prodotto richiede:

• Un nome visualizzato (es. “Pro”)
• Almeno una variante

Varianti

Ogni variante ha il proprio prezzo:

Campo	Note
name	Etichetta visualizzata per la variante (“Monthly”, “Annual”, “Large”)
currency	Codice ISO a tre lettere — USD, EUR, GBP, JPY, BRL, MXN, INR… (130+ supportate)
unit_amount	Prezzo nell’unità monetaria più piccola (centesimi). 2900 = $29.00
recurring	Opzionale — { interval: 'week' | 'month' | 'year' }. Ometti per prezzi una tantum. La fatturazione giornaliera non è supportata al momento.
is_default	Accettato ma non ancora applicato — la selezione della variante predefinita non è attualmente implementata.
media	Associa immagini o video tramite ID file CDN (vedi File)

Il prezzo è immutabile. Una volta creata una variante, il suo prezzo non può essere modificato — crea invece una nuova variante. Questo protegge gli abbonati esistenti da modifiche accidentali al prezzo.

Funzionalità (entitlement)

Le funzionalità sono il primitivo di controllo degli accessi. Crea una funzionalità una sola volta in Admin > Commerce > Products, poi associala a uno o più prodotti. Ogni funzionalità ha un nome, una descrizione opzionale e una chiave — lettere minuscole, numeri e underscore (es. pro_features) — che è ciò che la tua app verifica.

Quando crei un prodotto, associi le funzionalità tramite “risorse”. I clienti che si abbonano a un prodotto ottengono accesso a tutte le funzionalità ad esso associate.

Poi, nella tua app, controlla la chiave:

const { hasAccess, isLoading } = useEntitlement('pro_features');

if (isLoading) return <Spinner />;
if (!hasAccess) return <UpgradePrompt />;
return <ProOnlyThing />;

Il controllo viene eseguito lato server rispetto alla sessione dell’utente autenticato, quindi non può essere falsificato dal browser. Vedi Integrare Commerce nella Mia App per il pattern completo.

Nota: Usa sempre la chiave della funzionalità per il controllo degli accessi — lo slug derivato dal nome della funzionalità (es. pro_features) — non l’id interno della funzionalità.

In questo modo puoi proteggere pagine riservate ai Pro, endpoint API o funzionalità nel codice della tua app.

Forme di prodotto comuni

Abbonamenti SaaS

Create products: Free ($0/month), Pro ($29/month, $290/year), Business ($99/month, $990/year).
Attach a 'pro_features' feature to Pro and Business so I can gate access in my code.

Beni fisici

Create a T-shirt product with three variants: Small, Medium, Large at $25 each.

Beni digitali

Create a course product with a single one-time variant at $149.

Donazioni

Create a donation product with three variants: $25, $50, $100 — all one-time.

Inventario

Proyecta Commerce al momento non traccia l’inventario per i prodotti fisici. Se vendi articoli in stock, gestisci le quantità disponibili nel database della tua app e verificale nel flusso di checkout.

Prossimamente

• Personalizzazione dei campi di checkout — raccogli informazioni aggiuntive dagli acquirenti
• Prezzi a scelta libera
• Tracciamento dell’inventario integrato per i prodotti fisici