DiscordStatus
Guias / Guides

Erros comuns

Principais problemas que você pode encontrar no plugin de WooCommerce e como resolvê-los.

Use esta página para diagnosticar falhas no checkout, na criação de cobranças, em assinaturas e na sincronização por Webhooks.

Comece sempre pelo Log de Depuração do Plugin Asaas. Ele registra a resposta recebida da API e ajuda a identificar a causa antes de alterar configurações.

Habilite o Log de Depuração

Acesse:

WooCommerce > Configurações > Pagamentos

Selecione uma forma de pagamento do Asaas e habilite Habilitar Log na seção Log de Depuração.

Salve as alterações e reproduza o problema.

Depois, acesse:

WooCommerce > Status > Logs

Os logs do Plugin Asaas possuem o prefixo asaas seguido da forma de pagamento:

  • credit-card: Cartão de Crédito;
  • ticket: Boleto Bancário;
  • pix: Pix.

Abra o registro mais recente relacionado ao erro.

Falhas na comunicação com a API podem apresentar uma entrada EMERGENCY acompanhada do código retornado pelo Asaas.

Use o código e a mensagem encontrados no log para seguir o diagnóstico abaixo.

Problemas no WooCommerce

O plugin parou de funcionar após uma atualização

📘

Utilizar versões antigas não é recomendado

Sempre recomendamos utilizar a versão mais recente do Plugin Asaas. Caso enfrente algum problema após uma atualização, entre em contato com nosso suporte antes de realizar um downgrade.

Antes de fazer downgrade:

  1. confirme se WordPress, WooCommerce e as dependências do plugin estão atualizados;
  2. consulte o Log de Depuração;
  3. reproduza o problema na versão mais recente;
  4. procure incompatibilidades com outros plugins.

Se o downgrade for necessário para diagnóstico, acesse a página do Plugin Asaas no WordPress, clique em Panorama avançado e utilize a área de versões anteriores.

Erro "Ocorreu um erro ao processar seu pedido. Contate-nos."

Esse erro normalmente indica uma falha durante a criação da cobrança.

Depois de reproduzir o problema, consulte o Log de Depuração e localize a entrada EMERGENCY.

Use o código HTTP e a mensagem retornados para identificar a causa.

Erro "Não há métodos de pagamento disponíveis"

Esse cenário pode ocorrer quando a página de checkout utiliza a estrutura de blocos do WooCommerce e a versão ou configuração utilizada não é compatível com o Plugin Asaas.

Como alternativa, configure a página de checkout com o modelo clássico utilizando:

[woocommerce_checkout]

Depois da alteração, realize uma nova compra de teste.

Erro 401

HTTP 401 indica que a API Key não foi enviada corretamente ou não é válida.

Verifique:

  • se a API Key está ativa;
  • se foi copiada integralmente;
  • se a chave pertence ao ambiente selecionado;
  • se Sandbox e Produção não foram combinados na mesma configuração.

Após corrigir a credencial, salve e crie um novo pedido.

Se necessário, revise Configurações iniciais.

Erro 403

HTTP 403 indica que a requisição não foi autorizada.

No fluxo da API, uma das causas possíveis é o país de origem do IP utilizado pelo servidor. Também podem existir restrições de segurança configuradas para a conta.

Confira a origem das requisições e as restrições aplicadas antes de realizar um novo teste.

Erro 404 após trocar de conta ou ambiente

Esse cenário pode ocorrer quando a mesma instalação do WooCommerce é utilizada com contas Asaas diferentes ou após uma mudança entre Sandbox e Produção.

O plugin pode manter no WordPress o identificador do cliente criado anteriormente no Asaas. Como os clientes são independentes entre contas e ambientes, esse ID pode não existir na nova conta.

Antes de remover qualquer dado, consulte os registros afetados:

SELECT user_id, meta_key, meta_value
FROM wp_usermeta
WHERE meta_value LIKE '%cus_000%';

Confirme que os registros encontrados pertencem aos clientes que precisam ser recriados no novo ambiente.

❗️

Cuidado

Faça backup do banco antes de excluir metadados.

