Resolução de problemas técnicos: Corrigir erros de conexão

A maioria dos erros de conexão entre o Lexiik e a sua loja de e-commerce provém de problemas de autenticação, permissões ou configuração do servidor. Este guia ajuda-o a diagnosticar e resolver os problemas mais comuns.

Os 5 erros mais comuns

Aqui estão os erros que encontramos com mais frequência ao conectar uma loja. Cada erro tem uma solução simples.

Erro 403: Acesso negado (Forbidden)

Causa principal: A chave API não tem as permissões necessárias para ler ou escrever dados de produtos.

Soluções por plataforma

Shopify

1. Shopify Admin > Configurações > Apps e canais de vendas
2. Encontre "Lexiik" e clique em "Gerir"
3. Verifique que as permissões incluem: read_products, write_products, read_files, write_files
4. Se as permissões estiverem incorretas, desinstale e reinstale a aplicação

WooCommerce

1. WordPress Admin > WooCommerce > Configurações > Avançado > Chaves REST API
2. Encontre a chave utilizada pelo Lexiik
3. Verifique que as permissões estão definidas como: Leitura/Escrita (não apenas "Leitura")
4. Se necessário, gere uma nova chave com as permissões corretas

PrestaShop

1. Back-office PrestaShop > Parâmetros avançados > Webservice
2. Edite a chave API utilizada pelo Lexiik
3. Assinale todas as permissões para: products, categories, images, stock_availables
4. Guarde e teste novamente

Erro 500: Erro interno do servidor

Causa principal: Problema do lado do servidor da sua loja (PHP, base de dados, memória insuficiente).

Diagnóstico passo a passo

1. Verifique os logs de erros PHP
   • WooCommerce: wp-content/debug.log
   • PrestaShop: var/logs/
2. Verifique a configuração PHP
   • memory_limit: mínimo 256M (recomendado: 512M)
   • max_execution_time: mínimo 300 segundos
   • upload_max_filesize: mínimo 64M
3. Teste a API manualmente — Utilize uma ferramenta como Postman ou curl para testar diretamente o endpoint API da sua loja
4. Verifique a conexão à base de dados — Uma base de dados saturada ou desconectada pode causar erros 500 intermitentes

Erro 401: Não autorizado (Unauthorized)

Causa principal: A chave API está incorreta, expirou ou tem um formato errado.

Lista de verificação de resolução

• Verifique que não há espaços antes ou depois da chave API (erro frequente ao copiar e colar)
• Certifique-se de usar a última chave gerada (se criou várias, apenas a mais recente é válida)
• Verifique se a chave foi revogada nas configurações da sua loja
• Para PrestaShop, verifique que o webservice está ativado (Parâmetros avançados > Webservice > Sim)
• Teste a chave API com uma chamada curl para validar o seu funcionamento

Erro de timeout (tempo de espera excedido)

Causa principal: O seu servidor é demasiado lento ou sobrecarregado para processar os pedidos API no tempo atribuído.

Soluções

• 1. Otimize a base de dados — Um catálogo com 50 000+ produtos com tabelas sem índices pode causar timeouts. Limpe os logs e otimize as tabelas MySQL.
• 2. Desative temporariamente os plugins pesados — No WooCommerce, alguns plugins de cache ou segurança (Wordfence, All In One Security) podem abrandar os pedidos API. Teste desativando-os temporariamente.
• 3. Migre para o Lexiik Bridge — O Lexiik Bridge utiliza webhooks assíncronos que nunca causam timeouts, ao contrário da API standard.
• 4. Melhore o seu alojamento — Um VPS ou alojamento dedicado oferecerá melhor desempenho do que um alojamento partilhado básico.

Erro SSL/TLS (certificado inválido)

Causa principal: A sua loja não tem um certificado SSL válido ou ele expirou.

Resolução

