Rozwiązywanie problemów technicznych: Naprawianie błędów połączenia

Większość błędów połączenia między Lexiik a Twoim sklepem e-commerce wynika z problemów z uwierzytelnianiem, uprawnieniami lub konfiguracją serwera. Ten przewodnik pomoże Ci zdiagnozować i rozwiązać najczęstsze problemy.

5 najczęstszych błędów

Oto błędy, które najczęściej napotykamy podczas łączenia sklepu. Każdy z nich ma proste rozwiązanie.

Błąd 403: Odmowa dostępu (Forbidden)

Główna przyczyna: Klucz API nie posiada wymaganych uprawnień do odczytu lub zapisu danych produktów.

Rozwiązania według platformy

Shopify

1. Shopify Admin > Ustawienia > Aplikacje i kanały sprzedaży
2. Znajdź "Lexiik" i kliknij "Zarządzaj"
3. Sprawdź, czy uprawnienia obejmują: read_products, write_products, read_files, write_files
4. Jeśli uprawnienia są nieprawidłowe, odinstaluj i zainstaluj aplikację ponownie

WooCommerce

1. WordPress Admin > WooCommerce > Ustawienia > Zaawansowane > Klucze REST API
2. Znajdź klucz używany przez Lexiik
3. Sprawdź, czy uprawnienia są ustawione na: Odczyt/Zapis (nie tylko "Odczyt")
4. W razie potrzeby wygeneruj nowy klucz z prawidłowymi uprawnieniami

PrestaShop

1. Back-office PrestaShop > Parametry zaawansowane > Webservice
2. Edytuj klucz API używany przez Lexiik
3. Zaznacz wszystkie uprawnienia dla: products, categories, images, stock_availables
4. Zapisz i przetestuj ponownie

Błąd 500: Wewnętrzny błąd serwera

Główna przyczyna: Problem po stronie serwera Twojego sklepu (PHP, baza danych, niewystarczająca pamięć).

Diagnoza krok po kroku

1. Sprawdź logi błędów PHP
   • WooCommerce: wp-content/debug.log
   • PrestaShop: var/logs/
2. Sprawdź konfigurację PHP
   • memory_limit: minimum 256M (zalecane: 512M)
   • max_execution_time: minimum 300 sekund
   • upload_max_filesize: minimum 64M
3. Przetestuj API ręcznie — Użyj narzędzia takiego jak Postman lub curl, aby bezpośrednio przetestować endpoint API swojego sklepu
4. Sprawdź połączenie z bazą danych — Przeciążona lub rozłączona baza danych może powodować przerywane błędy 500

Błąd 401: Brak autoryzacji (Unauthorized)

Główna przyczyna: Klucz API jest nieprawidłowy, wygasł lub ma błędny format.

Lista kontrolna rozwiązania

• Sprawdź, czy przed kluczem API ani za nim nie ma spacji (częsty błąd przy kopiowaniu i wklejaniu)
• Upewnij się, że używasz ostatnio wygenerowanego klucza (jeśli utworzyłeś kilka, ważny jest tylko najnowszy)
• Sprawdź, czy klucz nie został unieważniony w ustawieniach Twojego sklepu
• W przypadku PrestaShop sprawdź, czy webservice jest włączony (Parametry zaawansowane > Webservice > Tak)
• Przetestuj klucz API za pomocą wywołania curl, aby sprawdzić jego działanie

Błąd timeout (przekroczenie czasu oczekiwania)

Główna przyczyna: Twój serwer jest zbyt wolny lub przeciążony, by przetworzyć żądania API w wyznaczonym czasie.

Rozwiązania

