UniverCart

#Visão geral

O UniverCart substitui o carrinho padrão do WooCommerce por um side cart premium e adiciona ferramentas de venda B2B e recuperação que normalmente custariam 5 plugins separados (Caddy + Cart Lift + WP Loyalty + funil de carrinho + WhatsApp blast).

Foi construído pra ser plug-and-play: você instala, ativa e o carrinho aparece automaticamente — em qualquer tema. Diferente de soluções genéricas, ele é opinionado pra mercado brasileiro: integração ZapGrup, URLs em PT-BR, brindes por nível e disparo em massa.

#Instalação

1. 1Faça upload do plugin
   Suba o ZIP em Plugins → Adicionar → Enviar plugin, ou descompacte em /wp-content/plugins/univercart/ via FTP.
2. 2Ative
   Em Plugins, clique em "Ativar" no card do UniverCart. As tabelas auxiliares são criadas automaticamente (cart tracking, recovery links, save for later, dispatches, templates).
3. 3Configure
   Vá em UniverCart → Configurações e revise: aparência, frete grátis, recompensas, recomendações.
4. 4Teste em uma loja vazia
   Adicione um produto pelo frontend e verifique que o painel lateral abre. Se não abrir, confira se outro plugin de carrinho está conflitando.

#Requisitos

#Painel lateral

O side cart é injetado automaticamente no body do site — funciona com qualquer tema. Ao clicar no carrinho ou adicionar um produto, o painel desliza da direita.

Comportamento

Shortcode

Use [univercart_cart_icon] em menu, header ou footer do tema. Atributos:

[univercart_cart_icon label="meu carrinho" size="64" bg="#000" color="#fff"]

#Aparência

Controle total das cores, geometria e ícone do side cart sem editar CSS.

#Frete grátis · meter

Barra de progresso visível no topo do carrinho com a meta restante para frete grátis. Auto-detecta a regra do WooCommerce ou aceita meta manual.

#Recompensas progressivas★

Configure níveis ilimitados de recompensa por valor de carrinho. Cada nível pode ser free_shipping, discount ou gift. O cliente vê o progresso visual no carrinho e cada brinde é adicionado automaticamente quando o threshold é atingido.

Tipos de recompensa

Estrutura de cada tier

[
  {
    "enabled":       "yes",
    "threshold":     199,
    "type":          "free_shipping",
    "value":         "",
    "text":          "Frete grátis",
    "show_in_meter": "yes"
  },
  {
    "enabled":       "yes",
    "threshold":     299,
    "type":          "gift",
    "value":         "13891",      // ID do produto
    "text":          "Máscara de presente",
    "show_in_meter": "yes"
  }
]

#Barra de anúncio

Mensagem persistente no topo do painel — útil pra promoções, prazos ou avisos. Aceita variáveis dinâmicas:

• {cart_total} — total formatado
• {cart_count} — número de itens
• {first_name} — primeiro nome do cliente logado
• {free_shipping_remaining} — falta R$ X pra frete grátis

#Salvar para depois

Wishlist persistente integrada ao side cart. Aba dedicada com produtos salvos. Visitantes não logados também podem usar (via cookie de sessão).

Migração ao login

Quando um visitante faz login, os itens salvos por cookie são migrados automaticamente pra conta dele via hook wp_login.

#Recomendações

Bloco de produtos recomendados exibido dentro do side cart. 3 fontes possíveis:

• Upsells — produtos vinculados manualmente como upsell no admin do produto
• Cross-sells — vinculados como cross-sell
• Related — auto-detect via categoria/tag (fallback)
• Bestsellers — fallback final por total_sales

#Aba de ofertas

Cupons disponíveis com aplicação em 1 clique direto do carrinho — sem o cliente ter que descobrir/digitar o código.

#Montador de CarrinhoPRO

Painel admin onde o time comercial monta carrinhos personalizados pra clientes B2B. Funcionalidade exclusiva — não existe em nenhum outro plugin do mercado.

Fluxo

