Skip to content

Compra, carrinho, frete e pagamentos ​

Regras comuns ​

A composição aceita disabled booleano por instância no template JSON. Somente true omite o Liquid e suas consultas comerciais exclusivas no servidor; ausente ou false mantém a renderização. Nenhum hook de navegador ou regra CSS representa esse estado. IDs, ordem, tipo e fontes permanecem na revisão, e a validação de referências, segurança e limites também alcança instâncias ocultas. Marcadores e controles de organização pertencem apenas à prévia administrativa, sem wrappers obrigatórios no HTML público.

  • Hooks podem aparecer em estruturas visuais diferentes. Não são necessários nomes de classes do Aura, fontes, cores, presets ou settings.
  • data-* comercial vem do contexto Liquid do servidor. Escape valores dinâmicos. data-cart-endpoint, data-shipping-endpoint, data-checkout-endpoint e data-cart-url devem usar caminhos da mesma origem com storefront_url, preservando o namespace da prévia.
  • Use botões com type explícito, labels, inputs nativos e mensagens com role="status"/aria-live="polite". Botões fora de submissões devem ter type="button".
  • Mensagens são atribuídas como texto, nunca HTML. data-state nas mensagens indica info, loading, success, error ou vazio; o CSS decide sua aparência. Controles de requisição recebem disabled e aria-busy.
  • Não esconda erros do backend nem reimplemente headers, cookies, fetch, limites comerciais, recuperação, polling ou idempotência no tema. A sessão é mantida pelo servidor e pelo navegador; não há tokens de autenticação do painel no runtime.
  • O runtime não oferece mini-cart nem wishlist. A conta do comprador usa os hooks documentados na seção Conta do comprador V3. O contador de carrinho é compartilhado; um drawer visual pode ser criado pelo tema. Busca, categorias, filtros e paginação usam os formulários GET e URLs fornecidos pelo servidor, sem outro controlador comercial no navegador.

Carrossel de banners ​

A raiz data-banner-carousel recebe data-banner-autoplay="true|false", data-banner-interval="5" (segundos, limitado a 3–15) e data-banner-transition="slide|fade". Dentro dela, use data-banner-track e um data-banner-slide por imagem. Controles opcionais: data-banner-prev, data-banner-next, um data-banner-dot por slide, data-banner-pause e data-banner-status com aria-live="polite".

O runtime marca data-banner-ready, alterna is-active, aria-hidden, inert e aria-current, define --banner-offset e acompanha a altura da imagem ativa. O CSS do tema implementa deslizar ou fade e deve mostrar só a primeira imagem antes da inicialização. Uma imagem não precisa de controles nem temporizador. Use <picture> e <source media="(max-width: 767px)"> para a imagem mobile opcional; sem ela, o navegador usa a desktop. URLs internas usam storefront_url e imagens usam asset_url. A mensagem do banner fica na própria imagem; slide.alt descreve essa imagem no alt e no nome acessível do link. O runtime só controla a navegação e não lê esses textos.

Há navegação por setas, indicadores, teclado e gesto horizontal. A troca automática pausa com mouse, foco, aba oculta, botão de pausa ou movimento reduzido. As transições CSS também devem respeitar prefers-reduced-motion. Esse controlador não consulta APIs nem altera carrinho ou checkout; funciona igualmente na prévia.

Validação dos filtros de preço ​

Formulários GET com inputs numéricos priceMin e priceMax recebem validação junto ao campo antes do envio. O runtime aceita campos vazios e confere formato, limite monetário e ordem do intervalo; input e change removem o erro após a correção. O envio continua sendo navegação GET nativa, sem consultas de catálogo no navegador. Não exige classes visuais ou hooks novos; formulários POST e campos ocultos de ordenação não são alterados. Os limites e parâmetros estão no contrato de Categoria e busca do manual oficial de temas.

A validação do servidor permanece obrigatória. Sem JavaScript, os limites vazios continuam funcionando; intervalos invertidos ou URLs malformadas são recusados pelo servidor. Revisões históricas com controladores próprios não recebem o runtime compartilhado até sua migração por nova revisão.

Produto, opções e quantidade ​

Raiz: [data-product-detail]. Atributos comerciais: data-product-id, data-requires-selection, data-price-visible, data-product-has-price; para inclusão, data-cart-endpoint="{{ '/api/cart/items' | storefront_url }}" e data-cart-url="{{ '/carrinho' | storefront_url }}".

HookContrato
[data-product-quantity]Input numérico com min, value e max quando houver limite. Obrigatório para compra.
[data-product-quantity-error]Mensagem de validação da quantidade; necessária para validação imediata.
[data-add-to-cart], [data-cart-message]Botão e mensagem necessários para inclusão.
[data-option-group]Em produto variável, um grupo por dimensão; data-group-index único na raiz.
[data-option-id]Botão dentro do grupo; data-option-id e data-option-name; data-option-image opcional.
[data-option-selection]Texto opcional da opção selecionada no grupo.
[data-product-variant]Um elemento por variante do DTO, com data-variant-id, data-option-ids separados por vírgula, data-in-stock, data-purchasable, data-minimum-quantity, data-maximum-quantity quando não nulo, data-price-amount/data-price-display apenas quando o preço é público. Pode ficar oculto.
[data-product-status], [data-product-selection-message], [data-product-price]Obrigatórios na seleção variável: disponibilidade, erro de combinação e preço.
[data-product-price-prefix], [data-product-compare-price]Opcionais; ocultados quando a variante tem preço público.
[data-product-low-stock]Aviso opcional dentro da raiz; texto e estilo livres. Renderizar hidden quando product.lowStock não for verdadeiro e manter o elemento para futuras seleções. Usar role="status"/aria-live="polite".
[data-gallery-media]Container da mídia principal do produto. Necessário para o vídeo: o runtime substitui seus filhos pelo player e os devolve depois.
[data-gallery-video]Botão com data-gallery-video="{{ product.video.embedUrl }}" e data-gallery-video-title opcional. Ao clicar, o runtime insere um <iframe> do YouTube em [data-gallery-media], marca is-active/aria-pressed e desmarca os [data-gallery-image]. Clicar em uma imagem ou escolher uma opção restaura a mídia original. Somente URLs youtube.com/embed ou youtube-nocookie.com/embed são aceitas.

