Sistema completo de sincronização, recuperação e limpeza de carrinhos abandonados em ambientes VTEX IO.

Este módulo implementa:

• Persistência de sessões de carrinho no Master Data v1
• Recuperação inteligente de carrinhos anteriores em múltiplas sessões
• Sugestão de recuperação com modal na loja (Store Framework)
• Sincronização após pedido realizado para evitar itens duplicados
• Padronização de payload via Base64 (btoa/atob)
• Validação estruturada com Zod
• Compatível com Loja (Store) e Checkout (v5/v6)

---

📌 Sumário

• 🛒 Abandoned Cart Sync – VTEX IO
• 📌 Sumário
• 🎯 Objetivo
• 🧱 Arquitetura
• 🔥 Endpoints da API
  • POST /cart-sync/upsertAbandonedCart
    • Request
    • Validação
    • Comportamento
  • POST /cart-sync/getAbandonedCarts
    • Request
    • Validação
    • Comportamento
  • POST /cart-sync/setAbandonedCartCompleted
    • Request
    • Validação
    • Comportamento
• 🔐 Formato do Payload (Base64)
  • Exemplo de envio no front:
  • Decodificação no backend:
• 📏 Esquemas (Zod)
  • itemSchema
  • upsertSchema
  • getAbandonedCartsSchema
  • setAbandonedCompletedSchema
• 🔄 Fluxo funcional
  • 1. Cliente navega na loja
  • 2. Cliente volta em outra sessão
  • 3. Cliente finaliza pedido
  • 4. Backend limpa carrinhos antigos
• 🧩 Componentes React da loja
  • AbandonedCartSync
  • AbandonedCartRetriever
  • AbandonedCartSyncCleanUp
• 🔒 Considerações de segurança
• 📄 Licença

---

🎯 Objetivo

Este projeto existe para resolver um problema comum em e-commerces com múltiplas sessões:

O cliente começa um carrinho em um dispositivo e continua em outro → carrinhos ficam divergentes.

Este módulo fornece:

• Persistência confiável das sessões de carrinho
• Recuperação automática das sessões anteriores
• Sincronização pós-pedido removendo itens já comprados
• Modal reativa para sugerir a recuperação do carrinho

---

🧱 Arquitetura

---

🔥 Endpoints da API

Todos os endpoints utilizam payload Base64 via { "data": "<base64>" }.

---

Cria ou atualiza um registro de carrinho abandonado.

Headers

Body

JSON interno (antes do btoa):

• orderFormId (string): ID do orderForm da VTEX.
• email (string, email válido): e-mail do cliente.
• items (array): lista de itens do carrinho.

Cada item (AbandonedCartItem):

• skuId (string, obrigatório)
• productId (string, obrigatório)
• quantity (int > 0, obrigatório)
• sellerId (string, opcional, default "1")

No backend:

• data é decodificado: parseJSONFromAtob(body.data).
• Validado com zod via upsertSchema:
  • orderFormId: z.string().min(5)
  • email: z.string().email()
  • items: z.array(itemSchema)

Se falhar:

1. Busca um documento existente por orderFormId em AC (Master Data v1).
2. Se não existe:
   • Cria um novo documento:
     • orderFormId
     • email
     • items
     • updatedDate = agora (ISO)
     • completed = false
   • Retorna 201 com o documento criado.
3. Se já existe:
   • Atualiza:
     • email
     • items
     • updatedDate
   • Retorna 200 com { id, updatedDate }.

---

Retorna carrinhos abertos para um email, exceto o carrinho da sessão atual.

Headers

Body

JSON interno:

Response

• Decode via parseJSONFromAtob.
• Validação com getAbandonedCartsSchema (zod):
  • orderFormId: z.string().min(5)
  • email: z.string().email()

Erro:

1. Normaliza o e-mail: email.trim().
2. Define uma janela de consulta (por exemplo days = 7).
3. Chama md.searchOpenWithinDays(email, orderFormId, days):
   • completed = false
   • updatedDate entre now - days e now
   • orderFormId \<\> <orderFormId atual>
4. Retorna 200 com array de AbandonedCart:

---

Usado quando um pedido é finalizado (orderPlaced).
Remove itens dos carrinhos antigos e marca como completed quando esvaziados.

Headers

Body

JSON interno:

orderFormId pode existir no payload (opcional), mas não é obrigatório na abordagem atual.

Schema setAbandonedCompletedSchema (Zod):

Erros de parse/validação → 400:

1. Normaliza o e-mail: email.trim().