1. 1Buscar produtos
   Busca AI por nome, SKU ou ID. Filtros por categoria, preço, estoque. Suporte a variações.
2. 2Customizar
   Override de preço por item, ajuste de quantidade, aplicação de cupons, frete customizado.
3. 3Gerar link
   Slug bonito (kit-vip-joana) ou token hash. Validade configurável.
4. 4Acompanhar
   Visitas, conversão e receita atribuída no dashboard.

#Busca AI de produtos

Endpoint REST GET /univercart/v1/builder/search-products retorna payload compacto otimizado pra LLMs e UI.

Campos suportados

#Override de preço

Cada item no Montador aceita custom_price ou discount_pct. O preço efetivo é calculado e gravado como meta _uc_custom_price no cart_item_data.

Regras de segurança

• Preço zero ou negativo é recusado — produto pago nunca vira free por essa rota
• 100% de desconto vira centavo simbólico (R$ 0,01) — força produto a aparecer como pago
• Se o admin quer realmente brinde, usa o sistema de Recompensas

#Frete customizado

Cada link gerado pelo Montador pode sobrescrever a regra de frete via shipping_override.

Modos

• free — frete grátis sobrescreve qualquer método
• fixed — valor fixo (ex: R$ 19,90)
• discount — % de desconto sobre o frete calculado

{
  "enabled":      true,
  "display_name": "Frete promocional",
  "mode":         "fixed",
  "fixed_value":  19.90
}

Persiste em WC()->session->set('uc_shipping_override', $override) e atua via filter woocommerce_package_rates.

#Carrinho salvo (URL)

Quando o admin marca is_saved=1 no Montador, o carrinho fica reutilizável pra sempre (ou até admin deletar). Ganha um slug bonito que vira a URL do checkout.

POST /univercart/v1/builder/save-cart

{
  "name":  "Kit VIP Joana",
  "slug":  "kit-vip-joana",  // opcional, gerado de name se vazio
  "items": [{"product_id": 123, "quantity": 2, "custom_price": 99.00}],
  "coupons": ["VIP10"],
  "shipping_override": { "enabled": true, "mode": "free", "display_name": "Frete VIP" }
}

→ link: https://lizzon.com.br/pedido/kit-vip-joana

#Recovery links

Cada carrinho gerado (Montador, Disparar Carrinhos, ou via API) cria um registro em wp_uc_recovery_links com token hash + dados do carrinho. URL no formato /uc-recover/{token} ou /pedido/{slug}.

Fluxo de resolução

1. 1Cliente abre o link
   Rewrite rule do WP captura o token/slug e dispara template_redirect.
2. 2Validação criptográfica
   Token URL é hashed (SHA-256 com salt do site) e comparado com o storage. Slug é look-up direto.
3. 3Reconstrução do carrinho
   WC()->cart->empty_cart() + add_to_cart() pra cada item, com _uc_custom_price aplicado.
4. 4Aplicação de cupons + override
   Cupons inválidos são silenciosamente dropados (admin já validou ao gerar). Shipping override persistido na sessão.
5. 5Redirect para checkout
   Cliente já vê totais finais. uc_recovery_link_id persistido na sessão pra atribuição de conversão.

#Tracking & analytics

Toda sessão de carrinho é instrumentada na tabela wp_uc_cart_tracking + wp_uc_cart_items. Sem cookies de terceiros, sem GA — dados ficam no seu banco.

Endpoints

• GET /wc-data/stats?period=30d — KPIs de pedidos com paginação 500/batch (sem OOM em loja grande)
• GET /cart-tracking?status=abandoned — listagem paginada
• GET /analytics/top-products — top SKUs por status e janela

#Cupom via URL

Aplica cupom automaticamente ao chegar via link com parâmetro ?coupon=:

https://sualoja.com.br/?coupon=BLACKFRIDAY

Funciona com qualquer cupom criado em WooCommerce → Cupons. Inválido/expirado é ignorado silenciosamente — sem notice de erro pro cliente.

