Univer Checkout

#Visão geral

O Univer Checkout substitui o checkout padrão do WooCommerce por uma experiência otimizada pra conversão no mercado brasileiro. Foi construído pra ser ultra-leve, single-page e plug-and-play: você instala, configura SMTP e gateway, e o resto funciona.

Diferente de page builders que tentam fazer tudo, o Univer é opinionado: a UX foi desenhada pra reduzir atrito do cliente brasileiro (CPF, CEP, parcelamento, OTP por WhatsApp) e tudo que distrai foi removido.

#Instalação

1. 1Faça upload do plugin
   Suba a pasta univer-checkout pra /wp-content/plugins/ via FTP, ou instale o ZIP em Plugins → Adicionar → Enviar plugin.
2. 2Ative
   Em Plugins, clique em "Ativar" no card do Univer Checkout. As tabelas auxiliares são criadas automaticamente.
3. 3Configure
   Vá em Univer Checkout no menu admin e revise: tema, cores, SMTP, OTP, gateway.
4. 4Teste em uma compra real
   Faça um pedido com valor baixo pra validar o fluxo end-to-end, especialmente a primeira parcela e o magic-link de email.

#Requisitos

#Plugins a remover

O Univer Checkout substitui completamente o checkout do Woo. Pra evitar conflitos, desative ou remova:

• Plugins de campos do checkout — Checkout Field Editor, WC Checkout Manager
• Auto-completar de endereço de terceiros — já incluído via API ViaCEP
• SMTP plugins (WP Mail SMTP, Easy SMTP) — desnecessário, temos SMTP nativo
• PIX manual com QR estático — temos PIX dinâmico via Mercado Pago

#Single-page em 2 etapas

O fluxo foi desenhado pra reduzir atrito ao mínimo. O cliente vê uma página dividida em 2 passos curtos:

1. 1Identificação
   O cliente informa email ou CPF. Se já houver conta, o sistema oferece login passwordless (WhatsApp ou magic-link, dependendo se ele tem telefone cadastrado). Se for novo, segue cadastro inline. Sem senha.
2. 2Endereço + Pagamento
   CEP auto-completa endereço (via ViaCEP). Cliente escolhe forma de pagamento (cartão, PIX, boleto), preenche o necessário e confirma. Tudo na mesma página, sem refresh.

#Login InteligenteBR · PRO

O cliente nunca precisa criar senha. O Univer Checkout reconhece se o email já está cadastrado e oferece duas formas de autenticação passwordless:

OTP via WhatsApp

Um código de 6 dígitos é enviado via WhatsApp pelo seu próprio número (via WAHA + Cloudflare Worker). Validade configurável (default 5 min). Funciona melhor pro Brasil — taxa de entrega superior a SMS.

Magic-link por email

Link único enviado por email. Cliente clica e entra. Útil pra quem não responde no WhatsApp ou tem segundo número.

Settings de auth

#Pagamento

Cartão, PIX e boleto via integração nativa com o Mercado Pago oficial. PIX dinâmico (QR e copy-paste), boleto com pré-data automática. Tudo cobrado direto na conta do lojista. Detection de gateway de cartão é via slug (mercado + custom/credit) — extensível pelo filter univer_checkout_is_card_gateway.

#Parcelamento

Configure como o lojista cobra parcelamento BR direto nas settings. As regras são respeitadas em todo lugar — checkout, página de upsell e save-card.

#Frete

Consome os métodos de envio nativos do WooCommerce e renderiza com presets visuais: prazo, valor e label "Médio/Máximo".

#Temas3 temas

Três temas visuais embutidos. Cada um troca apenas tokens CSS — o app JS é o mesmo. Você muda em 1 click sem perder configuração.

Settings de aparência

Override de cor primária — exemplo

Override opcional preserva o tema. Útil pra adequar à identidade visual da loja sem trocar o tema inteiro.

// Settings → Aparência
theme_color_primary:      "#7C3AED"  // botões / accents
theme_color_primary_dark: "#5B21B6"  // hover

#Header customizável

