앱에 커머스 통합하기

Proyecta SDK를 사용하여 앱 코드에서 고객 생성, 결제 시작, 기능 제한, 구독 취소를 구현하세요.

Stripe를 연결하고 상품을 생성했다면, proyecta.commerce SDK 리소스를 통해 앱에 커머스 기능을 연결할 수 있습니다. 가장 흔히 사용되는 네 가지 작업은 고객 생성, 결제 시작, 기능 접근 확인, 구독 취소입니다.

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

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

1. 고객 생성

**고객(customer)**은 앱에서 결제의 주체가 되는 엔티티로, 일반적으로 사용자, 조직, 또는 프로젝트를 의미합니다. 데이터베이스에 해당 엔티티가 생성되는 즉시 고객을 생성하고, 반환된 id를 저장해 결제 및 접근 확인 시 참조할 수 있도록 하세요.

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

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

생성 시 또는 customers.update()를 통해 청구 주소(line1, line2, city, state, postal_code, country)를 함께 전달할 수도 있습니다.

2. 결제 시작

commerce.checkout()은 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는 사용자 수(seat count)를 나타냅니다.

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

기본적으로 고객은 현재 결제 주기가 끝날 때까지 서비스에 계속 접근할 수 있습니다.

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