O comando abaixo remove todos os registros de wp_usermeta cujo valor corresponda ao padrão informado. Revise o resultado da consulta antes de executá-lo e confirme o prefixo das tabelas da sua instalação WordPress.

Após a validação, o procedimento atualmente documentado para remover os identificadores armazenados é:

DELETE FROM wp_usermeta
WHERE meta_value LIKE '%cus_000%';
📘

Importante

Esse problema ocorre apenas quando os mesmos dados de cliente são utilizados em contas ou ambientes diferentes.

Depois da remoção, faça uma nova compra para que o cliente seja criado no ambiente configurado.

A assinatura cria apenas o pedido

As versões atuais do Plugin Asaas declaram suporte ao High-Performance Order Storage (HPOS).

Se apenas o pedido for criado:

  1. atualize o Plugin Asaas e o WooCommerce Subscriptions;
  2. faça um novo teste;
  3. consulte os logs caso a assinatura continue sem ser criada.

Como alternativa de compatibilidade, acesse:

WooCommerce > Configurações > Avançado > Recursos

Em seguida:

  • habilite Armazenamento de postagens do WordPress (legado); ou
  • clique em Ativar modo de compatibilidade, sincronize as assinaturas e tente novamente.

Consulte também Assinaturas no WooCommerce.

O pedido não é marcado como concluído

No WooCommerce, pedidos de produtos físicos podem exigir conclusão manual.

Para que o WooCommerce trate o produto como elegível à conclusão automática, configure-o como:

  • Virtual;
  • Baixável.

Problemas com Webhooks

O pagamento foi confirmado, mas o pedido não atualizou

Verifique o status da fila em:

WooCommerce > Status > Meio de Pagamentos Asaas

Se a fila estiver interrompida, a opção Reabilitar fila de webhooks será exibida.

Antes de reativar:

  1. consulte os Logs de Webhooks;
  2. identifique o código HTTP ou erro de comunicação;
  3. corrija a causa;
  4. volte ao WooCommerce e clique em Reabilitar fila de webhooks.

Após a recuperação, o status deve ser atualizado e o botão ficará indisponível.

Consulte Webhooks do WooCommerce para acompanhar a saúde da sincronização.

Erro 403 nos Webhooks

Um HTTP 403 em Webhooks geralmente indica que a requisição chegou à infraestrutura da loja, mas foi bloqueada antes do processamento.

Verifique:

  • Firewall;
  • WAF ou Cloudflare;
  • regras de restrição por IP;
  • validações de headers;
  • mecanismos de segurança da hospedagem.

Se houver allowlist, confira os IPs oficiais do Asaas.

Erro 500 nos Webhooks

HTTP 500 indica falha interna no servidor que recebe o Webhook.

Verifique:

  • o Log de Depuração e os logs do servidor;
  • se o Plugin Asaas está atualizado;
  • se o servidor e suas dependências estão disponíveis;
  • se existem exceções durante o processamento;
  • se há Webhooks duplicados configurados para a mesma loja.

Corrija a falha antes de reativar a fila.

Consulte o guia de erro 500.

Erro 408 nos Webhooks

408 Read Timed Out indica que o Asaas estabeleceu a conexão, mas não recebeu uma resposta dentro de 10 segundos.

Evite processamentos demorados antes de responder ao Webhook.

Quando possível:

  1. receba e persista o evento;
  2. responda com sucesso;
  3. processe tarefas mais demoradas de forma assíncrona.

Depois de corrigir o timeout, reative a fila.

Consulte o guia de erro 408.

Incompatibilidade com outros plugins

Se o Plugin Asaas apresentar comportamentos como:

  • QR Code não exibido;
  • cliente criado sem geração da cobrança;
  • falhas inesperadas no checkout;
  • falhas no processamento de Webhooks;

verifique se outro plugin está modificando o checkout ou o processamento dos pedidos.

Plugins de personalização de checkout são um ponto comum de conflito.

Para investigar:

  1. mantenha o Log de Depuração habilitado;
  2. reproduza o problema;
  3. desative temporariamente plugins relacionados ao checkout em um ambiente de teste;
  4. repita a operação para identificar o conflito.

Próximos passos

Updated 9 days ago

Did this page help you?