• 1. Zoptymalizuj bazę danych — Katalog zawierający 50 000+ produktów z nieindeksowanymi tabelami może powodować timeouty. Wyczyść logi i zoptymalizuj tabele MySQL.
• 2. Tymczasowo dezaktywuj ciężkie wtyczki — W WooCommerce niektóre wtyczki pamięci podręcznej lub zabezpieczeń (Wordfence, All In One Security) mogą spowalniać żądania API. Przetestuj wyłączając je tymczasowo.
• 3. Migruj do Lexiik Bridge — Lexiik Bridge wykorzystuje asynchroniczne webhooki, które nigdy nie powodują timeoutów, w przeciwieństwie do standardowego API.
• 4. Zaktualizuj swój hosting — VPS lub dedykowany hosting zaoferuje lepszą wydajność niż podstawowy hosting współdzielony.

Błąd SSL/TLS (nieprawidłowy certyfikat)

Główna przyczyna: Twój sklep nie posiada ważnego certyfikatu SSL lub wygasł.

Rozwiązanie

1. Sprawdź certyfikat SSL — Użyj SSL Labs, aby przetestować ważność certyfikatu
2. Zainstaluj bezpłatny certyfikat — Let's Encrypt oferuje bezpłatne certyfikaty SSL z automatycznym odnawianiem. Większość dostawców hostingu (cPanel, Plesk) oferuje instalację jednym kliknięciem.
3. Wymusz HTTPS w swoim CMS
   • Shopify: Automatycznie (zarządzane przez Shopify)
   • WooCommerce: Ustawienia > Ogólne > Adres WordPress i Adres strony (użyj https://)
   • PrestaShop: Sklep > Ustawienia sklepu > Włącz SSL (Tak)

Zarządzanie kluczami API

Klucze API to "hasła", które umożliwiają Lexiik dostęp do Twojego sklepu. Oto najlepsze praktyki zarządzania nimi.

Generowanie nowego klucza API

Shopify

1. Shopify Admin > Ustawienia > Aplikacje i kanały sprzedaży
2. Kliknij "Twórz aplikacje" (na dole)
3. Utwórz prywatną aplikację z zakresami: read_products, write_products, read_files, write_files
4. Skopiuj Admin API access token

WooCommerce

1. WordPress Admin > WooCommerce > Ustawienia > Zaawansowane > Klucze REST API
2. Kliknij "Dodaj klucz"
3. Opis: "Lexiik Bridge"
4. Użytkownik: Twoje konto administratora
5. Uprawnienia: Odczyt/Zapis
6. Wygeneruj klucz i skopiuj Consumer key oraz Consumer secret

PrestaShop

1. Back-office PrestaShop > Parametry zaawansowane > Webservice
2. Aktywuj webservice, jeśli nie zostało to jeszcze zrobione
3. Kliknij "Dodaj nowy klucz"
4. Opis klucza: "Lexiik Bridge"
5. Zaznacz wszystkie uprawnienia (lub co najmniej: products, categories, images, stock_availables)
6. Kliknij "Zapisz" i skopiuj wygenerowany klucz

Zabezpieczanie kluczy API

• Nigdy nie udostępniaj publicznie swoich kluczy API (GitHub, fora, zrzuty ekranu)
• Odnawiaj klucze co 6 miesięcy jako środek bezpieczeństwa
• Usuń nieużywane klucze, aby zmniejszyć powierzchnię ataku
• Utwórz dedykowany klucz dla każdej usługi (jeden dla Lexiik, jeden dla innego narzędzia itp.)
• Dokumentuj użycie każdego klucza z jasnym opisem

Problemy z uprawnieniami do zapisu

Niektóre błędy pojawiają się, gdy Lexiik nie ma uprawnień do zapisu w określonych plikach lub folderach na Twoim serwerze.

Błąd podczas przesyłania obrazów

Przyczyna: Folder przesyłania nie posiada właściwych uprawnień do zapisu.

Rozwiązanie (przez SSH lub FTP)

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

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

Weryfikacja uprawnień

Oto zalecane uprawnienia dla każdej platformy:

Narzędzia diagnostyczne

Lexiik oferuje kilka wbudowanych narzędzi do diagnozowania problemów z połączeniem.

Wbudowany test połączenia

W panelu Lexiik przejdź do Połączenia > Testuj połączenie. Narzędzie to wykonuje serię automatycznych weryfikacji:

• Ważność klucza API
• Uprawnienia do odczytu/zapisu
• Czas odpowiedzi serwera
• Certyfikat SSL
• Zgodność wersji platformy

Logi synchronizacji

Każda próba synchronizacji jest rejestrowana w logach. Aby uzyskać do nich dostęp:

1. Panel Lexiik > Połączenia
2. Kliknij 3 kropki obok swojego sklepu
3. Wybierz "Pokaż logi"

Logi zawierają:

• Datę i godzinę każdej synchronizacji
• Status (sukces lub błąd)
• Czas trwania synchronizacji
• Liczbę przetworzonych produktów
• Szczegółowe komunikaty błędów w przypadku niepowodzenia

Tryb debug

Dla programistów Lexiik Bridge oferuje tryb debug, który rejestruje wszystkie szczegóły techniczne.

Włączenie trybu debug

W module Lexiik Bridge Twojego sklepu:

1. Otwórz konfigurację modułu
2. Włącz opcję "Tryb debug"
3. Przeprowadź synchronizację
4. Sprawdź wygenerowany plik logu (lokalizacja podana w konfiguracji)

Szczególne przypadki i specyficzne konfiguracje hostingu

Niektórzy dostawcy hostingu lub konfiguracje serwera wymagają specyficznych dostosowań.

Hosting współdzielony

Hostingi współdzielone (OVH, O2Switch, Ionos itp.) niekiedy narzucają ograniczenia.

• Problem: Webhooki blokowane przez zaporę sieciową
  Rozwiązanie: Dodaj IP Lexiik do białej listy (dostępne w Ustawienia > Integracje)
• Problem: Limit żądań API na minutę
  Rozwiązanie: Lexiik Bridge automatycznie zarządza rate limitingiem. Jeśli używasz standardowego API, przejdź na Bridge.
• Problem: PHP memory_limit za niskie (128M)
  Rozwiązanie: Skontaktuj się z dostawcą hostingu, aby zwiększyć do minimum 256M. Lub dodaj do wp-config.php: define('WP_MEMORY_LIMIT', '256M');

Sklepy za Cloudflare

Jeśli Twój sklep używa Cloudflare, reguły bezpieczeństwa mogą blokować webhooki Lexiik.

Zalecana konfiguracja Cloudflare

1. Cloudflare Dashboard > Firewall Rules
2. Utwórz regułę wyjątku dla URL: /wp-json/lexiik/* (WooCommerce) lub /api/lexiik/* (PrestaShop)
3. Akcja: Allow (zezwól)
4. W Security Level ustaw "Medium" zamiast "High" dla tych URL

Web Application Firewall (WAF)

Zapory WAF jak Sucuri, Wordfence lub ModSecurity mogą blokować żądania API.

• Wordfence (WordPress): Przejdź do Wordfence > Firewall > Rate Limiting > Dodaj IP Lexiik do białej listy
• Sucuri: Utwórz regułę wyjątku dla endpointów /wp-json/lexiik/ lub /api/lexiik/
• ModSecurity: Dodaj regułę wyjątku do pliku .htaccess lub skontaktuj się z dostawcą hostingu

Uzyskanie dodatkowej pomocy

Jeśli nie znajdziesz rozwiązania w tym przewodniku, zespół wsparcia Lexiik jest do Twojej dyspozycji.

Skontaktuj się z pomocą techniczną

• Czat na żywo: Dostępny 7 dni w tygodniu w panelu Lexiik (prawy dolny róg)
• Email: [email protected] (średni czas odpowiedzi: 2 godziny)
• Telefon: Tylko dla planów Pro i Expert (numer dostępny w obszarze klienta)
• Dokumentacja techniczna: docs.lexiik.com

Dodatkowe zasoby

• Przewodnik połączenia sklepu
• Porównanie Bridge vs standardowe API
• Uruchomienie pierwszego audytu SEO