محصولات و ویژگی‌ها

تعریف کنید چه چیزی می‌فروشید. محصولات را با یک یا چند variant ایجاد کنید و ویژگی‌های قابل استفاده مجدد را برای کنترل دسترسی مبتنی بر استحقاق متصل کنید.

Proyecta Commerce از سه مفهوم استفاده می‌کند: products، variants و features.

• Product — چیزی که می‌فروشید (مثلاً «پلن Pro»، «تی‌شرت»، «مشاوره استراتژی»)
• Variant — یک سطح قیمت‌گذاری یا پیکربندی از یک محصول (مثلاً «Pro ماهانه ۲۹ دلار»، «Pro سالانه ۲۹۰ دلار»، «تی‌شرت – سایز بزرگ»)
• Feature — یک کلید استحقاق قابل استفاده مجدد که اپ شما در زمان اجرا بررسی می‌کند (مثلاً pro_features، unlimited_projects، api_access)

یک محصول می‌تواند چندین variant داشته باشد. همچنین یک یا چند resource به محصول متصل می‌شود — معمولاً features — که پس از اشتراک مشتری، دسترسی را فعال می‌کنند.

ایجاد یک محصول

در Dashboard > Commerce > Products، روی Create product کلیک کنید (یا از AI بخواهید: "Create a Pro plan at $29/month and a Business plan at $99/month."). هر محصول به موارد زیر نیاز دارد:

• یک display name (مثلاً «Pro»)
• حداقل یک variant

Variants

هر variant قیمت‌گذاری مخصوص به خود را دارد:

فیلد	توضیحات
name	برچسب نمایشی برای variant («Monthly»، «Annual»، «Large»)
currency	کد سه‌حرفی ISO — USD، EUR، GBP، JPY، BRL، MXN، INR… (SDK از ۱۳۰+ پشتیبانی می‌کند)
unit_amount	قیمت به کوچک‌ترین واحد پولی (سنت). 2900 = ۲۹.۰۰ دلار
recurring	اختیاری — { interval: 'week' | 'month' | 'year' }. برای قیمت‌های یک‌بار مصرف حذف کنید. صورت‌حساب روزانه در حال حاضر پشتیبانی نمی‌شود.
is_default	پذیرفته شده اما هنوز اجرا نشده — انتخاب variant پیش‌فرض در حال حاضر پیاده‌سازی نشده است.
media	تصاویر یا ویدیوها را از طریق CDN file ID متصل کنید (ببینید Files)

قیمت‌گذاری تغییرناپذیر است. پس از ایجاد یک variant، قیمت آن قابل تغییر نیست — در عوض یک variant جدید بسازید. این کار از تغییرات قیمتی تصادفی برای مشترکین موجود محافظت می‌کند.

Features (استحقاق‌ها)

Features اولیه‌ترین ابزار کنترل دسترسی هستند. یک feature را یک بار بسازید و سپس آن را به یک یا چند محصول متصل کنید.

// Create a feature
const pro = await proyecta.commerce.features.create({
    name: 'Pro features',
    description: 'Unlocks the Pro tier capabilities',
    // optional custom id — lowercase alphanumeric and underscores only (e.g. 'pro_features')
});

هنگام ایجاد یک محصول، features را از طریق «resources» به آن متصل می‌کنید. مشتریانی که به یک محصول اشتراک می‌دهند، به تمام features متصل شده به آن دسترسی پیدا می‌کنند.

سپس در اپ خود بررسی کنید که آیا مشتری دسترسی دارد یا نه:

const { has_access } = await proyecta.commerce.check({
    customer_id: 'cus_123',
    resource_id: 'pro_features',
});

توجه: مقدار resource_id باید key ویژگی باشد — یعنی slug مشتق‌شده از نام feature (مثلاً pro_features)، نه ویژگی .id شیئی که توسط features.create() بازگردانده می‌شود.

این روشی است که با آن صفحات، endpoint های API، یا قابلیت‌های اختصاصی Pro را در کد اپ خود محدود می‌کنید.

شکل‌های رایج محصول

اشتراک‌های SaaS

Create products: Free ($0/month), Pro ($29/month, $290/year), Business ($99/month, $990/year).
Attach a 'pro_features' feature to Pro and Business so I can gate access in my code.

کالاهای فیزیکی

Create a T-shirt product with three variants: Small, Medium, Large at $25 each.

کالاهای دیجیتال

Create a course product with a single one-time variant at $149.

کمک‌های مالی

Create a donation product with three variants: $25, $50, $100 — all one-time.

موجودی

Proyecta Commerce در حال حاضر موجودی محصولات فیزیکی را ردیابی نمی‌کند. اگر اقلام انبارشده می‌فروشید، تعداد موجودی را در پایگاه داده اپ خود مدیریت کنید و آن را در فرآیند checkout بررسی نمایید.

به‌زودی

• سفارشی‌سازی فیلدهای Checkout — جمع‌آوری اطلاعات اضافی از خریداران
• قیمت‌گذاری به دلخواه خریدار
• ردیابی موجودی داخلی برای محصولات فیزیکی