Metas, créditos e cashback

Metas, créditos e cashback

Os temas oficiais apresentam os aplicativos comerciais habilitados no painel existente, sem settings visuais no tema. Atualizar os arquivos oficiais não altera uma loja publicada: aplique por nova revisão e publicação explícita.

cart.benefits é fornecido no carrinho e checkout:

• freeShipping: null ou { threshold, remaining, reached, percent }. Valores monetários usam { amount, currency: 'BRL' }, em centavos. A meta seleciona uma modalidade manual grátis, nacional e sem adicionais, respeitando limites de compra e peso. Atingir o valor não seleciona frete: o comprador ainda calcula o CEP e escolhe a modalidade retornada. Desativar a barra não desativa a modalidade manual grátis cadastrada no painel.
• giftGoals: metas elegíveis com id, title, productId, name e os mesmos campos de progresso. O valor mínimo considera produtos antes dos descontos e sem frete. Brindes indisponíveis ou com variações não são anunciados.
• gifts: itens conquistados, com goalId, productId, name e quantity: 1. Cada meta atingida concede uma unidade, sujeita a revalidação e estoque. Não some o preço do produto ao total e não permita editar sua quantidade.
• cashback: null ou { rate, threshold, remaining, reached, percent, estimated }. O mínimo histórico é estrito: uma configuração de R$ 50 exige R$ 50,01. estimated é uma estimativa de créditos; não é desconto desta compra. Na criação, o valor considera o total após descontos e créditos, com frete, e exige conta autenticada. A liberação depende da aprovação do pedido.

O componente oficial recebe benefits explicitamente:

{% render 'purchase-benefits', benefits: cart.benefits %}

Sem benefícios, mantenha a região oculta. A recotação atualiza também metas e brindes mesmo quando o valor dos produtos não muda; o runtime remove anúncios revogados e reaplica os créditos escolhidos ao total atualizado.

O backend fornece checkout.wallet somente à conta autenticada, com enabled e balance, e checkout.creditsMaximum com o teto de uso nesta compra. Nunca calcule autorização de saldo a partir de e-mail, documento, ID do tema ou valores do navegador. O runtime envia o valor escolhido em creditsAmount (centavos), e o servidor revalida conta, saldo e mínimo sob transação. O crédito pode cobrir os produtos líquidos de cupom; não financia frete nem adicionais. Uma compra com total zero após uso de créditos é aprovada sem cobrança externa.

/conta/creditos, via storefront_url, usa buyer.view = creditos e buyer.wallet = { enabled, balance, entries }. O histórico mostra as últimas 100 movimentações; o saldo considera o histórico completo. Cada entrada contém id, orderId, amount, operation (credit/debit), status (pending/available/refused), expired, date e expiresAt. Comentários administrativos não são expostos. Prévia de conta/checkout usa somente saldo fictício; não consulta históricos reais nem resgata créditos. O carrinho de prévia continua vazio, sem anunciar metas comerciais reais.

confirmation.creditsUsed e confirmation.cashbackGenerated mostram valores persistidos. Os mesmos campos existem em buyer.order. Brindes aparecem nos itens do pedido com preço zero e nome fotografado no momento da compra. Valores de cashback são fotografados na criação pelo Node; o prazo de validade usa a configuração vigente na liberação, como no painel. Aprovações manuais no painel continuam seguindo o fluxo daquele sistema.

O histórico compartilhado preserva o cálculo legado de vencimento. Cancelamento, estorno, chargeback e ajustes manuais continuam no fluxo de revisão de pedidos e créditos do painel; recusar uma tentativa de pagamento não devolve saldo automaticamente, pois o pedido pode ser pago em outra tentativa. Os hooks para metas e créditos estão na referência do runtime.