O topo do checkout é totalmente configurável: cor de fundo, logo, subtítulo, padding e tamanho da logo.

#Trust badges & bullets

Bullets aparecem abaixo do checkout pra reforçar credibilidade. Os defaults vêm prontos:

• Produto em estoque, envio rápido
• Compra 100% segura e criptografada
• Suporte humano por WhatsApp

Trust badges (Site Blindado, Reclame Aqui, Visa Verified) podem ser inseridos via array trust_badges com URL da imagem e link.

#Página de obrigado

Após o pagamento, o plugin sobrescreve completamente o template order-receiveddo WC (e do tema) com um bundle Preact próprio. Isso evita os blocos parasitas dos temas ("Comprar de novo" do Woodmart, "custo do parcelamento", etc) e garante visual coeso com o checkout. O theme escolhido (light/black/glass) é estendido automaticamente pra cá.

O cliente acessa via order_key na URL — mesmo modelo de auth que o WC usa pra guest checkouts, então não precisa estar logado. É também onde o upsell 1-clique aparece.

#Tracking analíticoPRO

Toda sessão de checkout é instrumentada — sem cookies de terceiros, sem GA. Os dados ficam no seu próprio banco, em tabelas dedicadas.

#Recuperação de carrinho

Sessão sem conclusão é marcada como abandoned após N minutos (default 30) por um cron próprio do plugin. A partir daí, a sessão fica disponível na tabela univer_sessions com todos os dados do cliente — email, telefone, carrinho, UTMs — pra você integrar com o seu canal de recuperação.

Como disparar lembretes

O plugin não envia emails de recuperação automaticamente — ele expõe os dados pro seu CRM/email tool de preferência (Brevo, ActiveCampaign, RD Station, FluentCRM, Univer Loyalty etc). Cenário típico:

1. 1Plugin marca sessão como abandonada
   Cron univer_checkout_abandonment_scan roda e atualiza status = abandoned nas sessões inativas há mais de N minutos.
2. 2Você consome a tabela univer_sessions
   Via SQL direto, REST custom ou hook do seu CRM. Os campos relevantes: email, phone, cart_total, utm_*, last_step.
3. 3Dispara o lembrete
   Email transacional (SMTP nativo do próprio plugin já serve), WhatsApp via WAHA, ou via integração nativa com Univer Loyalty / Univer Tracker.

#Upsell pós-compra 1-cliquePRO

Depois do pagamento aprovado, oferece um produto extra na página de obrigado. Cliente clica em "Quero também" e o cartão salvo é cobrado sem redigitar nada.

1. 1Save-card opt-in
   No checkout original, o cliente concorda em salvar o cartão (token Mercado Pago).
2. 2Thankyou injector
   Página de obrigado mostra a oferta de upsell.
3. 31-clique → Mercado Pago
   Backend chama API do MP com token salvo + idempotency-key. Pedido criado em < 800ms.
4. 4Cart price override
   Se o produto tem preço diferenciado pro upsell, sobrescreve no carrinho.

Modos:

• auto — sistema escolhe melhor produto baseado no carrinho do pedido principal (default)
• fixed — produto único definido nas settings
• off — desabilita upsell na página

#Cupom via URL

Aplica cupom automaticamente quando o cliente chega via link com o parâmetro ?coupon=:

// Exemplo: BLACKFRIDAY aplicado automaticamente
https://sualoja.com.br/checkout/?coupon=BLACKFRIDAY

Funciona com qualquer cupom criado em WooCommerce → Cupons. Se inválido/expirado, é ignorado silenciosamente.

#Pontos / Loyalty

Sistema de pontos opcional integrado ao checkout. Mostra "Você ganhará X pontos nesta compra!" abaixo do total e grava pontos na finalização.

#Mercado Pago

Integração nativa com o plugin oficial woocommerce-mercadopago. Necessário pra save-card, upsell 1-clique e parcelamento BR completo. PIX e boleto funcionam pelo gateway nativo do MP.

#SMTP nativo

Envio de emails (magic-link, recibo, recuperação) sem depender de plugins extras tipo WP Mail SMTP. Configure direto nas settings:

