Integrar Comércio ao Meu App

Use o SDK do Proyecta para criar clientes, iniciar checkouts, restringir funcionalidades e cancelar assinaturas a partir do código do seu app.

Depois de conectar o Stripe e criar um produto, você integra o comércio ao seu app por meio do recurso proyecta.commerce do SDK. As quatro operações mais comuns são: criar um cliente, iniciar um checkout, verificar acesso a funcionalidades e cancelar uma assinatura.

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

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

1. Criar um cliente

Um cliente é a entidade faturável no seu app — geralmente um usuário, organização ou projeto. Crie um assim que a entidade correspondente for criada no seu banco de dados e armazene o id retornado para referenciar o cliente em checkouts e verificações de acesso.

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

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

Você também pode informar um endereço de cobrança (line1, line2, city, state, postal_code, country) na criação ou via customers.update().

2. Iniciar um checkout

commerce.checkout() cria uma sessão de checkout hospedada pelo Stripe e retorna uma URL para redirecionar o cliente. Após o pagamento, o Stripe redireciona o cliente para o seu 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);

Múltiplos line_items são suportados. Para assinaturas, quantity representa a quantidade de assentos.

3. Verificar acesso a funcionalidades

Antes de permitir que um cliente use uma funcionalidade premium, chame commerce.check() para verificar se ele tem acesso:

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 });
}

Essa é a forma recomendada de restringir conteúdo premium. Consulte Produtos e Funcionalidades para entender o modelo de funcionalidades e permissões.

4. Cancelar uma assinatura

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

Por padrão, o cliente mantém o acesso até o fim do período de cobrança vigente.

Deixe a IA configurar tudo

Você não precisa escrever isso manualmente. Alguns prompts úteis:

• "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."