Skip to content

Formulários de conta e anexos ​

Conta do comprador V3 ​

O papel opcional account compõe todas as views da conta. buyer.enabled controla atalhos, buyer.authenticated separa entrada/cadastro de conta/pedidos/saída. Layouts precisam passar buyer: buyer ao render isolado do header. Nunca use o objeto como autorização: ela é refeita no servidor. Revisões sem o papel recebem buyer.enabled: false; não criar URLs de conta incondicionais.

Formulários declaram method="post" e action interno correspondente à API, inclusive saída, dados pessoais, pagamento e checkout. Sem runtime, o envio nativo é recusado pelo servidor sem colocar credenciais na URL. Formulários usam data-buyer-form, data-buyer-action (entrar, cadastro, dados, endereco, senha, sair, pagamento) e data-buyer-csrf="{{ buyer.csrf }}". Pagamento acrescenta data-buyer-order. Inclua botão type="submit", mensagem data-buyer-message com role/status e spans data-buyer-error="nomeDoCampo" vinculados por aria-describedby. Inputs de senha usam autocomplete current-password ou new-password; data-buyer-toggle="idDoInput" alterna visibilidade e aria-pressed. Senhas novas devem ser obrigatórias e limitar a 128 caracteres, sem minlength de 12 nem descrição dessa exigência. O servidor aceita senha não vazia e preserva espaços; login mantém o limite histórico de entrada. Rótulos são sempre visíveis. O runtime controla processamento, bloqueio de repetição, foco no erro, requests same-origin e redirecionamento. Não envia forms em preview.

reCAPTCHA v2 nos formulários públicos da conta ​

O reCAPTCHA está temporariamente suspenso pela plataforma. O endpoint /api/account/captcha retorna { "provider": "recaptcha-v2", "enabled": false }. O runtime oculta o container, não carrega o SDK do Google e não envia X-Recaptcha-Token; as quatro operações de conta dispensam a verificação. CSRF, validação de origem e demais regras de conta permanecem ativos. A suspensão é definida no servidor, não pelo tema ou pela requisição. Na prévia, o hook continua demonstrativo, sem operações reais.

Quando reativado pela plataforma, as ações entrar, cadastro, recuperar e redefinir-senha exigem reCAPTCHA v2 do tipo checkbox. Dentro do respectivo [data-buyer-form], o tema posiciona:

liquid
<div data-recaptcha></div>

Não é uma tag Liquid especial. É um ponto de montagem HTML que a IA pode colocar em qualquer posição dentro do formulário. data-recaptcha-theme="dark" e data-recaptcha-size="compact" são opcionais; os padrões são light e normal. O tema controla o espaço ao redor; a interface interna é do Google.

O runtime consulta /api/account/captcha na própria origem para obter a chave pública da plataforma e carrega uma única vez o SDK oficial, com renderização explícita. Cada formulário recebe seu próprio widget. O tema não fornece chaves, scripts nem callbacks. Se o hook estiver ausente em uma revisão antiga, o runtime acrescenta o container ao final do formulário protegido. Repetir o hook não cria vários desafios no mesmo formulário: somente o primeiro é usado.

O token segue em X-Recaptcha-Token no POST JSON da conta, junto do CSRF existente. O campo g-recaptcha-response criado pelo SDK não entra no corpo comercial. O Node valida o token com o Google e confere o hostname contra a origem da loja resolvida pelo servidor. Remover o widget, alterar atributos ou enviar diretamente ao endpoint não dispensa a verificação. A exigência não usa a antiga flag flg_habilita_captcha, nem pode ser desligada pelo tema ou por dados da requisição.

Token ausente/inválido/expirado resulta em erro 400; configuração ausente ou falha do provedor resulta em 503. Nenhuma dessas falhas executa a operação protegida. O runtime mostra mensagens em [data-buyer-message], renova o desafio após cada tentativa HTTP (inclusive erro de validação ou de rede) e trata a expiração. Os tokens são de uso único e têm validade curta, conforme a verificação oficial do Google.

Na prévia, o container mostra uma indicação demonstrativa: não consulta chaves, não carrega o Google e não envia formulários. Essa integração protege os quatro endpoints de conta listados; não cria formulários de contato nem acrescenta CAPTCHA ao checkout, pagamento ou edição de dados autenticada.

Campos e operações da conta ​