#WhatsApp / WAHA

Pra OTP via WhatsApp, configure um Cloudflare Worker próprio que se conecta na sua WAHA (WhatsApp HTTP API). Isso permite envio do seu número oficial sem custos de SMS BR.

1. 1Suba a WAHA
   Em servidor próprio (Docker recomendado) ou serviço cloud. Configure session com seu número.
2. 2Deploy Cloudflare Worker
   Use o template fornecido na doc do projeto. Define o segredo HMAC compartilhado.
3. 3Configure plugin
   Cole a URL do Worker, o segredo HMAC, a URL da WAHA e o nome da session.

#Wallet / SaldoBONUS

Feature opcional que permite o cliente usar saldo de carteira (store credit) no checkout. Auto-detecta os providers compatíveis na ativação:

• UniverWallet — nosso plugin nativo
• Wallet for WooCommerce (Flintop)
• TeraWallet
• WPS Wallet
• Custom — registre via filter univer_checkout_wallet_balance

Se nenhum provider estiver presente, a feature desativa graciosamente — sem erro, sem UI quebrada. Se você quiser desligar mesmo com provider presente (ex: durante uma campanha), use a setting:

#Licenciamento

Sistema de licença com 3 camadas de gate independentes — defesa em profundidade, nenhuma é suficiente sozinha.

1. 1Frontend template (priority 98)
   Antes do checkout renderizar, um template_include filter intercepta e mostra a tela de bloqueio se a licença estiver inativa. Mais cedo que qualquer outro plugin no pipeline.
