Problemas Comuns
Esta página cobre problemas encontrados com frequência, organizados por categoria. Cada entrada segue o formato: Problema, Causa, Solução.
Instalação
Plugin falha ao ativar
Problema: Ativar o plugin produz um erro fatal ou tela branca.
Causa: A versão do PHP está abaixo de 8.4, ou uma extensão PHP necessária está ausente.
Solução: Verifique se a versão do PHP atende ao requisito mínimo (8.4+). Certifique-se de que as seguintes extensões estão habilitadas: json, mbstring, openssl, curl, soap (obrigatória para a integração com ISSNet). Verifique no painel de controle da hospedagem ou execute php -v e php -m na linha de comando.
WooCommerce não detectado
Problema: Aviso no admin diz "MIDDAG Account requer WooCommerce."
Causa: O WooCommerce não está instalado, não está ativado, ou sua versão está abaixo de 9.0.
Solução: Instale e ative o WooCommerce 9.0 ou superior. O MIDDAG Account verifica a presença do WooCommerce no hook plugins_loaded e não inicializa completamente sem ele.
Autoloader do Composer não encontrado
Problema: Erro fatal referenciando vendor/autoload.php.
Causa: As dependências não foram instaladas, ou o diretório vendor/ foi excluído.
Solução: Execute composer install --no-dev no diretório do plugin. Se estiver fazendo deploy a partir de um arquivo de build, certifique-se de ter usado composer dist:build, que inclui as dependências.
Estilos e scripts não carregam
Problema: A admin UI aparece sem estilo ou exibe uma página em branco.
Causa: A saída do build Vite está ausente em assets/dist/.
Solução: Execute composer ui:npm:build para compilar o frontend React. Verifique se assets/dist/app.js existe após a conclusão do build.
Configuração
Entitlements não criados na compra
Problema: Um pedido WooCommerce é concluído, mas nenhum entitlement aparece.
Causa: O produto WooCommerce não está mapeado para uma Entitlement Class, ou o status do pedido não atingiu o estado de concluído.
Solução: Edite o produto WooCommerce e certifique-se de que o campo de Entitlement Class está preenchido. Verifique se o status do pedido atinge "concluído" ou "processando" (dependendo do seu gateway de pagamento). Verifique os logs do plugin em busca de erros durante o hook do pedido.
Erros de fronteira de organização
Problema: Requisições à API retornam AUTHORIZATION_ERROR com "organization mismatch."
Causa: O header X-Middag-Organization está ausente ou não corresponde à organização do usuário autenticado.
Solução: Inclua o header X-Middag-Organization em toda requisição à API. O valor deve ser um ID de organização onde o usuário autenticado é um colaborador ativo. Consulte a Referência de Erros para códigos de erro específicos.
Policy Engine não aplica overrides
Problema: Um override de policy por organização ou por produto não tem efeito.
Causa: Overrides de policy são avaliados em ordem de prioridade: entitlement > produto > organização > classe > global. Uma policy de maior prioridade pode estar sobrescrevendo sua configuração.
Solução: Verifique policies em todos os cinco níveis. Use a REST API para listar policies ativas para o entitlement afetado e verifique a cadeia de herança. A policy mais específica prevalece.
Autenticação JWT falha
Problema: Requisições à API com token JWT retornam AUTHENTICATION_ERROR.
Causa: O token está expirado, a chave de assinatura foi alterada, ou o token foi emitido para outro site.
Solução: Solicite um novo token. Verifique se o arquivo de chave privada JWT existe e está legível pelo servidor web (mas não dentro do webroot). Certifique-se de que o relógio do servidor está preciso, pois a válidação JWT é sensível ao tempo. Consulte os códigos de erro MIDDAG-AUTH-TOKEN_EXPIRED e MIDDAG-AUTH-TOKEN_REVOKED na Referência de Erros.
Capabilities customizadas não funcionam
Problema: Um usuário com o papel esperado não consegue acessar determinadas funcionalidades.
Causa: As capabilities customizadas não foram atualizadas após a ativação do plugin, ou outro plugin conflitante está filtrando capabilities.
Solução: Desative e reative o plugin para acionar o registro de capabilities. Se o problema persistir, verifique se há outros plugins que modificam user_has_cap ou utilizam plugins de editor de papéis que possam remover capabilities customizadas.
Integrações
Webhooks do Stripe não chegam
Problema: Pagamentos são processados no Stripe, mas o plugin não atualiza o status do entitlement.
Causa: A URL do endpoint de webhook está incorreta, o Stripe está enviando para o ambiente errado, ou o secret do webhook está mal configurado.
Solução: No Stripe Dashboard, verifique se a URL do endpoint de webhook aponta para a REST API do seu site: https://seusite.com/wp-json/middag-account/v1/webhooks/stripe. Confirme que o signing secret nas configurações do plugin corresponde ao exibido no Stripe. Verifique o log de erros do servidor em busca de falhas na válidação de assinatura.
Erros de sincronização com HubSpot
Problema: Organizações ou deals não estão sincronizando do HubSpot.
Causa: As credenciais de API expiraram, o escopo do app HubSpot é insuficiente, ou a configuração dual-account está apontando para o portal errado.
Solução: Verifique se a chave de API ou token OAuth do HubSpot é válido. Certifique-se de que o app possui os escopos necessários (contacts, deals, companies). Para configurações dual-account, confirme que cada conta (BR e US) possui suas próprias credenciais configuradas na seção de configurações apropriada.
Geração de NFSe via ISSNet falha
Problema: A geração de nota fiscal retorna um erro ou expira por timeout.
Causa: O endpoint SOAP está inacessível, o certificado municipal expirou, ou campos obrigatórios estão ausentes.
Solução: Verifique a conectividade de rede com o endpoint SOAP do ISSNet. Certifique-se de que o certificado digital é válido e está configurado corretamente. Garanta que todos os campos obrigatórios (CNPJ, inscrição municipal, código de serviço) estão preenchidos nas configurações da organização. O ISSNet é específico de Brasília/DF; outros municípios não são suportados.
Pix/Boleto do Banco Inter não é gerado
Problema: Boletos ou códigos Pix não são criados.
Causa: As credenciais de API ou o certificado do Banco Inter são inválidos, ou a URL de callback do webhook está inacessível.
Solução: Verifique o client ID, client secret e o certificado mTLS nas configurações do plugin. Certifique-se de que seu servidor consegue acessar os endpoints da API do Banco Inter. Verifique se a URL de callback do webhook é acessível publicamente (não protegida por autenticação básica ou restrições de IP).
Sincronização de solicitações de serviço com Jira trava
Problema: Solicitações de serviço criadas no MIDDAG Account não aparecem no Jira, ou atualizações do Jira não sincronizam de volta.
Causa: O token de API do Jira expirou, a chave do projeto está errada, ou os mapeamentos de campos estão mal configurados.
Solução: Verifique o token de API e a URL base do Jira nas configurações do plugin. Confirme que o projeto-alvo no Jira existe e que o token tem permissão para criar e atualizar issues. Verifique a configuração de mapeamento de campos para garantir que os campos do MIDDAG Account correspondem a campos customizados válidos do Jira.
Obtendo Mais Ajuda
Se o seu problema não está listado aqui, consulte:
- Referência de Erros para códigos de erro específicos e correções
- Suporte para saber como reportar bugs e obter assistência