Para o alerta de estoque baixo, cada [data-product-variant] declara o booleano data-low-stock, usando variant.lowStock ou uma condição Liquid sobre variant.stock com o limite visual escolhido pelo tema. Ausência do atributo equivale a falso. O runtime alterna apenas hidden em todos os avisos da raiz, sem calcular estoque nem alterar texto. Seleções incompletas/ambíguas, variantes esgotadas, sem compra ou sem preço público ocultam o aviso. Tema sem o hook continua funcionando. O alerta é nativo do Node, sem aplicativo ou chave de ativação. Sua presença no Liquid controla a exibição. Os limites e a diferença em relação ao legado estão no manual canônico.

O runtime resolve combinações, mantém data-selected-variant-id e data-selected-variant-has-price na raiz, ajusta quantidade mínima/máxima e bloqueia compra sem seleção, preço ou quantidade válida. Opções impossíveis recebem disabled/aria-disabled; opções sem compra recebem is-unavailable; a escolhida recebe is-selected e aria-pressed. O status recebe data-state="selection|unavailable|available|order". Nenhum preço é recalculado somando valores de variantes.

Evento storefront:product-option-change na raiz, com bubbling e detail: { imageUrl }, informa uma escolha de opção. Serve para atualizar a galeria sem acoplar a lógica comercial à apresentação. O Aura preserva sua escolha manual de foto, thumbnails e zoom no JS visual. O tema pode ignorar esse evento e usar sua própria apresentação de mídia.

Lista de variações e conteúdo em abas ​

[data-option-select] é um select opcional dentro de [data-option-group]. Cada option referencia o ID real em value; a opção vazia é um placeholder disabled. Mantenha os botões [data-option-id] em .product-option-values. O runtime revela a lista inicialmente hidden, oculta os botões e encaminha a escolha para o mesmo fluxo comercial. Sincroniza opções impossíveis, seleção inicial por URL e limpeza das dimensões seguintes. Sem JS, os botões permanecem visíveis. A opção de ocultar fotos das variações não remove data-option-image.

[data-product-discount] é um selo opcional do desconto do produto-base; renderize somente com preço público e compareAtPrice.amount > price.amount. O runtime oculta o selo ao resolver uma variante, pois esse desconto não pertence à variante.

[data-product-information="tabs"] contém dois ou mais details [data-product-panel], cada um com summary e aberto no HTML. O runtime gera tablist, tab, tabpanel, IDs vinculados à raiz do produto e seleção exclusiva. Setas, Home e End mudam aba e foco. Com menos de dois painéis ou sem JS, mantém os blocos legíveis. data-product-information="blocks" mantém os details abertos, transformando o summary em título; accordion preserva a interação nativa. Esses hooks não são obrigatórios em temas próprios e não fazem consultas comerciais.

Quick add, linhas e contador de carrinho ​

Quick add: raiz [data-product-card] com data-product-id, data-minimum-quantity, data-cart-endpoint="{{ '/api/cart/items' | storefront_url }}"; filhos obrigatórios [data-quick-add] e [data-quick-add-message]. Ofereça quick add apenas para produtos simples compráveis conforme o DTO; variantes são escolhidas no detalhe. O runtime envia o mínimo e atualiza [data-cart-count] pelo quantityTotal retornado (não pelo número de linhas); zero oculta o contador.

Fotos dos cards: dentro de [data-product-card], use uma imagem [data-product-primary-image], uma [data-product-secondary-image] inicialmente hidden e um botão type="button" com [data-product-image-toggle], aria-pressed="false", aria-label="Ver outra foto de NOME" e hidden. O botão fica fora de qualquer link; o runtime o revela quando existem as duas imagens. pointerenter de mouse mostra a segunda foto, pointerleave restaura conforme a seleção do botão; toque e teclado alternam a seleção persistente. O runtime muda hidden na imagem secundária e aria-pressed no botão. O tema posiciona a secundária sobre a principal via CSS, respeita [hidden] e preserva um alvo de toque de pelo menos 44px. Não esconda o botão exclusivamente por hover. Se a segunda imagem falhar, o controle é ocultado e a principal continua visível. Não inserir outra cópia do controlador no JavaScript visual do tema.

Linha: [data-cart-line] com data-line-key e data-cart-endpoint="{{ '/api/cart/items/' | storefront_url }}". [data-cart-quantity] é um input com limites do DTO; [data-cart-remove] é o botão de remoção. Os dois são opcionais individualmente; inclua [data-cart-message] para apresentar falhas. PATCH e DELETE recarregam a página após sucesso, para reobter preços e totais do servidor. A inclusão pelo detalhe navega para data-cart-url.