2. Monta mapa purchasedQtyBySku (quantidades compradas por SKU):

   
   

   _10

   const purchasedQtyBySku: Record<string, number> = {}

   _10

   _10

   for (const item of purchasedItems) {

   _10

   const skuKey = String(item.skuId)

   _10

   purchasedQtyBySku[skuKey] =

   _10

   (purchasedQtyBySku[skuKey] || 0) + Number(item.quantity || 0)

   _10

   }

   
   

3. Busca todos os carrinhos abertos para aquele e-mail:

   • openDocs = md.searchOpenWithinDays(email, undefined, 30)

4. Normaliza os items de cada doc (caso venham como string do Master Data):

   
   

   _15

   const mdItemsSchema = z.preprocess((value) => {

   _15

   if (typeof value === 'string') {

   _15

   try {

   _15

   return JSON.parse(value)

   _15

   } catch {

   _15

   return []

   _15

   }

   _15

   }

   _15

   return value

   _15

   }, itemsSchema)

   _15

   _15

   openDocs = openDocs.map(openDoc => ({

   _15

   ...openDoc,

   _15

   items: mdItemsSchema.parse(openDoc.items || []),

   _15

   }))

   
   

5. Para cada doc:

   • Itera sobre originalItems.
   • Se sku não foi comprado → item permanece.
   • Se quantity comprada for maior/igual → remove item.
   • Se for menor → reduz quantity no carrinho.
   • Se não sobra nenhum item → completed = true.
   • Se sobra algo → atualiza items com a nova lista.

6. Resposta:

---

🔐 Formato do Payload (Base64)

Todos os endpoints devem receber:

Motivos:

• Evitar logs legíveis de dados sensíveis
• Padronizar entrada
• Evitar erros quando o payload contém caracteres especiais

---

📏 Esquemas (Zod)

---

🔄 Fluxo funcional

O componente AbandonedCartSync roda na loja inteira (exceto checkout) e:

• observa mudanças no orderForm (useOrderForm)
• envia orderFormId, email, items → /cart-sync/upsertAbandonedCart

O componente AbandonedCartRetriever:

• consulta /cart-sync/getAbandonedCarts
• compara items antigos vs carrinho atual
• busca detalhes no catálogo (/api/catalog_system/pub/products/search)
• mostra uma modal com cards de produtos para recuperação
• adiciona os itens ao carrinho via addItems do vtex.order-manager

Na página de orderPlaced:

• o componente AbandonedCartSyncCleanUp:
  • coleta email e items do pedido (via vtex.order-placed)
  • envia payload → /cart-sync/setAbandonedCartCompleted

• Remove quantidades compradas dos carrinhos abertos do mesmo email
• Se um carrinho ficar sem itens → completed = true
• Se ainda sobraram itens → carrinho permanece aberto, com items ajustados

---

🧩 Componentes React da loja

• Executado na loja (Store Framework), exceto em rotas de checkout:
  • Detecta rota via useRuntime + fallback em window.location.
• Usa useOrderForm para obter:
  • orderFormId
  • email
  • items
  • salesChannel
• Envia updates para /cart-sync/upsertAbandonedCart.

• Executado na loja.
• Usa useOrderForm:
  • Pega carrinho atual
  • Busca carrinhos antigos via /cart-sync/getAbandonedCarts
  • Exibe modal com:
    • imagem do produto
    • preço de/por
    • quantidade
• Ao clicar em “Sim, adicionar”:
  • Usa addItems do vtex.order-manager para adicionar ao carrinho atual.
• Ao clicar em “Não, obrigado”:
  • Marca recusa em sessionStorage para não exibir novamente na mesma sessão.

• Executado apenas na página orderPlaced (store.orderplaced).
• Usa OrderGroupContext de vtex.order-placed:
  • obtém orders do grupo
  • extrai email e items
• Envia payload para /cart-sync/setAbandonedCartCompleted.

---

🔒 Considerações de segurança

• Base64 não é criptografia, mas:
  • reduz risco de log de dados sensíveis em texto puro.
  • evita problemas com caracteres especiais em logs/transporte.
• email e itens são validados com Zod:
  • garante tipos corretos
  • evita payload malformado
• Itens provenientes do Master Data:
  • podem vir como string (JSON serializado) ou como array.
  • são sempre normalizados e validados com Zod antes de uso.

---

📄 Licença

MIT — Sinta-se livre para adaptar, expandir ou reutilizar este módulo em outros projetos VTEX IO.