Produtos & Funcionalidades

Defina o que você vende. Crie produtos com uma ou mais variantes e anexe funcionalidades reutilizáveis para controle de acesso baseado em permissões.

O Proyecta Commerce usa três conceitos: produtos, variantes e funcionalidades.

• Produto — o que você vende (ex.: “Plano Pro”, “Camiseta”, “Consultoria Estratégica”)
• Variante — uma faixa de preço ou configuração de um produto (ex.: “Pro Mensal R$29”, “Pro Anual R$290”, “Camiseta – GG”)
• Funcionalidade — uma chave de permissão reutilizável que seu app verifica em tempo de execução (ex.: pro_features, unlimited_projects, api_access)

Um produto pode ter múltiplas variantes. Um produto também possui um ou mais recursos vinculados — geralmente funcionalidades — que concedem acesso quando um cliente assina.

Criando um produto

Em Dashboard > Commerce > Products, clique em Create product (ou peça à IA: "Create a Pro plan at $29/month and a Business plan at $99/month."). Cada produto precisa de:

• Um nome de exibição (ex.: “Pro”)
• Pelo menos uma variante

Variantes

Cada variante tem seu próprio preço:

Campo	Observações
name	Rótulo de exibição da variante (“Monthly”, “Annual”, “Large”)
currency	Código ISO de três letras — USD, EUR, GBP, JPY, BRL, MXN, INR… (o SDK suporta mais de 130)
unit_amount	Preço na menor unidade monetária (centavos). 2900 = $29,00
recurring	Opcional — { interval: 'week' | 'month' | 'year' }. Omita para preços avulsos. Cobrança diária não é suportada no momento.
is_default	Aceito, mas ainda não aplicado — a seleção de variante padrão ainda não foi implementada.
media	Anexe imagens ou vídeos pelo ID do arquivo no CDN (veja Arquivos)

O preço é imutável. Depois que uma variante é criada, seu preço não pode ser alterado — crie uma nova variante em vez disso. Isso protege assinantes existentes de mudanças de preço acidentais.

Funcionalidades (permissões)

As funcionalidades são o mecanismo primitivo de controle de acesso. Crie uma funcionalidade uma vez e depois vincule-a a um ou mais produtos.

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

Ao criar um produto, você vincula funcionalidades a ele por meio de “resources”. Clientes que assinam um produto obtêm acesso a todas as funcionalidades vinculadas a ele.

Em seguida, no seu app, verifique se um cliente tem acesso:

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

Nota: O resource_id deve ser a chave da funcionalidade — o slug derivado do nome da funcionalidade (ex.: pro_features), e não a propriedade .id do objeto de funcionalidade retornado por features.create().

É assim que você restringe páginas exclusivas do Pro, endpoints de API ou funcionalidades no código do seu app.

Formatos comuns de produto

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

Produtos físicos

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

Produtos digitais

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

Doações

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

Estoque

O Proyecta Commerce não rastreia estoque de produtos físicos no momento. Se você vende itens com estoque limitado, gerencie as quantidades no banco de dados do seu app e verifique-as no fluxo de checkout.

Em breve

• Personalização de campos no checkout — colete informações adicionais dos compradores
• Preço “pague quanto quiser”
• Rastreamento de estoque integrado para produtos físicos