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

O Proyecta Commerce utiliza 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 – G”)
• Funcionalidade — uma chave de direito reutilizável que seu app verifica em tempo de execução (ex.: pro_features, unlimited_projects, api_access)

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

Duas formas de modelar o que você vende

O Commerce se integra ao restante da plataforma, portanto existem dois formatos para “algo que você vende” — e o Proyecta escolhe o mais adequado para você:

• Produtos nativos do Commerce — assinaturas, planos, upgrades avulsos e funcionalidades/direitos. Definidos diretamente em Admin > Commerce > Products. Este é o modelo descrito no restante desta página.
• Catálogo de storefront baseado em conteúdo — produtos com fotos, preços e descrições que o dono do negócio edita no dia a dia. Esses itens ficam no CMS como uma coleção vendável: cada entrada é o produto. Quando uma entrada é publicada, o Proyecta automaticamente a integra ao Commerce como um produto real e comprável — criando o produto e sua variante com preço, e copiando o preço diretamente do campo de conteúdo. O storefront exibe o preço do conteúdo e o checkout cobra a variante vinculada; como compartilham uma única fonte, eles nunca podem divergir. Você gerencia esses itens como conteúdo (no Admin do seu app, no builder ou no seu site publicado), e não em Commerce > Products. Consulte Gerenciamento de Conteúdo.

Um catálogo simples que não aceita pagamentos com cartão — um cardápio apenas para consulta ou uma loja cujo botão “comprar” abre um link de pedido pelo WhatsApp — é apenas conteúdo comum — uma coleção de catálogo comum, sem integração com o Commerce. O checkout por cartão é o que torna uma coleção vendável.

Criando um produto

Em Admin > 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… (mais de 130 suportados)
unit_amount	Preço na menor unidade monetária (centavos). 2900 = R$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 não está implementada no momento.
media	Anexe imagens ou vídeos pelo ID do arquivo CDN (consulte Arquivos)

O preço é imutável. Depois que uma variante é criada, seu preço não pode ser alterado — crie uma nova variante. Isso protege os assinantes existentes de alterações acidentais de preço.

Funcionalidades (direitos)

As funcionalidades são o elemento primitivo de controle de acesso. Crie uma funcionalidade uma vez em Admin > Commerce > Products e, em seguida, vincule-a a um ou mais produtos. Cada funcionalidade tem um nome, uma descrição opcional e uma chave — letras minúsculas, números e underscores (ex.: pro_features) — que é o que seu app verifica.

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

Em seguida, no seu app, faça o controle de acesso com essa chave:

const { hasAccess, isLoading } = useEntitlement('pro_features');

if (isLoading) return <Spinner />;
if (!hasAccess) return <UpgradePrompt />;
return <ProOnlyThing />;

A verificação é executada no servidor contra a sessão autenticada, portanto não pode ser falsificada pelo navegador. Consulte Integrar o Commerce ao Meu App para ver o padrão completo.

Nota: Sempre controle o acesso pela chave da funcionalidade — o slug derivado do nome da funcionalidade (ex.: pro_features) — e não pelo id interno da funcionalidade.

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

Formatos de produto comuns

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 quantidade limitada, gerencie as contagens de estoque 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
• Precificação livre (pague quanto quiser)
• Rastreamento de estoque integrado para produtos físicos