Entrar: email, password, returnTo. Cadastro: name, email, password, personType, returnTo e, se mantidos pelo tema conforme buyer.registrationFields (campos habilitados no painel), phone, document, birthDate, sex, stateRegistration, whereFound/whereFoundOther, o endereço (postalCode, street, number, complement, neighborhood, city, state) e custom_<id> por campo personalizado. O servidor aceita campos habilitados que o tema omite, inclusive telefone e campos personalizados obrigatórios no painel. Campos enviados são validados; um endereço enviado precisa estar completo. Campos não habilitados são recusados pelo servidor. Dados: name, phone, document, personType; e-mail é readonly e não é enviado. Senha: currentPassword, password. Saída é POST; não há GET com efeito colateral. Dados monetários dos pedidos continuam usando money.

Endereço principal: formulário separado em Meus dados com ação endereco, POST /api/account/endereco, campos postalCode, street, number, complement, neighborhood, city, state. Apenas complemento é opcional. O servidor fornece buyer.address nessas telas e no checkout, ou null se não existir endereço.

No checkout autenticado, o tema pode incluir checkbox name="saveAddress", sem checked, com texto “Salvar este endereço na minha conta”. O runtime envia booleano; ausente/desmarcado não modifica a conta. O consentimento não é preservado ao trocar de sessão. Um rascunho sem endereço digitado não apaga o principal pré-preenchido; quando há endereço digitado, ele prevalece para aquela compra. Nenhum preenchimento consulta API de CEP. Conta e pedido mantêm fotografias de endereço distintas.

Checkout atualizado acrescenta data-buyer-csrf e data-buyer-store. Links de entrada/cadastro usam data-checkout-login e retorno /checkout. O runtime preserva campos na aba por 30 minutos, sem guardar senha, sessão, token ou tentativa. A volta ganha outro UUID; exige conferir frete e enviar novamente. data-checkout-session-choice apresenta nova entrada ou escolha explícita de visitante (data-buyer-guest="true" no formulário de saída). Erros de campo recebem data-checkout-field-error; estados de identidade nunca reenviam o pedido.

O servidor persiste loja e identidade inicial em node_checkout_attempt ao fornecer checkout.attemptId. O único cookie de identidade é lv_buyer_v3; não há cookie por UUID, marcador global ou prova de tentativa no body. Revisões anteriores continuam enviando somente checkoutAttemptId. A sessão atual precisa corresponder ao proprietário inicial autenticado. Tentativas de visitante continuam visitantes, mesmo após login em outra aba. Para vincular à conta, entrar e abrir outro checkout. Logout nunca altera a identidade de uma tentativa existente.

O runtime mantém a mesma tentativa em retries, sem gerar outra automaticamente. invalid_checkout_attempt, buyer_identity_changed, session_expired e buyer_unavailable mostram recuperação explícita. O campo buyerContext de revisões anteriores é aceito mas ignorado para autorização; o Aura novo não o emite. O cookie anti-CSRF dos formulários de conta permanece independente das tentativas. SQL manual, transição de abas abertas antes do deployment, snapshots e limites de infraestrutura estão em Área do comprador V3.

Etapa de escolha do pagamento ​

Com a capacidade de pagamentos habilitada, o servidor fornece checkout.paymentStep e a criação idempotente do pedido retorna nextUrl: /checkout/pagamento/:token. O mesmo template interno confirmation recebe checkoutPaymentStage: true e confirmation.confirmationUrl; o servidor valida o token e o isolamento por loja antes de montar a sessão. A página continua com scripts restritos e é classificada como checkout, sem disparar os eventos de acompanhamento do Google Commerce.

Os vinte temas atualizados declaram data-payment-confirmation-url na raiz data-payment-pix somente nessa etapa. O runtime também reconhece o caminho em revisões anteriores, sem reescrever temas já publicados. Após uma ação explícita bem-sucedida ou a recuperação da tentativa após resposta perdida, navega uma vez ao acompanhamento canônico. Abrir/recarregar/polling não geram nova cobrança nem forçam a navegação. Links antigos de confirmação permanecem válidos.

O runtime agrupa opções elegíveis pela modalidade, preservando a primeira na prioridade do servidor. Pix automático e manual permanecem distintos. Não há escolha por menor preço nem alteração da elegibilidade financeira. data-payment-reload é opcional e consulta as opções/estado; data-payment-base-total permite apresentar a diferença da opção escolhida em [data-payment-adjustment="ID"], e [data-payment-order-total="ID"] recebe o total autorizado para aquele pedido. A interface não calcula uma nova autorização de cobrança. orderStatusTitle vem do servidor e não equivale ao nome do provedor ou ao rótulo administrativo antigo.