Há um bloqueio compartilhado por documento para mutações, com restauração dos controles e aria-busy. data-cart-was-disabled é transitório/interno e não deve ser estilizado ou alterado. Não há coordenação entre abas: o carrinho atual usa cookie stateless e essa limitação anterior permanece. Nenhum evento de carrinho adicional é necessário para os componentes atuais.

Cupom ​

Raiz form[data-cart-coupon], método POST e action/data-coupon-endpoint apontando para {{ '/api/cart/coupon' | storefront_url }}. Filhos: input [data-coupon-code] com maxlength 30, botão submit [data-coupon-apply], botão opcional [data-coupon-remove] e mensagem [data-coupon-message] com aria-live. O runtime envia somente código, serializa a mutação com as demais operações e recarrega após sucesso. Prévia continua bloqueada antes da rede. Dados de cupom e desconto vêm do servidor; Liquid só formata e escapa.

No checkout, a raiz recebe data-coupon-applied, data-coupon-code, data-coupon-amount e data-coupon-free-shipping. A quantia é somente a do cupom: use cart.coupon.amount quando presente, com fallback cart.discount.amount nas revisões antigas. data-coupon-eligible mantém a expectativa de um cupom elegível que perdeu para uma promoção maior (amount zero, applied false). O runtime envia expectedCoupon para detectar alterações; esses valores não autorizam desconto.

A raiz também recebe data-discount-type (tipo de cart.promotion, desconto_cupom, desconto_frete_gratis ou vazio) e data-discount-amount (cart.discount.amount em centavos). Eles formam expectedDiscount: { type, amount }, com type null quando vazio. O servidor revalida preço, regras e sessão. Resumo atualizado usa [data-checkout-subtotal], [data-checkout-coupon-row] (região do desconto vencedor, inclusive automático), [data-checkout-discount-label], [data-checkout-coupon-code] e [data-checkout-discount]. O rótulo vem de cart.promotion.label ou “Desconto do cupom”; só mostre código se applied true. promotion_changed retorna o carrinho para revisão e mantém a tentativa. Revisões antigas sem expectativa recebem uma revisão quando existe promoção automática; atualizar o tema por nova publicação apresenta o contrato completo. Erros recuperáveis com cart atualizado reapresentam o resumo sem apagar dados pessoais, invalidam o frete selecionado e bloqueiam envio quando o cupom ficou inválido. Inclua link para revisar/remover no carrinho. Não gerar outra tentativa para contornar conflito de idempotência.

Criar o pedido limpa os itens e o cupom do carrinho, antes da aprovação do pagamento. O servidor mantém no cookie assinado o vínculo privado com a confirmação e um recibo do último pedido consumido: reabrir /checkout sem uma nova inclusão retoma o pedido pendente, sem nova criação. Não implementar a limpeza no tema: o POST confirmado atualiza o cookie HttpOnly. Cookies anteriores ainda vinculados a pedidos existentes também são esvaziados. Um replay só pode limpar o carrinho atual se seus itens, variações, quantidades e cupom ainda corresponderem à fotografia do pedido, sem um recibo de consumo do mesmo pedido ou de outro posterior. Uma nova inclusão desvincula a compra anterior; consultar ou aprovar seu pedido não pode limpar o novo carrinho. Cancelar o pedido não restaura seus itens. O pedido anterior não é cancelado por voltar à loja. Os nomes dos pagamentos automáticos combinam o intermediador do contrato com a modalidade; títulos personalizados continuam válidos para pagamentos manuais.

Condições de pagamento no produto ​

O bloco opcional [data-product-payment-offers] contém a oferta unitária calculada no servidor. Declare data-offers-variant="" para a oferta inicial e data-offers-variant="{{ variant.id }}" para cada combinação, usando variant.paymentOffers. Renderize os blocos das outras combinações com hidden; se product.selectedVariantId existir, mostre apenas o bloco correspondente já no HTML inicial. Declare também esse ID em data-selected-variant-id da raiz. O runtime alterna hidden conforme a seleção e oculta todas as ofertas quando a quantidade não for uma unidade. Não calcula parcelas ou descontos. Preserve [hidden] { display: none; } nesses blocos. Temas sem esse hook mantêm seu comportamento.

CEP, frete e totais ​

Raiz de cálculo: form[data-shipping-calculator], com data-shipping-endpoint="{{ '/api/cart/shipping-quotes' | storefront_url }}".

Obrigatórios: input [data-shipping-postal-code], botão submit [data-shipping-submit], mensagem [data-shipping-message] e container [data-shipping-options]. O CEP é validado como oito dígitos e formatado ao sair do campo, sem movimentar o cursor durante a digitação. CEP inválido recebe aria-invalid e foco.

Resumo opcional (um por página): [data-cart-summary] com data-subtotal-amount inteiro em centavos, data-currency e data-shipping-required="true|false". Filhos opcionais [data-cart-shipping] e [data-cart-total] mostram frete e total estimado. Para cupom, acrescente data-total-amount="{{ cart.total.amount }}": é o total de produtos já descontado, calculado pelo servidor. data-subtotal-amount continua sendo bruto. A cotação devolve o total final por modalidade; o runtime apenas o apresenta.

