Resolver problemas comuns na calculadora de frete

Quando algo não funciona como esperado, comece pelas verificações abaixo. Cada problema tem uma causa típica e uma solução de 1 minuto.

Máscara de CEP não formata

Sintoma: o cliente digita o CEP e ele continua sem traço, ou os dígitos saem fora de ordem.

Verificações:

1. Confirme que Máscara de campo está marcada em WooCommerce → Configurações → Entrega → Otimização da calculadora.
2. Limpe o cache do navegador (e do site, se você usa um plugin de cache como WP Rocket ou LiteSpeed).
3. Abra a página em janela anônima pra descartar cache local.
4. Confira se você não tem outro plugin de máscara ativo aplicando regra concorrente no mesmo campo.

Se você tem o TM Extra Product Options instalado, há tratamento específico no plugin — ele deveria funcionar. Se não funciona, abra um ticket no suporte com a versão do TM Extra Product Options.

Cidade não é preenchida automaticamente

Sintoma: o estado vem certo, mas a cidade fica em branco ou marcada como -.

Verificações:

1. Confirme que Identificar cidade automaticamente está marcada nas configurações.
2. Cheque se sua loja tem acesso à internet de saída (ViaCEP é uma API externa em viacep.com.br).
3. Teste o CEP do cliente diretamente em https://viacep.com.br/ — se a API não acha, o plugin também não vai achar.
4. Abra o console do navegador (F12 → aba Network) e veja se a requisição pra viacep.com.br está sendo feita e o que ela responde.

Se o ViaCEP estiver indisponível, o plugin retorna - como cidade — o frete continua sendo calculado pelo estado.

Cálculo automático não dispara

Sintoma: o cliente digita o CEP completo e o frete não calcula sozinho.

Verificações:

1. Confirme que Calcular automaticamente está marcada nas configurações.
2. Confira se o CEP digitado tem 8 dígitos válidos — abaixo disso o plugin não dispara.
3. Teste em outro navegador (ou anônimo) — extensões que bloqueiam JavaScript podem impedir o trigger.
4. Se você usa um plugin de carrinho lateral (CartFlows, Side Cart for WooCommerce etc), confirme que o campo de CEP renderizado é o nativo do WooCommerce — alguns substituem o markup e quebram o monitor.

Estado não é detectado pelo CEP

Sintoma: o cliente preenche um CEP válido, mas o cálculo retorna como se o estado estivesse em branco.

Verificações:

1. Confira que o CEP digitado é brasileiro válido (8 dígitos, dentro de uma das faixas oficiais dos Correios).
2. Teste o CEP em https://viacep.com.br/ — se não retorna estado, é um CEP fora das faixas reconhecidas.
3. Em casos raros (CEPs novos ainda não mapeados), o plugin pode não detectar — abra um ticket no suporte com o CEP exato.

Os campos País e Estado voltaram a aparecer

Sintoma: depois de uma atualização do WooCommerce ou outro plugin, País e Estado voltaram pra calculadora.

Verificações:

1. Confirme que o plugin Calculadora de Frete Otimizada ainda está ativo em Plugins → Plugins instalados.
2. Outro plugin pode estar aplicando os mesmos filtros (woocommerce_shipping_calculator_enable_*) com prioridade maior — desative plugins um a um pra identificar.
3. Tema customizado pode estar reescrevendo o template cart-shipping.php — confira em wp-content/themes/seu-tema/woocommerce/cart/.

Como pedir suporte

Se nenhum dos itens acima resolveu, abra um ticket por e-mail incluindo:

• Versão do WordPress e do WooCommerce.
• Versão do plugin (em Plugins → Plugins instalados).
• Tema usado.
• Quais opções estão ligadas em Otimização da calculadora.
• Print da tela ou link da loja onde acontece o problema.
• Um CEP de exemplo que falha.

Quanto mais detalhes, mais rápida a resposta.