Anexos de pedido ​

O runtime compartilhado lê [data-order-attachment-input] dentro do checkout e adiciona o arquivo à mesma requisição/tentativa de compra. Sem seleção, preserva o contrato anterior. PDF/PNG/JPEG/WebP até 5 MiB; validação definitiva no servidor. [data-order-attachment-clear] limpa somente a seleção local, sem rede.

Na conta, [data-order-attachment-form] exige data-order-id, data-attachment-id (vazio quando ausente), data-buyer-csrf, método POST e action interno explícito. O submit normal envia o arquivo; um submit com data-order-attachment-remove envia attachment null. A região [data-order-attachment-message] recebe progresso/erro. O runtime bloqueia envios simultâneos e toda mutação em preview, envia Origin/CSRF pelo contrato de conta e recarrega o pedido após sucesso. Falha de rede orienta recarregar antes de repetir. O backend compara o anexo esperado para não sobrescrever alteração concorrente.

O tema decide livremente posição, texto e apresentação. Campos e comportamento não ficam em settings nem em JSON visual. Ver contrato completo.

Recuperação de senha ​

O formulário data-buyer-action="recuperar" envia email e returnTo ao POST /api/account/recuperar. A resposta é genérica para contas ausentes, bloqueadas ou ambíguas. O formulário data-buyer-action="redefinir-senha" declara inputs token vazio, password e returnTo, e POST /api/account/redefinir-senha. O runtime lê o fragmento do link somente na página de redefinição, limpa esse fragmento do histórico e transmite o segredo no corpo JSON com CSRF. Não usar query string, localStorage nem GET para enviar senha/token. O backend exige novo login após concluir. buyer.recoveryEnabled indica a disponibilidade funcional.

A página de redefinição declara data-buyer-recovery-page mesmo quando o formulário está indisponível; isso permite limpar o fragmento também nesse estado.

Apresentação compacta da compra ​

ThemeEngine fornece purchase.active nos templates internos checkout e confirmation; purchase.stage vale details, payment ou tracking. O layout passa purchase explicitamente ao cabeçalho/rodapé e adere com body[data-purchase-stage]. Não deduza esse estado de page.type, que pode vir do contexto de carrinho. Cabeçalho compacto identifica a loja e aponta ao carrinho; ajuda, políticas configuradas, informações da empresa e páginas institucionais continuam no rodapé. A Home conserva a navegação normal.

A folha privada /storefront/checkout-summary.css acompanha checkout e confirmação. Preserva ajustes monetários e compactação do topo também em revisões anteriores; não regrava bundles publicados. Título padrão Checkout passa a Finalizar compra; o runtime encurta somente o link padrão Alterar cupom ou revisar carrinho. Textos personalizados são preservados. Nos templates oficiais atualizados, .purchase-payment-heading fica dentro de .purchase-payment-layout: em desktop ocupa a primeira linha da coluna de pagamento, enquanto o resumo ocupa a lateral desde o topo; em celular a ordem é título, resumo e conteúdo do pagamento. Essa mudança de Liquid exige nova revisão; não há regravação automática de temas publicados. Os vinte templates novos organizam resumo em details[data-purchase-summary], aberto na etapa de dados/entrega em desktop e celular; nas etapas de pagamento/acompanhamento inicia recolhido no celular, com <summary> nativo. Cupons usam details.purchase-coupon com o mesmo endpoint do carrinho; no checkout o contêiner data-cart-coupon é uma div, evitando formulários aninhados, e data-coupon-apply tem type="button". Enter aplica o cupom sem enviar o pedido. O campo não é required.

[data-checkout-items] permite atualizar apenas linhas do resumo quando o carrinho muda. Dados pessoais, FileList, modalidade e créditos não são recriados. Revisões sem esse hook mantêm recuperação por rascunho de identificação/endereço. Mudanças comerciais invalidam a entrega; a chave estrutural inclui condição e desconto do cupom, não apenas seu código.

O grupo único [data-purchase-actions] contém o botão original e o total. [data-checkout-action-total] copia apenas o texto de [data-checkout-total]; nunca calcula preço. Em celular, ResizeObserver reserva a altura real, visualViewport posiciona acima do teclado/controles e o foco em campo recebe espaço de leitura. Abaixo de 280 px de altura disponível a ação volta ao fluxo rolável. pagehide desconecta observadores e pageshow.persisted retoma. O cartão conserva o botão e a validação do SDK: nenhuma cópia visual inicia cobrança. Políticas de consentimento, isolamento e eventos comerciais permanecem independentes da apresentação.