#Disparar CarrinhosULTRA

Recuperação em massa de carrinhos abandonados via WhatsApp. Você seleciona até 1.000 carrinhos, escolhe um template, e dispara — cada cliente recebe a mensagem com link único.

Fluxo

1. 1Selecionar carrinhos
   Filtros por status (abandoned, active), período, valor mínimo, ticket médio.
2. 2Escolher template
   Mensagem com variáveis dinâmicas. Preview ao vivo do payload renderizado.
3. 3Configurar disparo
   Sessão WhatsApp, rate limit (balanced/aggressive/safe), modo dry-run.
4. 4Acompanhar
   Status em tempo real via GET /dispatch/{id}/sync com polling 3s.

#Templates de mensagem

Templates editáveis com variáveis dinâmicas. Cada template tem nome, canal (whatsapp), corpo e preview ao vivo.

Variáveis suportadas

• {nome} · primeiro nome do cliente
• {total} · valor formatado (R$ 1.234,56)
• {qtd_itens} · número de itens no carrinho
• {primeiro_item} · nome do primeiro produto
• {link_carrinho} · URL única de recuperação
• {email} · email do cliente

Oi *{nome}* 👋

Notei que você deixou um carrinho de {total} aqui na loja.

Reservei pra você por mais 24h:
{link_carrinho}

Qualquer dúvida, é só responder. 🤝

Endpoints CRUD

• GET /dispatch/templates
• POST /dispatch/templates
• PUT /dispatch/templates/{id}
• DELETE /dispatch/templates/{id}
• POST /dispatch/templates/preview — render com sample data

#Integração ZapGrup

O Disparar Carrinhos delega o envio efetivo para a sua instância ZapGrup. O plugin nunca envia direto — só prepara o payload.

Payload enviado ao ZapGrup

POST {zapgrup_url}/api/dispatch/cart-blast
Headers:
  Content-Type: application/json
  X-ZapGrup-Key: {api_key}

Body:
{
  "source":           "univercart",
  "dispatch_id":      42,
  "channel":          "whatsapp",
  "session_id":       "session-1",
  "rate_limit_mode":  "balanced",
  "items":            [...],
  "callback_url":     "https://sualoja/wp-json/univercart/v1/dispatch/callback"
}

#Rate limit & status

Três modos de envio configuráveis via parâmetro rate_limit_mode no payload do disparo:

Status em tempo real

O ZapGrup chama de volta em POST /dispatch/callback a cada evento (sent, failed, delivered). O plugin reconcilia o estado em wp_uc_dispatch_items. UI faz polling de 3s em GET /dispatch/{id}/sync.

#Configurações

SPA dedicada em UniverCart → Configurações. 11 abas: Geral, Exibição, Aparência, Recompensas, Recomendações, Ofertas, Salvar pra Depois, Anúncio, Avançado, Disparos, Ferramentas.

Persistência

Aba de Ferramentas

• Limpar carrinhos antigos — Marca abandonados + remove fora da janela de retenção
• Limpar cache — Apaga transients uc_* e univercart_*
• Resetar todos os dados — Backup automático + truncate em todas as tabelas. Requer confirmação digitada.

#REST API

Namespace /wp-json/univercart/v1/. Todas as rotas administrativas exigem manage_woocommerce; rotas públicas requerem nonce.

Carrinho & checkout

• GET /side-cart/cart-data — payload do side cart
• POST /cart/mutate — add / remove / update item
• POST /clear-cart — limpar carrinho do cliente
• GET /saved-items · POST /saved-items · DELETE /saved-items/{id}

Builder

• POST /builder/preview — validar items antes de criar link
• POST /builder/create-link — link descartável
• POST /builder/save-cart — carrinho salvo com slug
• GET /builder/saved-carts · PUT /builder/saved-carts/{id} · DELETE …
• GET /builder/check-slug?slug=…
• GET /builder/search-products?q=… — busca AI

Tracking & dispatch