2. 2REST gate (rest_pre_dispatch)
   Todas as rotas /wp-json/univer/v1/* retornam 503 quando a licença está bloqueada, exceto as rotas /license/* e /cep/* (pra você conseguir reativar).
3. 3Admin banner
   admin_notices mostra estado da licença em todas as telas do wp-admin com link direto pra reativação.

Verificação criptográfica

Tokens são assinados com Ed25519 (libsodium) e re-verificados a cada read — qualquer tentativa de adulterar o option no DB invalida o token. Domain-binding: o token traz o host de issuance e é rejeitado se mudou.

Heartbeat e grace period

Cron diário chama o licensing server pra revalidar. Se o servidor estiver inalcançável, o site continua funcionando por 7 dias (grace period) com base no último signed_token válido. Após esse prazo, o gate ativa.

#Persistência de settings

Settings ficam em wp_options.univer_checkout_settings. Em cada read, defaults são mergeados atrás dos valores salvos (nunca sobrescrevem). Em cada save, só as keys explícitas são tocadas.

#Developer hooks

O Univer Checkout expõe hooks (filters e actions) pra extensão sem precisar fork. Todos seguem o prefixo univer_checkout_*. Use no functions.php do tema ou em um plugin filho.

Filters — comportamento

Actions — eventos

Crons agendados

Tabelas no banco

Prefixo {wp_prefix}_univer_. Todas têm índices estratégicos pra queries de funil e timeline.

REST API

Todos os endpoints ficam sob o namespace /wp-json/univer/v1/. As rotas administrativas exigem capability manage_woocommerce; rotas públicas são protegidas por nonce + rate-limit.

• POST /checkout/bootstrap · /coupon · /shipping · /submit · /wallet — fluxo do checkout
• POST /auth/instant-login · /verify · /recover — passwordless
• POST /events — ingest de eventos (32KB / 50 events por batch)
• GET /analytics/* — KPIs, funnel, timings, field-stats, sessions (admin only)
• GET /upsell/offers/{order_id} · POST /upsell/accept — fluxo de upsell 1-clique
• POST /license/{state|activate|sync|deactivate} — gerência de licença
• POST /cep/lookup — proxy ViaCEP

#LGPD / Uninstall

Quando você desinstala o plugin pelo wp-admin, o uninstall.php é LGPD-aware:

• Drop de todas as tabelas univer_* (sessions, events, step_timings, field_stats, upsell_rules, saved_cards, upsell_events, otp_codes legacy)
• Delete de todas as options: univer_checkout_settings, _settings_backup, _settings_version, _db_version, _hash_salt
• Cancela crons agendados (univer_checkout_abandonment_scan + _retention_sweep)
• Limpa transients _transient_univer_*, locks univer_lock_* e idempotency keys univer_idem_*
• Remove user_meta com prefix _univer_ (não toca em billing_* do Woo, esse é histórico do lojista)
• Remove order_meta com prefix _univer_ em ambos os modelos: HPOS e legacy posts

Após desinstalar, nada do plugin permanece no banco. Zero footprint.

#Problemas comuns

Checkout não aparece

Verifique se o WooCommerce está ativo. Em WooCommerce → Status, confirme que a página de Checkout está mapeada e que não há erro de banco. Se persistir, ative WP_DEBUG e cheque wp-content/debug.log.

Magic-link cai em spam

Configure SMTP nativo e use SPF/DKIM no DNS. Sem SMTP, o WordPress usa mail() que é flagged por gmail/outlook.

OTP não chega

Cheque o log do Cloudflare Worker, status da WAHA e formato do número (BR usa 9 dígitos no celular). O plugin tem resolver automático que tenta com e sem o 9.

Save-card falha em produção

Save-card requer Mercado Pago em modo produção (não sandbox) e plugin oficial atualizado. Verifique SANDBOX_MODE nas configurações do MP.

Settings sumiram após update

Não acontece — o framework de persistência preserva tudo. Se você ver default em algum campo, é porque essa key foi adicionada em uma migration nova. Confira o backup em univer_checkout_settings_backup.

#FAQ

Funciona com gateway que não seja Mercado Pago?

O fluxo básico (PIX, boleto) funciona com qualquer gateway. As features avançadas (save-card, upsell 1-clique, parcelamento BR completo) só funcionam com o Mercado Pago oficial.

Suporta HPOS?

Sim. custom_order_tables declarado como compatível. Cart/Checkout Blocks são incompatíveis intencionalmente — usamos nosso próprio template otimizado.

Posso desativar o upsell?

Sim. Em Univer Checkout → Recursos, mude upsell_mode pra off.

Tem versão multilíngue?

Versão atual é PT-BR. Strings traduzíveis via load_plugin_textdomain. Roadmap inclui ES-AR/MX e EN-US.

Funciona com cache (WP Rocket, LiteSpeed)?

Sim, mas a página de checkout (e a thank-you) precisam estar na exclude list do seu plugin de cache. O Univer Checkout é uma SPA stateful — cachear o HTML quebra o bootstrap. Configure exclusão dos paths /checkout/* e /order-received/* no WP Rocket / LiteSpeed / Cloudflare Page Rules.

#Changelog

2.3.0 atual

• 3 temas embutidos (Light, Black, Glass)
• Override opcional da cor primária por tema (theme_color_primary + theme_color_primary_dark)
• Admin session exclusion — sessões iniciadas por admins logados ou IPs em admin_ips são ignoradas no tracking. Suporta CIDR IPv4/IPv6 (ex: 10.0.0.0/8). Mantém o funil limpo durante testes internos.
• Backup automático de settings antes de qualquer migration (univer_checkout_settings_backup)

2.1.0

• Hardening pra venda comercial / plug-and-play
• Wallet multi-provider auto-detect
• Settings persistence framework formal
• DoS hardening em magic-link + /events
• uninstall.php LGPD-aware (zero footprint)
• Lazy loading por contexto
• MP API com retry exponencial

2.0.5

• OTP fix: REQUEST_TIMEOUT 0.5s → 5s

2.0.4

• Smart phone resolver no Worker (BR 9-vs-no-9)

2.0.3

• User_Guard: bloqueia magic-link/OTP pra roles privilegiadas

2.0.2

• SMTP nativo, OTP via Cloudflare Worker, magic-link via ULAU

2.0.0

• Upsell pós-compra 1-clique com Mercado Pago save-card
• Tracking analítico completo (sessions, events, timings, fields, UTM)