Intégrer le commerce dans mon application

Utilisez le SDK Proyecta pour créer des clients, démarrer des paiements, restreindre l’accès aux fonctionnalités et annuler des abonnements depuis le code de votre application.

Une fois Stripe connecté et un produit créé, vous intégrez le commerce dans votre application via la ressource SDK proyecta.commerce. Les quatre opérations les plus courantes sont : créer un client, démarrer un paiement, vérifier l’accès à une fonctionnalité et annuler un abonnement.

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

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

1. Créer un client

Un client est l’entité facturable dans votre application — généralement un utilisateur, une organisation ou un projet. Créez-en un dès que l’entité correspondante est créée dans votre base de données, puis stockez l’id retourné afin de pouvoir référencer le client lors des paiements et des vérifications d’accès.

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

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

Vous pouvez également transmettre une adresse de facturation (line1, line2, city, state, postal_code, country) à la création ou via customers.update().

2. Démarrer un paiement

commerce.checkout() crée une session de paiement hébergée par Stripe et retourne une URL vers laquelle rediriger le client. Après le paiement, Stripe redirige le client vers votre 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);

Plusieurs line_items sont pris en charge. Pour les abonnements, quantity représente le nombre de sièges.

3. Vérifier l’accès à une fonctionnalité

Avant d’autoriser un client à utiliser une fonctionnalité premium, appelez commerce.check() pour vérifier qu’il y a accès :

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

C’est la méthode recommandée pour restreindre l’accès au contenu premium. Consultez Produits & Fonctionnalités pour en savoir plus sur le modèle de fonctionnalités et de droits d’accès.

4. Annuler un abonnement

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

Par défaut, le client conserve son accès jusqu’à la fin de la période de facturation en cours.

Laissez l’IA tout connecter

Vous n’avez pas besoin d’écrire tout cela à la main. Quelques exemples de prompts courants :

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