Introdução: Quando o Cache Vira Inimigo
Imagine uma loja online gerando notificações de pedido duplicadas. Clientes veem cobranças a mais, estoque atualizado errado. O suporte técnico coça a cabeça. O desenvolvedor olha os logs e tudo parece normal. Esse é o fantasma que assombra sites WordPress com WooCommerce e sistemas de cache agressivo – conflito entre a API REST e o cache de página inteira.
Não estou falando de problemas óbvios, como plugins desatualizados. É um bug sutil, que só aparece sob carga, quando Varnish ou Redis armazenam respostas de endpoints que deveriam ser dinâmicos.
Como Funciona o Gatilho do Problema
O WooCommerce, desde a versão 3.0+, usa a API REST para criar pedidos, processar carrinhos e gerenciar sessões. Quando um cliente adiciona um item ao carrinho, uma requisição POST é enviada para /wp-json/wc/v3/cart/add-item. Essa requisição retorna um JSON com o estado atualizado do carrinho.
Se você usa um cache de página inteira (como WP Rocket, W3 Total Cache, Cloudflare ou Varnish), o servidor pode armazenar em cache a resposta dessa requisição para um determinado usuário. Mas aí está o truque: os cookies de sessão do WooCommerce (como woocommerce_cart_hash e woocommerce_items_in_cart) são enviados no cabeçalho da requisição. Por padrão, sistemas de cache baseados em Varnish ignoram cookies de sessão (para não quebrar o cache para visitantes anônimos), mas o WooCommerce precisa que essas respostas sejam dinâmicas.
O Cenário Crítico
Quando um usuário anônimo adiciona um item ao carrinho, a API retorna um JSON contendo o status addToCart com success: true e o novo total do carrinho. Se esse JSON for cacheado, o próximo usuário (ou o mesmo, em outra aba) receberá a mesma resposta, mesmo tendo um carrinho vazio. O resultado? O front-end mostra o carrinho de outro usuário, ou o total permanece errado.
Você pode não perceber isso em testes simples, porque muitos desenvolvedores ignoram o cache durante o desenvolvimento. Em produção, com tráfego real, o bug se manifesta de forma intermitente – o fantasma.
Debug Profundo: Como Identificar o Fantasma
Para diagnosticar, você precisa de ferramentas avançadas de monitoramento de cache: cabeçalhos X-Cache, logs de Varnish, e análise de requisições no navegador. Siga este roteiro:
- 1. Verifique os cabeçalhos da API: Em qualquer resposta da REST API (ex: ao adicionar ao carrinho), olhe para
X-Cache: HITouX-Cacheable: YES. Se aparecerHIT, o cache está ativo e potencialmente causando o problema. - 2. Teste com cabeçalho de Cookie Vary: Adicione
Vary: Cookieno servidor para endpoints do WooCommerce. No Varnish, usesub vcl_backend_response { if (bereq.url ~ "^/wp-json/wc/") { set beresp.http.Vary = "Cookie"; } }. Mas isso pode quebrar o cache para usuários anônimos (eles não têm cookie de sessão). A solução é condicionar o cache apenas quando o cookie de sessão está presente. - 3. Exclua endpoints específicos do cache: No Varnish, adicione regras como:
if (bereq.url ~ "^/wp-json/wc/v3/cart") { return (pass); }. Isso força a requisição a ir direto ao backend, sem cache. - 4. Plugins de cache podem ignorar cookies: No WP Rocket, vá em Advanced Rules e adicione
/wp-json/wc/v3/cart/*na lista de URLs para nunca cachear.
Mas cuidado: se você desabilitar o cache para toda a API, pode impactar o desempenho de outros endpoints (como produtos). A solução granulada é melhor.
Estudo de Caso Reverso: O Erro que Custou R$ 50 mil
Uma loja de móveis no sul do Brasil sofria com pedidos duplicados. Entre em pânico – o suporte do hosting dizia que era plugin. O desenvolvedor usava WooCommerce + W3 Total Cache com Varnish no servidor. O problema: o W3 Total Cache, por padrão, cacheia todas as páginas, incluindo a resposta da API de carrinho se ela passar por URL amigável (ex: /cart-ajax). Após dias de debug, descobrimos que o Varnish cacheava por 10 minutos a resposta de /wp-json/wc/v3/cart/update. Quando dois clientes acessavam simultaneamente, um recebia o carrinho do outro.
A solução: personalizamos o .htaccess para forçar Cache-Control: no-cache em todas as URLs que contêm /wp-json/wc/ e configuramos o Varnish para não cachear nenhuma requisição POST para a API. Depois disso, tudo normalizou.
Manifesto Técnico: A Nova Regra de Ouro
A partir de agora, em qualquer projeto WooCommerce com cache, siga este check-list:
- Nunca cacheie requisições POST ou PUT para a API REST.
- Para GET, defina exceções: endpoints de carrinho, finalização, contas de usuário e sessão devem ter
Cache-Control: no-cacheeVary: Cookie. - Em servidores com Varnish, adicione
return(pass)para URLs que contenham/cart,/checkout,/my-accounte/wp-json/wc/. - Use o plugin Query Monitor para depurar cabeçalhos de cache e detectar hits indevidos.
Ignorar isso é convidar o fantasma para morar na sua loja. E acredite, ele gosta de aparecer na Black Friday.
No final, a tecnologia não mente. O cache é poderoso, mas exige respeito pelas regras da aplicação. WooCommerce não é um blog; é um sistema transacional.
Fique atento, teste com vários cookies, e mantenha seus logs sempre acessíveis. O fantasma só assusta quem não sabe onde procurar.