Tích Hợp Thương Mại Vào Ứng Dụng

Sử dụng Proyecta SDK để tạo khách hàng, bắt đầu thanh toán, kiểm soát tính năng và hủy đăng ký từ code ứng dụng của bạn.

Sau khi đã kết nối Stripe và tạo sản phẩm, bạn tích hợp thương mại vào ứng dụng thông qua SDK resource proyecta.commerce. Bốn thao tác phổ biến nhất là: tạo khách hàng, bắt đầu thanh toán, kiểm tra quyền truy cập tính năng và hủy đăng ký.

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

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

1. Tạo khách hàng

Khách hàng là đơn vị chịu phí trong ứng dụng của bạn — thường là một người dùng, tổ chức hoặc dự án. Hãy tạo khách hàng ngay khi đối tượng tương ứng được tạo trong cơ sở dữ liệu, sau đó lưu lại id được trả về để tham chiếu đến khách hàng trong các lần thanh toán và kiểm tra quyền truy cập.

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

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

Bạn cũng có thể truyền địa chỉ thanh toán (line1, line2, city, state, postal_code, country) khi tạo hoặc thông qua customers.update().

2. Bắt đầu thanh toán

commerce.checkout() tạo một phiên thanh toán do Stripe host và trả về URL để chuyển hướng khách hàng tới. Sau khi thanh toán, Stripe sẽ chuyển hướng khách hàng về success_url của bạn.

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

Hỗ trợ nhiều line_items. Đối với đăng ký, quantity đại diện cho số lượng chỗ ngồi (seat).

3. Kiểm tra quyền truy cập tính năng

Trước khi cho phép khách hàng sử dụng tính năng cao cấp, hãy gọi commerce.check() để xác minh họ có quyền truy cập:

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

Đây là cách được khuyến nghị để kiểm soát nội dung cao cấp. Xem Sản Phẩm & Tính Năng để tìm hiểu về mô hình tính năng/quyền sử dụng.

4. Hủy đăng ký

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

Theo mặc định, khách hàng vẫn giữ quyền truy cập cho đến khi kết thúc chu kỳ thanh toán hiện tại.

Để AI tự động tích hợp tất cả

Bạn không cần tự viết code cho những thao tác này. Một số prompt phổ biến:

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