A plataforma gera labels [data-shipping-option="id"] com radio [data-shipping-option-input], conteúdo [data-shipping-option-content] (nome e prazo), e preço em b. A seleção recebe is-selected e radio checked. O CSS pode reordenar esses elementos e estilizar os hooks. Essa estrutura é funcional e neutra; não contém classes do Aura. Na próxima cotação o conteúdo do container é substituído.

As modalidades personalizadas ativas do painel usam os mesmos controles de seleção: nome, valor e deliveryDescription vêm da cotação. O servidor aplica limites de compra/peso, CEP, UF/região, capital/interior e adicionais cadastrados; o tema não calcula essas regras. Uma entrega manual elegível independe das medidas e da origem exigidas por transportadoras automáticas. A barra de frete grátis não habilita nem desabilita essas modalidades.

Editar CEP ou alterar/remover uma linha limpa a seleção e invalida a estimativa. Requisições antigas são abortadas e respostas atrasadas são ignoradas. O checkout recota antes de criar pedido. Não há persistência de seleção de frete do carrinho nem eventos de frete adicionais no contrato atual.

Checkout ​

Raiz: [data-checkout] com data-checkout-attempt opaco fornecido pelo servidor, data-checkout-endpoint="{{ '/api/checkout/orders' | storefront_url }}" e data-shipping-required="true|false".

Obrigatórios: form[data-checkout-form], [data-checkout-submit], [data-checkout-message], [data-checkout-total] com data-subtotal="{{ cart.total.amount }}" em centavos (produtos após desconto vencedor) e [data-checkout-shipping-value]. O formulário fornece inputs com name: name, email, phone, document, postalCode, street, number, complement, neighborhood, city, state. Preserve os atributos HTML de obrigatoriedade e limites do contrato da página.

Quando requer frete, inclua [data-checkout-quote] com data-shipping-endpoint e o container [data-checkout-shipping]. O botão finalizar começa desabilitado e é liberado pela seleção. O total final de cada modalidade é recebido do servidor, em centavos BRL. Quando não há frete, a plataforma envia no-shipping e valor zero.

Nas revisões atualizadas, data-checkout-auto-shipping="true" habilita cotação após 350 ms de pausa. checkout.deliveryModes fornece receive, pickup (descrição pública do local) e quoteFields. O grupo [data-checkout-delivery-modes] contém rádios name="deliveryMode", valores delivery/pickup, antes do fieldset [data-checkout-address]. Não crie uma modalidade que o contexto não ofereceu. Em retirada, o runtime oculta/desabilita os campos de entrega, envia address: null e revalida a opção 48 da loja sem inventar CEP ou consultar transportadoras. Cobrança é tratada separadamente.

data-checkout-quote-fields usa os nomes fornecidos pelo servidor; o padrão aguarda CEP, rua, número, bairro, cidade e UF. A consulta de CEP em andamento adia a cotação. A consulta do endereço permite edição, nova tentativa e preenchimento manual. Repetir input/change com os mesmos valores não duplica consulta. Alterações invalidam total/seleção imediatamente, cancelam a solicitação anterior e descartam sua resposta mesmo se ela chegar após o cancelamento. A entrega de menor price.amount é selecionada na primeira cotação. A seleção anterior por modalidade é preservada por ID enquanto continuar disponível; se desaparecer, usa a mais barata atual. Retirada é filtrada fora da entrega comum e depende de seleção explícita de deliveryMode=pickup; o HTML nunca a pré-seleciona.

checkout.cartKey, escapado em data-checkout-cart-key, identifica apenas a revisão exibida. A chave vem da mesma função estrutural no servidor/runtime, sem autorizar valores. Um carrinho diferente na resposta, no evento storefront:cart-change ou na consulta ao voltar para a aba exige novo resumo/cálculo. Com [data-checkout-items], o resumo muda sem recarregar nem recriar campos/anexos/créditos. Revisões sem esse hook recorrem a checkout:save-draft e ao rascunho da aba por 30 minutos, inclusive a modalidade, sem salvar endereço na conta. Enquanto a entrega aguarda revalidação no fluxo automático, o rótulo mostra “Total parcial, sem frete” e o valor considera somente os produtos/desconto/créditos válidos, excluindo a cotação antiga e o CTA permanece desabilitado. O backend sempre recota ao criar o pedido; a cotação do navegador não autoriza preço.

O runtime monta o payload, envia tentativa opaca e valor esperado de frete, bloqueia submissões concorrentes e navega para confirmação pelo token retornado. shipping_changed exige recotar e selecionar novamente. Repetições manuais usam a mesma tentativa de checkout do servidor; não há geração local de outra tentativa nem retry automático. Não existem eventos adicionais de checkout neste contrato.

Permissões comerciais de pessoa física/jurídica ​

O servidor fornece shop.customerPolicy.individual (CPF) e .company (CNPJ), conforme as flags de bloqueio administradas no painel. O Liquid deve oferecer somente os tipos habilitados no cadastro/perfil e identificar o documento aceito no checkout. Ambos falsos impedem novos cadastros/compras. Mantenha os hooks e nomes personType / document: a proteção é revalidada pelo backend, inclusive para visitantes e contas existentes. Uma recusa person_type_not_allowed usa os canais de erro dos formulários existentes, sem requisições adicionais no tema.