Checkouts oficiais anteriores com data-editor-field="shipping_button_text", já sem controladores próprios, também recebem cotação automática, salvo data-checkout-auto-shipping="false" explícito. Revisões com controladores históricos continuam no modo postal-only para evitar duplicação de operações.

Na entrega automática, [data-checkout-delivery-message] anuncia carregamento/resultado junto das opções. O botão [data-checkout-quote] passa a retentativa, oculto no caminho normal e disponível após falha; ausência de opções orienta corrigir o endereço. O CTA principal permanece visível/desabilitado até a cotação válida; a primeira seleção usa a entrega mais barata e preserva o ID escolhido quando ainda disponível. A atualização de preço continua dependendo do servidor.

Os vinte templates colocam section[data-checkout-delivery-options] imediatamente depois do fieldset de endereço, com título Opções de entrega, estado inicial Informe seu CEP para ver preços e prazos e estado de consulta Buscando opções de entrega…. O grupo de opções recebe aria-busy. Nenhum campo de identificação é bloqueado durante a consulta. O resumo continua na coluna lateral em desktop e após o formulário em celular. [data-checkout-total-label] guarda data-resolved-total-label; [data-checkout-action-label] acompanha o rótulo parcial/final sem alterar o nome personalizado validado. checkoutPartialTotal só adere no cotador automático: revisões com controlador próprio preservam seu contrato. O renderer existente gera cartões com rádio nativo, nome/preço/prazo e seleção destacada; não há outro controlador de frete.

Continuidade da compra e confirmação do pedido ​

O runtime carrega do servidor data-checkout-store e data-checkout-draft-identity na sua própria tag. O segundo é um identificador derivado do contexto anti-CSRF de uma conta autenticada, nunca o token original; visitantes usam guest. Esses atributos separam o preenchimento por loja/identidade na aba e não autorizam operações comerciais.

O carrinho guarda somente intenção de serviço, CEP e expiração de trinta minutos em sessionStorage; nenhum preço ou cotação é autorizado pelo navegador. O checkout preenche o CEP, recota com o endereço completo e mantém o serviço se ainda existir. Se a escolha ficar indisponível, exige outra seleção explícita. Mudança de CEP invalida a intenção anterior. Alterar quantidade mantém a intenção do serviço, mas exige nova cotação.

O rascunho do checkout preserva identificação, endereço e modalidade ao revisar o carrinho ou sair/recarregar a página. Nunca guarda anexos, senhas, tokens ou tentativa de pedido. A troca de identidade descarta o rascunho anterior; o visitante que escolhe explicitamente entrar pode transferir seu próprio preenchimento à conta. O evento checkout:completed remove o rascunho após a resposta de criação, antes da navegação. Storage indisponível gera diagnóstico sem dados pessoais e não impede o preenchimento manual.

confirmation.items fornece { name, quantity, price, total, options: [{ group, name }] } dos itens históricos. confirmation.address contém destinatário, rua, número, complemento, bairro, CEP, cidade e UF fotografados no pedido; é nulo na retirada. confirmation.pickup e confirmation.shippingDetails identificam retirada e instruções gravadas. Esses dados são localizados somente após autorizar o token opaco na loja; não devem ser reconstruídos com o produto, perfil ou endereço principal atual.

Os vinte modelos oficiais atualizados apresentam itens e destino no pagamento e na confirmação, e usam product.preparationNotice como texto escapado. O aviso de encomenda só aparece para a unidade comprável sem estoque físico; não muda disponibilidade nem prazo do frete. cart.items[].product.preparationNotice fica nulo para unidades que não estão por encomenda. O aviso combina os campos comerciais existentes, sem criar cadastro paralelo ou estimar dias ausentes. Uma atualização do carrinho reexibe esse texto por textContent.

No Aura, Ver todos nos destaques abre /busca. O bloco brand_intro aceita button_link para um destino institucional explícito; sem destino, oferece contato ou catálogo com rótulo correspondente. Não deduz uma página institucional nem o catálogo completo a partir da primeira categoria. Os ajustes de Liquid e JavaScript visual exigem nova revisão do tema; revisões publicadas não são reescritas.

A rota /busca sem q, com q= ou contendo apenas espaços lista o catálogo público completo. A fonte Liquid listing segue a mesma consulta. Um termo preenchido continua filtrando os resultados; facetas e paginação permanecem disponíveis, e as regras de visibilidade e isolamento por loja continuam no repository.

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