Prodotti e Funzionalità

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

Proyecta Commerce utilizza tre concetti: prodotti, varianti e funzionalità.

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

Un prodotto può avere più varianti. Un prodotto ha anche una o più risorse associate — di solito funzionalità — che concedono l’accesso quando un cliente si abbona.

Creare un prodotto

In Dashboard > 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… (l’SDK supporta 130+)
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 è attualmente supportata.
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 Files)

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à (diritti)

Le funzionalità sono il meccanismo primitivo per il controllo degli accessi. Crea una funzionalità una volta, poi associala a uno o più prodotti.

// Create a feature
const pro = await proyecta.commerce.features.create({
    name: 'Pro features',
    description: 'Unlocks the Pro tier capabilities',
    // optional custom id — lowercase alphanumeric and underscores only (e.g. 'pro_features')
});

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

Poi, nella tua app, verifica se un cliente ha accesso:

const { has_access } = await proyecta.commerce.check({
    customer_id: 'cus_123',
    resource_id: 'pro_features',
});

Nota: Il resource_id deve essere la chiave della funzionalità — lo slug derivato dal nome della funzionalità (es. pro_features), non la proprietà .id dell’oggetto funzionalità restituito da features.create().

È così che puoi proteggere pagine riservate agli utenti Pro, endpoint API o funzionalità nel codice della tua app.

Configurazioni 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.

Prodotti fisici

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

Prodotti 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 non tiene attualmente traccia dell’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
• Gestione integrata dell’inventario per i prodotti fisici