Pagamentos: Pix e cartão ​

Raiz: [data-payment-pix] com data-payment-order="{{ confirmation.orderId }}", apenas numa confirmação autorizada pelo servidor. Este ID é uma proteção de contexto, não uma credencial e não substitui a sessão autorizada.

Obrigatórios:

HookElemento/comportamento
[data-payment-form]Formulário de seleção, inicialmente hidden.
[data-payment-options]Fieldset ou container dentro do formulário. Recebe labels [data-payment-option] e radios gerados. Pode conter legend fixo; só opções geradas são removidas.
[data-payment-message]Mensagem de estado/erro fora do formulário, para continuar visível durante a cobrança.
[data-payment-start]Botão submit, inicialmente disabled.
[data-payment-details]Container fora do formulário, inicialmente hidden.
[data-payment-code]Input ou textarea readonly dentro dos detalhes.

Opcionais: título [data-payment-order-status="<orderId>"] (pode ficar fora da raiz Pix; recebe orderStatusTitle do DTO atual e usa o rótulo antigo quando ausente), imagem [data-payment-qr], botão [data-payment-check], botão [data-payment-copy], texto [data-payment-expiration] e texto [data-payment-total]. Botões opcionais usam type="button". Sem QR, o Pix Copia e Cola continua funcionando. Sem botão copiar, o comprador pode selecionar o texto manualmente. [data-payment-pix-amount] recebe o valor autorizado; [data-payment-monitoring] apresenta pausas/erros da atualização (é criado pelo runtime se necessário). Nos temas atualizados, a cópia do Pix automático precede o QR e o link [data-payment-return] é secundário. No Pix manual, o runtime apresenta o QR acima do código Copia e Cola e dos botões de copiar e conferir a situação, inclusive ao retomar um pagamento pendente pela Minha conta. A consulta explícita compartilha um único controlador entre [data-payment-check] e o botão manual criado pelo runtime, sem depender de um clique no hook opcional. Os botões mostram Consultando…, recebem aria-busy e ficam desabilitados somente enquanto a requisição está ativa; não há espera adicional na interface após a resposta. O limite existente do servidor para verificações de pagamentos integrados permanece: eventual recusa é mostrada como erro, sem cliques silenciosos; Pix manual consulta a situação local. [data-payment-check-feedback] (criado quando necessário, com status acessível) informa carregamento, erro ou Consulta concluída com a situação retornada pelo servidor, inclusive quando ela não mudou. Consultar nunca aprova o recebimento no navegador nem inicia outra cobrança.

O hook opcional [data-payment-card] define a posição do formulário de cartão. Use um id único, inicialmente hidden e fora do formulário de seleção. O provedor selecionado define o formulário nesse container: Brick para Mercado Pago, formulário com tokenização direta para Pagar.me ou formulário com cartão criptografado pelo SDK oficial para PagSeguro transparente (PagBank). Se o hook estiver ausente, o runtime cria o container dentro da raiz de pagamento ao selecionar cartão, inclusive em revisões já instaladas; se faltar apenas o id, gera um. A ausência desse hook não esconde cartão disponibilizado pela API. Habilitação, credenciais e regras comerciais continuam sendo validadas pelo backend.

Quando uma opção autorizada informa requiresBillingAddress: true, o runtime apresenta um formulário separado [data-payment-billing-form] antes dos dados do cartão. A exigência corresponde aos adapters existentes e só aparece quando falta endereço válido no pedido. O mesmo contrato de endereço é validado no servidor e enviado com prepare/start. A fotografia de cobrança fica na composição da tentativa existente; não altera a entrega/retirada nem o cadastro do cliente e é retirada do DTO visual. Replay vincula também o endereço normalizado à chave idempotente, sem gerar outra cobrança. Não remova essa solicitação quando o provedor exigir cobrança.

A seleção de cartão Mercado Pago carrega https://sdk.mercadopago.com/js/v2 e monta o Card Payment Brick com a Public Key e limites vindos da API autorizada. O parcelamento segue o limite de até 12 parcelas do checkout, combinado com o teto e o valor mínimo da parcela cadastrados no admin. Um teto maior no admin (por exemplo, 24) não oculta o cartão: a API oferece até 12, sem alterar o cadastro. Dados brutos de cartão permanecem nos campos do provedor. O runtime envia somente bandeira, parcelas, token transitório e identificação de dispositivo quando disponível. A seleção/preparação vincula o método ao pedido; valor e elegibilidade continuam sendo calculados pelo servidor. Montagem/desmontagem são serializadas: troca de opção ou saída da página invalida callbacks antigos. Erros do SDK não são logados com seus payloads. Preview não carrega SDK nem consulta pagamentos.

No Pagar.me, o runtime monta campos acessíveis para número, nome, validade, CVV e parcelas sem juros. Envia dados de cartão diretamente a https://api.pagar.me/core/v5/tokens?appId=<publicKey>, sem Authorization; só token, bandeira e parcelas seguem para o Node. O backend converte o token no cofre do Pagar.me e cobra pelo identificador do cartão; o tema não recebe esse identificador nem oferece reuso de cartões salvos. Os campos são limpos após tentativa ou saída da página, sem armazenamento local nem logs dos dados. O domínio precisa estar habilitado para tokenização no Pagar.me. Não existe desafio 3DS interativo neste formulário. Prévia não monta formulário nem tokeniza.

