یکپارچه‌سازی تجارت در اپلیکیشن

از Proyecta SDK برای ایجاد مشتری، شروع پرداخت، محدودسازی ویژگی‌ها و لغو اشتراک از کد اپلیکیشن خود استفاده کنید.

پس از اتصال Stripe و ایجاد یک محصول، تجارت را از طریق منبع proyecta.commerce در SDK به اپلیکیشنت وصل می‌کنی. چهار عملیات رایج عبارتند از: ایجاد مشتری، شروع پرداخت، بررسی دسترسی به ویژگی، و لغو اشتراک.

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

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

۱. ایجاد مشتری

مشتری موجودیت قابل‌صدور فاکتور در اپلیکیشن توست — معمولاً یک کاربر، سازمان یا پروژه. به محض ایجاد موجودیت متناظر در پایگاه داده‌ات، یک مشتری بساز و 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() ارسال کنی.

۲. شروع پرداخت

commerce.checkout() یک session پرداخت میزبانی‌شده توسط Stripe ایجاد می‌کند و یک URL برای هدایت مشتری بازمی‌گرداند. پس از پرداخت، 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 نمایانگر تعداد صندلی است.

۳. بررسی دسترسی به ویژگی

پیش از اینکه به مشتری اجازه دهی از یک ویژگی پریمیوم استفاده کند، 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 });
}

این روش توصیه‌شده برای محدودسازی محتوای پریمیوم است. برای مدل ویژگی/استحقاق، محصولات و ویژگی‌ها را ببین.

۴. لغو اشتراک

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

به‌طور پیش‌فرض، مشتری تا پایان دوره صدور فاکتور دسترسی خود را حفظ می‌کند.

بگذار AI همه چیز را وصل کند

نیازی نیست این کد را دستی بنویسی. دستورالعمل‌های رایج:

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