Meus Cartões (Minha Conta) Storefront 2.0

A seção Meus Cartões permite que o cliente final gerencia seus Cartões de Crédito salvos. Esta funcionalidade foca na transparência e no controle de dados pelo usuário, permitindo a visualização e exclusão de cartões vinculados à sua conta.

📘
Info: Fluxo de Adição
Por motivos de segurança e conformidade com o fluxo de checkout, não é permitido adicionar novos cartões através desta interface. A adição de novos cartões ocorre exclusivamente durante a jornada de compra (Checkout).

Configuração de Rota

Para habilitar a página, é necessário registrar a nova rota no arquivo de configuração de páginas do tema (Configs/pages.json).

A página deve obrigatoriamente exigir autenticação para proteger os dados sensíveis do cliente.

{
  "name": "cards",
  "url": "cards",
  "path": "account/cards.html",
  "query": "account/cards.graphql",
  "authLevel": "Authenticated",
  "authFallback": "login/authenticate"
}

Dados e Queries (GraphQL)

A funcionalidade consome o endpoint de customer para buscar os cartões de pagamento. Abaixo está a estrutura da query utilizada:

Query: Queries/account/cards.graphql

query Account($customerAccessToken: String!, $hasCustomerAccessToken: Boolean!) {
  customer(customerAccessToken: $customerAccessToken) @include(if: $hasCustomerAccessToken) {
    customerName
    paymentCards {
      id
      name
      number
      brand
      expiration
      isSubscription
      subscriptionId
      isSuggestedCard
    }
  }
}

Atributos Principais

Campo	Tipo	Descrição
isSubscription	Boolean	Indica se o cartão está vinculado a uma assinatura ativa.
subscriptionId	String	ID da assinatura vinculada (utilizado para gerar links de redirecionamento).
isSuggestedCard	Boolean	Define se o cartão é um "cartão sugerido" salvo para compras avulsas.
brand	String	Bandeira do cartão (ex: visa, mastercard, amex).

🚧
Atenção: Cartões com Assinatura e Vínculos Híbridos
Se um cartão estiver associado a uma assinatura ativa — mesmo que também possua o status de pedido avulso (isSuggestedCard) — ele será exibido exclusivamente na listagem de assinaturas. Nesses casos, a exclusão não será permitida para evitar falhas no processamento de novos ciclos de recorrência, garantindo que a próxima compra programada ocorra sem interrupções.

Implementação no Template

No arquivo de visualização (Pages/account/cards.html), você deve estruturar o layout utilizando os componentes da Wake. O componente principal realiza a lógica de separação entre cartões de compras avulsas e cartões de assinatura.

<div class="wake-account-wrapper">
  {{ wake_account_sidebar customer: data.customer }}
  {{ wake_account_cards cards: data.customer }}
</div>

Componentes Disponíveis (UI)

A Wake fornece componentes de alto nível que já tratam a lógica de exibição e exclusão. Estes componentes são "fechados", garantindo a segurança das operações de exclusão de tokens.

wake_account_cards

Componente mestre que organiza a listagem. Ele separa automaticamente os cartões em dois blocos:

Cartões das Compras: Lista cartões onde isSuggestedCard é verdadeiro e não há assinatura ativa vinculada. Permite a exclusão direta.
Cartões das Assinaturas: Lista cartões vinculados a um subscriptionId. Se o cartão for híbrido (avulso + assinatura), ele será movido para este bloco. Exibe um link para a gestão da assinatura em vez do botão de exclusão.

🚧
Regra de Exclusão
A exclusão de um cartão que possua qualquer vínculo com assinaturas deve ser feita através da página de detalhes da própria assinatura, obrigando o cliente a definir uma forma de pagamento substituta para não interromper o serviço.

Comportamento de Exclusão

A exclusão de cartões sugeridos utiliza a função deleteCustomerSuggestedCard(cardId) presente no core do repositório de componentes.

Confirmação: Ao clicar em excluir, um modal de confirmação é exibido ao usuário.
Execução: Após a confirmação, é chamada a mutation deleteSuggestedCard.
Feedback: Um overlay de carregamento é exibido durante a transação, seguido de um refresh nos dados da página após o sucesso.

Assets de Marca

Para garantir a melhor experiência visual, o tema deve conter os ícones das bandeiras no caminho Assets/Img/payment-brands/. Os nomes dos arquivos devem corresponder ao campo brand retornado pela API:

visa.png
mastercard.png
amex.png
elo.png
hipercard.png

Branch awake (checkout-ssr) : https://git.fbits.net/stores/awake Branch wake-components (v1) : https://git.fbits.net/stores/wake-components