No PagSeguro transparente, o runtime monta campos acessíveis para número, nome, validade, CVV e parcelas, carrega https://assets.pagseguro.com.br/checkout-sdk-js/rc/dist/browser/pagseguro.min.js e chama PagSeguro.encryptCard com a chave pública da loja vinda da API autorizada. O cartão completo e o CVV são enviados somente ao SDK de criptografia local. Quando há juros do comprador, o runtime consulta POST /api/payments/card/installments com associação, hash do cálculo e somente o BIN (seis primeiros dígitos). Exibe parcelas, juros e total retornados, permite repetir falhas e descarta respostas de um cartão anterior. A preparação recebe também BIN e hash do plano e consulta novamente as taxas autenticadas; o envio revalida a cotação antes de criar cobrança. Nenhuma taxa enviada pelo navegador é aceita como fonte financeira. Cartão criptografado, titular e seleção seguem no início do pagamento; campos são limpos após cada tentativa. Não há débito nem 3DS. Prévia não monta o formulário nem criptografa.

Boleto Pagar.me, PagSeguro transparente e PagHiper usam as mesmas opções, preparação, retomada e polling do runtime. O hook opcional [data-payment-boleto], inicialmente hidden e fora do formulário de seleção, posiciona linha digitável, botão de cópia, link e vencimento. Se ausente, o runtime cria o container. showBoleto e boleto: { line, url } no DTO autorizam sua exibição; não interpretar estados financeiros no tema. A confirmação financeira continua vindo da API, nunca da emissão do boleto. A plataforma filtra os links retornados pelo provedor e mantém cada emissão vinculada à tentativa do pedido. Os estilos .payment-pagarme-form, .payment-pagseguro-form e [data-payment-boleto] pertencem ao CSS do tema; os temas oficiais já os incluem. Publicar nova revisão para atualizar CSS.

PagHiper usa o cadastro de boleto por e-mail do painel existente. Não oferece Pix ou cartão nesse contrato. O servidor confirma o pagamento pelo retorno autenticado do provedor; o polling da página lê o estado persistido. Se a emissão ficar incerta, a interface bloqueia outra cobrança e orienta conferência. O tema não deve criar links de boleto, reenviar emissão nem interpretar notificações.

A Carteira PicPay usa method: wallet, com preparação, envio único e acompanhamento pelo runtime. O hook opcional [data-payment-wallet], inicialmente hidden e fora do formulário, posiciona o link Pagar no PicPay e a validade. Se ausente, o runtime cria o container. showWallet e wallet: { url } autorizam a exibição. O link abre somente o checkout HTTPS validado do PicPay em outra aba; não é Pix Copia e Cola. Confirmação, expiração, revisão e retomada vêm do backend. Instruções são removidas quando deixam de ser exibíveis. Nenhum token PicPay chega ao navegador. O CSS de [data-payment-wallet] pertence ao tema; os temas oficiais incluem estilos do link e foco, aplicáveis às lojas por nova revisão. Prévia não consulta nem cria pagamentos. A plataforma controla também wallet/prepare e wallet/start; o tema não chama essas rotas por conta própria.

A Vindi Commerce também usa method: wallet, com provider: vindi, para cartão no checkout hospedado. O runtime identifica a Vindi no seletor e no botão de pagamento; não rotule toda opção wallet como PicPay. O mesmo hook [data-payment-wallet] recebe o link HTTPS oficial validado no servidor. O comprador informa cartão e parcelas na Vindi; o tema não coleta PAN/CVV nem aprova o pedido pelo retorno do navegador. A confirmação continua vindo da consulta autenticada feita pelo backend. Pix Vindi usa os hooks de QR Code e copia e cola já existentes, sem novo formulário ou SDK no tema.

As formas manuais cadastradas no painel (Pix/depósito e pagamento personalizado) usam o mesmo seletor. O personalizado usa o título cadastrado no painel, como “Pagar na entrega”, inclusive quando existem várias opções personalizadas. Ao selecionar, o runtime apresenta as instruções e o valor antes da confirmação. Ao confirmar, chama manual/select e registra a escolha aguardando conferência. O personalizado não exige chave Pix, conta bancária ou credenciais de gateway. As opções respeitam ativação, exibição, tipo de pessoa e limites do cadastro. O hook opcional [data-payment-manual] permite escolher a posição dessas instruções; se ausente, o runtime cria o container dentro da raiz de pagamento, inclusive em revisões já instaladas. Os dados textuais são inseridos como texto; o HTML das instruções é sanitizado no servidor para parágrafos, listas e ênfase, sem atributos. Trocar para uma opção online ou recarregar as opções oculta as instruções da seleção anterior. A confirmação recupera o título e as instruções registrados na escolha, mesmo que o cadastro seja alterado depois.

Os adicionais percentual e fixo do cadastro manual aceitam valores negativos como descontos. O percentual incide sobre os produtos após o cupom, sem frete; o desconto combinado fica limitado a esse saldo. O valor apresentado e persistido é calculado no servidor. O desconto Pix específico de gateways não se aplica às formas manuais.

A escolha manual fica aguardando conferência pelo lojista no painel existente. Não cria cobrança em gateway, não confirma pagamento, não baixa estoque e não agenda polling financeiro. Recarregar a confirmação recupera a escolha persistida e consulta a situação atual do pedido. Instruções deixam de ser apresentadas quando o pedido é aprovado, cancelado ou fica indisponível. A interface mostra indisponibilidade temporária quando opções cadastradas falham na validação técnica; o servidor registra o motivo por loja/associação, sem credenciais.

