دمج التجارة الإلكترونية في تطبيقي

استخدم Proyecta SDK لإنشاء العملاء، وبدء عمليات الدفع، وتقييد الميزات، وإلغاء الاشتراكات من كود تطبيقك.

بمجرد توصيل Stripe وإنشاء منتج، يمكنك دمج التجارة الإلكترونية في تطبيقك عبر مورد SDK المسمى proyecta.commerce. أكثر أربع عمليات شيوعاً هي: إنشاء عميل، وبدء عملية دفع، والتحقق من صلاحية الوصول إلى ميزة، وإلغاء اشتراك.

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

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

1. إنشاء عميل

العميل هو الكيان القابل للفوترة في تطبيقك — عادةً مستخدم أو مؤسسة أو مشروع. أنشئه فور إنشاء الكيان المقابل في قاعدة بياناتك، ثم احفظ id المُعاد لتتمكن من الإشارة إلى العميل في عمليات الدفع وفحوصات الوصول.

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

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

يمكنك أيضاً تمرير عنوان الفوترة (line1, line2, city, state, postal_code, country) عند الإنشاء أو عبر customers.update().

2. بدء عملية دفع

تُنشئ commerce.checkout() جلسة دفع مُستضافة على Stripe وتُعيد رابطاً لتوجيه العميل إليه. بعد إتمام الدفع، يُعيد Stripe توجيه العميل إلى 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);

يُدعم تمرير عدة line_items. بالنسبة للاشتراكات، يمثّل quantity عدد المقاعد.

3. التحقق من صلاحية الوصول إلى ميزة

قبل السماح للعميل باستخدام ميزة مدفوعة، استدعِ commerce.check() للتحقق من صلاحية وصوله:

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

هذه هي الطريقة الموصى بها لتقييد المحتوى المدفوع. راجع المنتجات والميزات للاطلاع على نموذج الميزات والصلاحيات.

4. إلغاء اشتراك

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

بشكل افتراضي، يحتفظ العميل بصلاحية الوصول حتى نهاية فترة الفوترة الحالية.

دع الذكاء الاصطناعي يتولى كل شيء

لا تحتاج إلى كتابة هذا الكود يدوياً. إليك بعض الأوامر الشائعة:

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