Integrare il Commerce nella Mia App

Usa il Proyecta SDK per creare clienti, avviare checkout, limitare funzionalità e annullare abbonamenti dal codice della tua app.

Una volta connesso Stripe e creato un prodotto, puoi integrare il commerce nella tua app tramite la risorsa SDK proyecta.commerce. Le quattro operazioni più comuni sono: creare un cliente, avviare un checkout, verificare l’accesso a una funzionalità e annullare un abbonamento.

import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

1. Creare un cliente

Un cliente è l’entità fatturabile nella tua app — di solito un utente, un’organizzazione o un progetto. Creane uno non appena l’entità corrispondente viene creata nel tuo database, quindi salva l’id restituito in modo da poter fare riferimento al cliente nei checkout e nelle verifiche di accesso.

const customer = await proyecta.commerce.customers.create({
    email: 'alice@example.com',
    name: 'Alice Liddell',
});

await db.users.update({ id: userId, proyectaCustomerId: customer.id });

Puoi anche passare un indirizzo di fatturazione (line1, line2, city, state, postal_code, country) in fase di creazione o tramite customers.update().

2. Avviare un checkout

commerce.checkout() crea una sessione di checkout ospitata da Stripe e restituisce un URL a cui reindirizzare il cliente. Dopo il pagamento, Stripe reindirizza il cliente al tuo success_url.

const { url } = await proyecta.commerce.checkout({
    customer_id: customer.id,
    line_items: [{ variant_id: 'var_pro_monthly', quantity: 1 }],
    success_url: 'https://myapp.com/welcome',
    cancel_url: 'https://myapp.com/pricing',
});

return Response.redirect(url);

Sono supportati più line_items. Per gli abbonamenti, quantity rappresenta il numero di posti.

3. Verificare l’accesso a una funzionalità

Prima di consentire a un cliente di utilizzare una funzionalità premium, chiama commerce.check() per verificare che abbia l’accesso:

const { has_access } = await proyecta.commerce.check({
    customer_id: customer.id,
    resource_id: 'feat_pro_features',
});

if (!has_access) {
    return Response.json({ error: 'Upgrade required' }, { status: 402 });
}

Questo è il metodo consigliato per limitare i contenuti premium. Consulta Prodotti e Funzionalità per il modello di funzionalità ed entitlement.

4. Annullare un abbonamento

await proyecta.commerce.cancel({
    customer_id: customer.id,
    subscription_id: 'sub_123',
    cancellation_timing: 'at_billing_period_end', // or 'immediate'
});

Per impostazione predefinita, il cliente mantiene l’accesso fino alla fine del periodo di fatturazione.

Lascia che l’AI faccia tutto il lavoro

Non è necessario scrivere questo codice a mano. Alcuni prompt utili:

• "Create a Proyecta customer when a user signs up. Store the proyecta_customer_id on the user record."
• "Build a /pricing page that shows my Proyecta products and starts a checkout when a button is clicked."
• "Gate the /admin route — only allow users whose Proyecta customer has access to feat_admin."
• "When a user clicks Cancel Subscription, call proyecta.commerce.cancel with at_billing_period_end."