• GET /cart-tracking — listagem paginada com filtros
• POST /dispatch/send — disparar em massa
• GET /dispatch/{id}/sync — polling de status
• POST /dispatch/callback — webhook ZapGrup (auth via X-ZapGrup-Key)

Sistema

• GET /settings · POST /settings
• POST /tools/purge-old · POST /tools/clear-cache
• GET /wc-data/stats?period=30d

#Developer hooks

Filters e actions seguindo o padrão univercart_*. Use no functions.php do tema ou em plugin filho.

Filters

Actions

Tabelas no banco

#Licenciamento

Sistema de licença com Cloudflare Worker (Univer License Server). Tokens assinados Ed25519, domain-binding, grace period de 7 dias.

Verificação

O plugin chama o endpoint POST /v1/license/activate na primeira ativação e POST /v1/license/heartbeat diariamente. Recebe um signed_token com Ed25519 que é validado a cada read — qualquer adulteração no DB invalida.

#LGPD / Uninstall

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

• Drop de todas as tabelas uc_* + tabelas de backup uc_bk_*
• Delete de todas as options: univercart_settings, univercart_db_version, univercart_last_version, univercart_zapgrup_url, univercart_zapgrup_api_key, univercart_reset_audit
• Cancela cron univercart_cleanup
• Limpa transients univercart_* e uc_*
• Remove capability manage_univercart de administrator e shop_manager

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

#Problemas comuns

Side cart não abre

Verifique se o WooCommerce está ativo. Cheque se há outro plugin de side cart conflitando (Caddy, Cart Lift, FunnelKit). Em Ferramentas → Site Health, confirme que JS está sendo enqueueado.

Recovery link redireciona pro carrinho vazio

Indica que todos os items do link estão com estoque zerado ou foram despublicados. Veja a notice no carrinho e considere editar os items do link.

Disparar Carrinhos retorna 502

Confira zapgrup_url e zapgrup_api_key em Configurações → Disparos. Teste o endpoint {zapgrup_url}/api/dispatch/sessions manualmente com cURL.

Brinde não é adicionado

Cheque: (a) rewards_enabled = yes; (b) tier com enabled = yes e threshold ≤ subtotal; (c) produto do brinde tem estoque (se managing_stock); (d) produto não é variável-pai (use uma variação específica).

Settings não salvam

O sanitiser é per-key estrito desde 2.2.3. Se algo não salva, abra DevTools e cheque o payload do POST /settings — chaves precisam estar presentes pra serem gravadas.

#FAQ

Funciona com gateway que não seja Mercado Pago?

Sim. UniverCart é agnóstico de gateway — ele só monta o carrinho. O pagamento usa o que você já tem configurado no Woo.

Suporta HPOS?

Sim. custom_order_tables declarado como compatível. Cart Blocks também são suportados.

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áginas do checkout/recovery devem estar na exclude list; (b) o JS do side cart precisa ser servido fresh (não combinar/minify agressivo). UniverCart já adiciona cache-busting por versão.

Posso desativar o Disparar Carrinhos?

Sim. É uma feature exclusiva do plano Ultra. Em planos menores ela simplesmente não aparece no menu.

#Changelog

2.2.4 atual

• Cupom movido pra fora do scroll do body — sem gap visual
• Settings: SPA full UI com 11 abas + toggles, color picker, tier rows
• Settings: sanitiser per-key estrito (PATCH semantics)
• Settings: tabs verticais à esquerda, save bar pill flutuante

2.2.0

• Migração completa de Settings para SPA (fim do options.php)
• SettingsController REST + 3 ferramentas de manutenção

2.1.0

• Hardening pra venda comercial — 49 bugs corrigidos
• Sanitization REST endpoints (CSRF + nonce)
• Recovery flow com notice/redirect em vez de checkout vazio
• HPOS hook bootstrap fix
• Reset destrutivo com backup + audit log

2.0.0

• Disparar Carrinhos via ZapGrup
• Montador B2B com URL custom
• Override de preço por item
• Recompensas progressivas (níveis ilimitados)