Sản Phẩm & Tính Năng

Xác định những gì bạn bán. Tạo sản phẩm với một hoặc nhiều biến thể, đính kèm các tính năng có thể tái sử dụng để kiểm soát quyền truy cập dựa trên quyền lợi.

Proyecta Commerce sử dụng ba khái niệm: sản phẩm, biến thể, và tính năng.

• Sản phẩm — thứ bạn bán (ví dụ: “Pro Plan”, “Áo thun”, “Tư vấn chiến lược”)
• Biến thể — một mức giá hoặc cấu hình của sản phẩm (ví dụ: “Pro Hàng tháng $29”, “Pro Hàng năm $290”, “Áo thun – Cỡ Lớn”)
• Tính năng — một khóa quyền lợi có thể tái sử dụng mà app của bạn kiểm tra lúc runtime (ví dụ: pro_features, unlimited_projects, api_access)

Một sản phẩm có thể có nhiều biến thể. Một sản phẩm cũng có một hoặc nhiều tài nguyên được đính kèm — thường là các tính năng — cấp quyền truy cập khi khách hàng đăng ký.

Tạo sản phẩm

Trong Dashboard > Commerce > Products, nhấn Create product (hoặc hỏi AI: "Create a Pro plan at $29/month and a Business plan at $99/month."). Mỗi sản phẩm cần có:

• Một tên hiển thị (ví dụ: “Pro”)
• Ít nhất một biến thể

Biến thể

Mỗi biến thể mang thông tin giá riêng:

Trường	Ghi chú
name	Nhãn hiển thị cho biến thể (“Monthly”, “Annual”, “Large”)
currency	Mã ISO ba chữ cái — USD, EUR, GBP, JPY, BRL, MXN, INR… (SDK hỗ trợ 130+ loại tiền tệ)
unit_amount	Giá theo đơn vị tiền tệ nhỏ nhất (cents). 2900 = $29.00
recurring	Tùy chọn — { interval: 'week' | 'month' | 'year' }. Bỏ qua nếu là giá thanh toán một lần. Thanh toán hàng ngày hiện chưa được hỗ trợ.
is_default	Được chấp nhận nhưng chưa được áp dụng — tính năng chọn biến thể mặc định hiện chưa được triển khai.
media	Đính kèm hình ảnh hoặc video bằng CDN file ID (xem Tệp)

Giá không thể thay đổi. Một khi biến thể đã được tạo, giá của nó không thể chỉnh sửa — hãy tạo một biến thể mới thay thế. Điều này bảo vệ những người đăng ký hiện tại khỏi việc bị thay đổi giá ngoài ý muốn.

Tính năng (quyền lợi)

Tính năng là yếu tố nguyên thủy để kiểm soát quyền truy cập. Tạo một tính năng một lần, sau đó đính kèm nó vào một hoặc nhiều sản phẩm.

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

Khi bạn tạo một sản phẩm, bạn đính kèm các tính năng vào nó thông qua “resources”. Khách hàng đăng ký một sản phẩm sẽ được cấp quyền truy cập vào mọi tính năng được đính kèm với sản phẩm đó.

Sau đó, trong app của bạn, kiểm tra xem khách hàng có quyền truy cập hay không:

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

Lưu ý: resource_id phải là khóa của tính năng — slug được tạo từ tên tính năng (ví dụ: pro_features), không phải thuộc tính .id của đối tượng tính năng được trả về bởi features.create().

Đây là cách bạn chặn các trang chỉ dành cho Pro, các endpoint API, hoặc các tính năng trong code của app.

Các dạng sản phẩm phổ biến

Đăng ký 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.

Hàng hóa vật lý

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

Hàng hóa kỹ thuật số

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

Quyên góp

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

Tồn kho

Proyecta Commerce hiện chưa theo dõi tồn kho cho các sản phẩm vật lý. Nếu bạn bán các mặt hàng có kho lưu trữ, hãy quản lý số lượng tồn kho trong cơ sở dữ liệu của app và kiểm tra chúng trong luồng thanh toán của bạn.

Sắp ra mắt

• Tùy chỉnh trường thanh toán — thu thập thêm thông tin từ người mua
• Định giá tùy ý theo ý muốn
• Theo dõi tồn kho tích hợp cho sản phẩm vật lý