A plataforma controla card/prepare, card/start, /api/payments/options, pix/prepare, pix/start, pix/current, pix/check e pix/qr, headers X-LojaVirtual-Storefront/X-Payment-Order, cookies da mesma origem e crypto.randomUUID() usado na mesma tentativa de prepare/start. O contexto do pedido também é validado em options.current.

Reload consulta opções/tentativa existente. Poll consulta somente o estado local a cada dez segundos quando shouldPoll é verdadeiro; não cria cobrança nem consulta o provider. Consulta manual chama check com intervalo mínimo de quinze segundos. Após resposta perdida, consulta current sem repetir criação; se também perder essa consulta, mantém bloqueio até recuperação ou reload. A disponibilidade de uma nova tentativa vem de blocksNewPayment, não de um mapa de estados do tema.

Quando a tentativa permite novo pagamento, a seleção anterior é descartada e o formulário permanece oculto/bloqueado até receber novas opções. Isso também vale para retorno pelo bfcache. Após a recarga, é obrigatório selecionar uma opção novamente; falha na consulta mantém o bloqueio. O evento de estado continua refletindo blocksNewPayment do backend, sem autorizar reutilizar opções antigas durante essa atualização.

data-payment-state na raiz reflete o estado recebido. statusMessage vem do backend; showPix e presença do código controlam os detalhes. O formulário/controles são bloqueados por tentativa existente, execução ou resultado incerto. Código/QR são retirados quando deixam de ser exibíveis. Falha no QR orienta a usar Copia e Cola; falha no clipboard foca/seleciona o texto e informa como copiar manualmente. Sucesso mostra “Código copiado”. O estado do servidor não muda por copiar ou clicar em Já paguei.

Polling usa GET local a cada dez segundos, por até dez minutos e sessenta consultas, sem renovar cobranças nem deduzir expiração pelo relógio do navegador. Respostas de leituras anteriores não sobrescrevem uma consulta mais recente. pagehide cancela timers e invalida leituras; o retorno pelo bfcache reconsulta opções. A aba oculta interrompe consultas; voltar revalida sem prolongar automaticamente o prazo dessa visualização. Após limite/falha, Atualizar pagamento (hook opcional) ou recarregar retoma a consulta, sem prepare/start. A confirmação por notificações/workers do servidor permanece independente do limite da interface.

Evento storefront:payment-state-change, com bubbling, tem detail: { state, blocksNewPayment, showPix, shouldPoll }. Use apenas para efeitos visuais. Não altere flags, não calcule estados financeiros e não inicie outra cobrança por esse evento. Não inclui código Pix ou credenciais.

Exemplo mínimo sem JS do tema:

liquid
<section data-payment-pix data-payment-order="{{ confirmation.orderId }}">
  <p data-payment-message role="status" aria-live="polite"></p>
  <form data-payment-form hidden>
    <fieldset data-payment-options><legend>Pagamento</legend></fieldset>
    <button data-payment-start type="submit" disabled>Gerar Pix</button>
  </form>
  <div data-payment-manual hidden></div>
  <div data-payment-card hidden></div>
  <div data-payment-boleto hidden></div>
  <div data-payment-wallet hidden></div>
  <div data-payment-details hidden>
    <label>Código Pix <textarea data-payment-code readonly></textarea></label>
    <button data-payment-copy type="button">Copiar</button>
    <button data-payment-check type="button">Consultar pagamento</button>
  </div>
</section>

Metas e créditos no checkout ​

[data-purchase-benefits] é a região opcional de metas no carrinho/checkout. O Liquid renderiza a apresentação inicial; uma nova cotação atualiza os dados no carrinho e checkout, mesmo sem mudança de total, com texto escapado e valores calculados pelo servidor. A região fica oculta quando não há benefícios; uma resposta sem benefícios remove os anúncios anteriores. Use aria-live="polite", títulos e progress nativo acessível. Os temas oficiais usam .purchase-benefit; toda aparência permanece no CSS de cada revisão.

A raiz [data-checkout] declara data-expected-gift-ids com os goalId de cart.benefits.gifts separados por vírgula (vazio quando não há brindes). O runtime envia expectedGiftIds; mudanças exigem nova revisão do carrinho. O servidor determina os produtos: enviar outro ID não concede um brinde.

Dentro de [data-checkout-form], um input opcional [data-checkout-credits] usa name="credits", type="number", min="0", step="0.01", value="0" e max em reais a partir de checkout.creditsMaximum. Só o input usa reais; creditsAmount no POST usa centavos. [data-checkout-credits-row] e [data-checkout-credits-value] apresentam a dedução e o total acompanha a escolha. A validação local é auxílio de interface; a autorização ocorre no servidor. Não salvar saldo, fazer débito ou gerar cashback em JavaScript do tema. Depois de uma recotação, o total reaplica a escolha de créditos. Se a ativação ou o mínimo mudarem, a escolha permanece preenchida para correção, mas deixa de ser deduzida. Total comercial ausente é exibido como indisponível, nunca zero.