1. Verifique o seu certificado SSL — Utilize o SSL Labs para testar a validade do seu certificado
2. Instale um certificado gratuito — O Let's Encrypt oferece certificados SSL gratuitos e renováveis automaticamente. A maioria dos fornecedores de alojamento (cPanel, Plesk) oferece instalação com um clique.
3. Force o HTTPS no seu CMS
   • Shopify: Automático (gerido pelo Shopify)
   • WooCommerce: Configurações > Geral > Endereço WordPress e Endereço do site (use https://)
   • PrestaShop: Loja > Configurações da loja > Ativar SSL (Sim)

Gestão de chaves API

As chaves API são as "palavras-passe" que permitem ao Lexiik aceder à sua loja. Aqui estão as boas práticas de gestão.

Gerar uma nova chave API

Shopify

1. Shopify Admin > Configurações > Apps e canais de vendas
2. Clique em "Desenvolver apps" (em baixo)
3. Crie uma app privada com os scopes: read_products, write_products, read_files, write_files
4. Copie o Admin API access token

WooCommerce

1. WordPress Admin > WooCommerce > Configurações > Avançado > Chaves REST API
2. Clique em "Adicionar chave"
3. Descrição: "Lexiik Bridge"
4. Utilizador: A sua conta de administrador
5. Permissões: Leitura/Escrita
6. Gere a chave e copie a Consumer key e o Consumer secret

PrestaShop

1. Back-office PrestaShop > Parâmetros avançados > Webservice
2. Ative o webservice se ainda não o fez
3. Clique em "Adicionar nova chave"
4. Descrição da chave: "Lexiik Bridge"
5. Assinale todas as permissões (ou no mínimo: products, categories, images, stock_availables)
6. Clique em "Guardar" e copie a chave gerada

Proteger as suas chaves API

• Nunca partilhe as suas chaves API publicamente (GitHub, fóruns, capturas de ecrã)
• Renove as suas chaves a cada 6 meses como medida de segurança
• Elimine as chaves não utilizadas para reduzir a superfície de ataque
• Crie uma chave dedicada por serviço (uma para o Lexiik, outra para outra ferramenta, etc.)
• Documente o uso de cada chave com uma descrição clara

Problemas de permissões de escrita

Alguns erros ocorrem quando o Lexiik não tem permissões de escrita em determinados ficheiros ou pastas do seu servidor.

Erro ao carregar imagens

Causa: A pasta de upload não tem as permissões de escrita corretas.

Solução (via SSH ou FTP)

chmod -R 755 /path/to/wordpress/wp-content/uploads/

chmod -R 755 /path/to/prestashop/img/

Verificação de permissões

Aqui estão as permissões recomendadas para cada plataforma:

Ferramentas de diagnóstico

O Lexiik oferece várias ferramentas integradas para diagnosticar problemas de conexão.

Teste de conexão integrado

No painel do Lexiik, vá a Conexões > Testar a conexão. Esta ferramenta realiza uma série de verificações automáticas:

• Validade da chave API
• Permissões de leitura/escrita
• Tempo de resposta do servidor
• Certificado SSL
• Compatibilidade da versão da plataforma

Logs de sincronização

Cada tentativa de sincronização é registada nos logs. Para aceder a eles:

1. Painel do Lexiik > Conexões
2. Clique nos 3 pontos junto à sua loja
3. Selecione "Ver logs"

Os logs indicam:

• Data e hora de cada sincronização
• Estado (sucesso ou falha)
• Duração da sincronização
• Número de produtos processados
• Mensagens de erro detalhadas em caso de falha

Modo debug

Para programadores, o Lexiik Bridge oferece um modo debug que regista todos os detalhes técnicos.

Ativar o modo debug

No módulo Lexiik Bridge da sua loja:

1. Abra a configuração do módulo
2. Ative a opção "Modo debug"
3. Realize uma sincronização
4. Consulte o ficheiro de log gerado (localização indicada na configuração)

Casos particulares e alojamentos específicos

Alguns fornecedores de alojamento ou configurações de servidor requerem ajustes específicos.

Alojamento partilhado

Os alojamentos partilhados (OVH, O2Switch, Ionos, etc.) impõem por vezes restrições.

• Problema: Webhooks bloqueados pela firewall
  Solução: Adicione os IPs do Lexiik à lista branca (disponíveis em Configurações > Integrações)
• Problema: Limite de pedidos API por minuto
  Solução: O Lexiik Bridge gere automaticamente o rate limiting. Se utilizar a API standard, migre para o Bridge.
• Problema: PHP memory_limit demasiado baixo (128M)
  Solução: Contacte o seu fornecedor de alojamento para aumentar para 256M no mínimo. Ou adicione em wp-config.php: define('WP_MEMORY_LIMIT', '256M');

Sites atrás do Cloudflare

Se a sua loja utiliza Cloudflare, algumas regras de segurança podem bloquear os webhooks do Lexiik.

Configuração Cloudflare recomendada

1. Cloudflare Dashboard > Firewall Rules
2. Crie uma regra de exceção para os URLs: /wp-json/lexiik/* (WooCommerce) ou /api/lexiik/* (PrestaShop)
3. Ação: Allow (permitir)
4. Em Security Level, defina "Medium" em vez de "High" para estes URLs

Web Application Firewall (WAF)

Os WAF como Sucuri, Wordfence ou ModSecurity podem bloquear os pedidos API.

• Wordfence (WordPress): Vá a Wordfence > Firewall > Rate Limiting > Adicione o IP do Lexiik à lista branca
• Sucuri: Crie uma regra de exceção para os endpoints /wp-json/lexiik/ ou /api/lexiik/
• ModSecurity: Adicione uma regra de exceção no ficheiro .htaccess ou contacte o seu fornecedor de alojamento

Obter ajuda adicional

Se não encontrar uma solução neste guia, a equipa de suporte do Lexiik está aqui para o ajudar.

Contactar o suporte

• Chat em direto: Disponível 7 dias por semana no painel do Lexiik (canto inferior direito)
• Email: [email protected] (resposta em menos de 2 horas em média)
• Telefone: Apenas para planos Pro e Expert (número disponível na sua área de cliente)
• Documentação técnica: docs.lexiik.com

Recursos complementares

• Guia de conexão da loja
• Comparativo Bridge vs API standard
• Lançar a sua primeira auditoria SEO