credits_unavailable mantém o preenchimento para corrigir o valor. Mudança de brindes exige revisar/reabrir o carrinho, preservando a tentativa existente até uma decisão explícita. A repetição após resposta perdida mantém o mesmo UUID, o mesmo valor de créditos e os mesmos IDs esperados. Não criar nova tentativa automaticamente. A prévia bloqueia mutações antes de acessar a rede.

Modalidades de frete podem conter deliveryDescription em vez de prazo numérico. O runtime apresenta o texto cadastrado escapado, sem inventar uma data de entrega.

Ofertas de catálogo e publicidade ​

O endereço /produto/camisa?variant=123 seleciona a combinação pública 123 do produto. O servidor valida o vínculo e apresenta seu preço no HTML inicial; o runtime seleciona as opções e aplica quantidade/estoque próprios. Uma combinação que não pertence ao produto recebe 404. Links sem variant preservam a seleção manual. Esse parâmetro não permite definir preço, estoque ou loja.

Em lojas habilitadas, o runtime apresenta consentimento de publicidade e o botão Privacidade, sem exigir código extra do tema. Pixel e API de Conversões são administrados pela plataforma; não duplique os mesmos eventos no JavaScript do tema ou no Tag Manager. Nenhum token Meta é fornecido ao Liquid ou ao navegador. Prévias não ativam essa coleta. Revisões sem o runtime compartilhado precisam de atualização/publicação antes de usar o recurso.

Os hooks existentes de produto, carrinho e checkout continuam sendo utilizados. Nenhum novo setting visual ou atributo obrigatório de tema foi introduzido.

Contato e dúvidas de produtos ​

O papel opcional contact do manifesto compõe /contato. A query produto=ID apresenta o produto disponível da mesma loja. O cliente não precisa entrar na conta. Use capabilities.contact para apresentar links/formulário quando o backend e a revisão oferecem esse fluxo. Na prévia, a apresentação é habilitada e o envio é bloqueado pelo runtime. O formulário continua editável em Liquid/CSS.

liquid
{% if capabilities.contact %}
  <a href="{{ '/contato' | storefront_url }}">Fale com a loja</a>
  <a href="{{ '/contato?produto=' | append: product.id | storefront_url }}">Tire uma dúvida</a>
{% endif %}

O segundo link pertence à página de produto. form[data-contact-form] exige method="post" e action="{{ '/api/contact' | storefront_url }}". Campos name (2–150), email (até 100), message (10–5.000) são obrigatórios; phone é opcional (até 45). Quando houver produto, inclua input[type=hidden][name=productId] com product.id. Não envie nome/link do produto, destinatário ou ID de loja.

Um fieldset agrupa os campos visíveis e um campo website vazio, oculto e fora da tabulação, funciona como honeypot. Mantenha o botão submit fora do fieldset: ele permite retentar o mesmo pedido quando a resposta se perde. Inclua a mensagem [data-contact-message] com role="status" e aria-live="polite" fora do fieldset. Cada label aponta para um ID único. Use labels visíveis, limites HTML e campos com fonte de pelo menos 16px em telas pequenas.

O runtime prepara o CSRF em /api/contact/context, envia JSON para a mesma origem e conserva conteúdo/UUID durante retries na mesma página. O tema não cria tokens, polling ou lógica de envio. A confirmação significa mensagem registrada para encaminhamento; não afirma entrega do e-mail. O envio exige JavaScript. Não use mailto: como action nem mostre sucesso antes da resposta positiva do backend.

Os temas oficiais oferecem a section e os links; revisões já instaladas precisam de adaptação e publicação explícita. Temas sem templates.contact continuam válidos, mas /contato responde 404. O editor inclui Contato no seletor e conserva o produto ao navegar do detalhe para o formulário. O exemplo completo está em Formulário de contato.

Para adaptar uma revisão antiga pelo editor, a plataforma prepara o template templates/platform_contact_v1.json e a section sections/platform_contact_v1.liquid a partir do formulário oficial, no rascunho. Também acrescenta estilos responsivos a assets/theme.css, sem apagar o CSS anterior. Essa base fica restrita a .contact-page na camada lojavirtual-contact; regras comuns do tema têm prioridade para preservar personalizações. A IA recebe esses arquivos para adaptar a aparência e incluir o botão. O servidor acrescenta somente o papel contact ao manifesto efetivo da prévia, do ZIP e da nova revisão publicada. theme.json permanece protegido; a IA não cria templates. Um contact.json arbitrário não habilita o recurso. Durante a preparação, a composição oficial é preservada. Antes de devolver a proposta, o editor verifica os campos e hooks no HTML renderizado do contato. Depois de publicada, a revisão segue as regras de edição dos templates existentes.

Contatos já declarados mantêm seu caminho. Se um contato preparado anteriormente em templates/platform_contact_v1.json ainda não tiver a base CSS, um pedido de correção visual pode acrescentar somente os estilos ao rascunho, sem recriar o formulário. A presença do marcador /* LojaVirtual: contact presentation v1 */ evita repetições; não há correção automática ao abrir o tema. Colisões com os arquivos da preparação e temas com controladores anteriores ao runtime compartilhado exigem revisão técnica, sem sobrescrever arquivos. Ler um tema ou editar outra parte não o migra. A preparação só chega ao editor após a edição e a prévia válidas; falhas e perguntas preservam o rascunho anterior. Nenhuma revisão publicada é regravada, e a publicação continua explícita.

Temas V3 · Liquid estrutura, CSS desenha, JSON compõe.