Problemy z integracjami w sklepie internetowym – diagnoza API i webhooks 2026

Sklep internetowy w 2026 roku rzadko działa w pojedynkę. Przeciętny sklep ma od 5 do 15 integracji – od systemu magazynowego, przez kurierów, bramki płatnicze, marketplace'y, po narzędzia księgowe i reklamowe. Każde połączenie to potencjalny punkt awarii.

W praktyce spotykamy cztery typy integracji, każda z własną charakterystyką problemów:

• REST API (synchroniczne) – sklep sam odpytuje zewnętrzny system. Typowe błędy: timeouty, rate limity, nieaktualne tokeny OAuth. Przykłady: Allegro REST, Shopify Admin API, WooCommerce REST.
• Webhooki (asynchroniczne push) – zewnętrzny system powiadamia sklep o zdarzeniu. Typowe błędy: nieosiągalny endpoint, brak weryfikacji sygnatury, duplikaty. Przykłady: PayU, Przelewy24, Stripe, BaseLinker.
• CSV/XML feedy – plik generowany cyklicznie, pobierany przez partnera. Typowe błędy: brakujące pola obowiązkowe, błędne kodowanie, stary timestamp. Przykłady: Ceneo, Google Merchant, Facebook Catalog.
• Middleware (BaseLinker, Apilo, Erli) – pośrednik spinający wiele systemów. Typowe błędy: błędny mapping pól, desynchronizacja, limit wywołań cron.

Z naszego doświadczenia problemy z BaseLinkerem odpowiadają za około 30% zgłoszeń serwisowych w sklepach korzystających z marketplace'ów. Kolejne 25% to kłopoty z synchronizacją stanów magazynowych opisane w artykule problemy z stany magazynowe. Reszta rozkłada się mniej więcej równo między API, webhooki i feedy.

Webhook, który nie przychodzi, to klasyk – i paradoksalnie najłatwiejszy do zdiagnozowania problem. Trzeba tylko wiedzieć, gdzie patrzeć.

Krok 1: Sprawdź, czy dostawca w ogóle wysłał webhook. Większość poważnych serwisów (Stripe, PayU, Przelewy24, Allegro) ma w panelu logi webhooków z kodem odpowiedzi. Jeśli widzisz tam 200 OK, problem jest po Twojej stronie (np. kod nie przetworzył danych, ale zwrócił sukces). Jeśli widzisz 500, 404 albo timeout – endpoint jest uszkodzony lub nieosiągalny.

Krok 2: Przetestuj endpoint z zewnątrz. Użyj narzędzia webhook.site lub curl z innej maszyny:

curl -X POST https://twojsklep.pl/webhook/payu \
  -H "Content-Type: application/json" \
  -d '{"test": true}' -v

Jeśli dostajesz błąd SSL – masz nieaktualny certyfikat albo niepełny łańcuch certyfikatów (brak intermediate). To drugi najczęstszy powód nieodbierania webhooków. Sprawdź na ssllabs.com/ssltest/.

Krok 3: Zweryfikuj logi serwera. W Nginx: `/var/log/nginx/access.log`. Szukaj requestów na endpoint webhooka. Jeśli ich nie ma, a dostawca twierdzi, że wysłał – masz problem z firewallem lub WAF (Cloudflare, Sucuri). Często WAF blokuje requesty bez nagłówka User-Agent.

Krok 4: Sprawdź, czy webhook zwraca 200 w rozsądnym czasie. Większość dostawców retry'uje, jeśli odpowiedź przyjdzie po 5-10 sekundach. Jeśli Twój kod synchronicznie przetwarza dużo danych (np. generuje fakturę i wysyła email), odpowiedź może się spóźniać. Rozwiązanie: przyjmij webhook, zapisz do kolejki, zwróć 200, a przetwarzaj asynchronicznie.

W WooCommerce webhooki konfiguruje się w WooCommerce → Ustawienia → Zaawansowane → Webhooki. Szczegóły w artykule webhooki w WooCommerce.

API timeout to cichy zabójca integracji. Sklep działa, klienci kupują, ale po kilku godzinach orientujesz się, że 15% zamówień nie dotarło do ERP, bo Allegro zwracał 429 (Too Many Requests), a Twój kod tego nie obsłużył.

Typowe przyczyny timeoutów i rate limitów:

Rozwiązanie 1: Exponential backoff. Po błędzie 429 nie retry'uj natychmiast. Czekaj 1 sekundę, potem 2, potem 4, potem 8. W pseudokodzie:

attempt = 1
while attempt <= 5:
    response = call_api()
    if response.status == 429:
        sleep(2 ** attempt)
        attempt += 1
        continue
    break

Rozwiązanie 2: Przetwarzanie asynchroniczne z kolejką. Zamiast wywoływać API z poziomu request/response użytkownika, dodaj zadanie do kolejki (Redis, RabbitMQ, Laravel Queue, wp-cron) i przetwarzaj w workerze. To samo dotyczy wysyłki faktur – faktury w WooCommerce powinny lecieć w tle.

Rozwiązanie 3: Cache'uj, co da się cache'ować. Dane produktów z Allegro, stawki VAT z Fakturowni, katalogi kurierów – wszystko to zmienia się rzadko. Cache w Redis na 5-15 minut redukuje ruch do API o 80-95%.

Rozwiązanie 4: Zwiększ timeout PHP i FastCGI. Domyślne 30 sekund to często za mało. W php.ini: `max_execution_time = 120`, w nginx: `fastcgi_read_timeout 120s`. Ale to plaster – docelowo przenieś długie operacje do workera.

Allegro to najtrudniejsza integracja w polskim e-commerce. API jest dobrze udokumentowane, ale ma setki punktów końcowych i co kwartał pojawiają się zmiany. Oto problemy, z którymi spotykamy się najczęściej:

Błąd 401 Unauthorized – token wygasł. Allegro używa OAuth 2.0 z access tokenem ważnym 12 godzin i refresh tokenem ważnym 90 dni. Jeśli integracja nie odświeża tokenu automatycznie – siada. Rozwiązanie: implementuj refresh token flow i zapisuj nowy access token w bazie przy każdym odświeżeniu.

Błąd 422 przy wystawianiu oferty – pola wymagane. Allegro wymaga różnych parametrów dla różnych kategorii (np. kategoria "Elektronika" wymaga EAN i stanu baterii). Najczęstsze braki: `parameters.required_id_1234`, `images.url`, `stock.available`, `delivery.shippingRates`.

Duplikaty ofert po synchronizacji z BaseLinkerem. Jeśli w BaseLinkerze ustawisz "wystaw nowe oferty" bez mapowania external_id, po każdym pełnym sync powstaje duplikat. Zawsze mapuj po SKU lub własnym ID. Szczegóły w allegro w WooCommerce.

Limit 10 000 aktywnych ofert na konto Pro. Mało kto pamięta, że Allegro Pro ma twardy limit wystawień. Powyżej potrzebujesz konta Pro+ albo musisz rotować ofertami (zakończ nieaktywne po 14 dniach).

Smart! – zamówienia bez webhooka. Allegro Smart! wysyła zamówienia inną ścieżką niż standardowe. Upewnij się, że Twoja integracja subskrybuje event `CHECKOUT_FORM_FILLED_EVENT`, a nie tylko `BOUGHT_EVENT`.

Ceny z przecinkiem zamiast kropki. Allegro API akceptuje tylko kropkę jako separator dziesiętny. PHP z polskim locale domyślnie konwertuje float na string z przecinkiem. Wymuś format: `number_format($price, 2, '.', '')`.

BaseLinker to de facto standard polskiego e-commerce z marketplace'ami – około 70% sklepów sprzedających na Allegro i Empik używa właśnie jego. I właśnie dlatego problemy z BaseLinker trafiają do nas najczęściej.

Typowe problemy z BaseLinker + WooCommerce:

• Zamówienia nie wpadają – sprawdź token API w BaseLinkerze (Twoje konto → API). Token musi być aktywny, a w WooCommerce wtyczka baselinker w WooCommerce musi mieć uprawnienia `read/write` dla Orders, Products, Customers.
• Stany magazynowe się rozjeżdżają – BaseLinker synchronizuje co X minut (domyślnie 15). Jeśli sprzedajesz ten sam produkt na 5 kanałach równocześnie, mogą powstać overselling'i. Włącz "rezerwację po zamówieniu" i ustaw sync na 5 minut.
• Duplikaty produktów po imporcie – BaseLinker mapuje po SKU. Jeśli w WooCommerce niektóre produkty nie mają SKU, po każdym sync tworzy nowe. Uzupełnij SKU przed importem.
• Faktury nie podpinają się do zamówienia – w BaseLinkerze: Automatyczne akcje → Dodaj akcję "Wystaw fakturę" z triggerem "Zmiana statusu na Zapakowane".
• Cron nie wykonuje się – WordPress wp-cron odpala się tylko przy ruchu na stronie. Jeśli sklep ma mało ruchu, sync nie następuje. Rozwiązanie: wyłącz wp-cron w wp-config (`define('DISABLE_WP_CRON', true);`) i ustaw systemowy cron co 5 minut.

Kiedy BaseLinker nie wystarcza? Przy ruchu powyżej 500 zamówień/dziennie zaczynasz walczyć z limitami API i opóźnieniami. Wtedy warto rozważyć Apilo integracja WooCommerce albo dedykowaną integrację.

ERP w polskim sklepie to najczęściej Subiekt GT, Subiekt Nexo, Comarch Optima albo enova365. Każdy z tych systemów ma własną filozofię – i własne pułapki integracyjne.

Subiekt GT (InsERT) – problemy typowe:

• Kodowanie Windows-1250 – Subiekt GT używa Windows-1250, a sklep UTF-8. Nazwy z ogonkami (ąęłśćżź) wychodzą jako krzaki. Rozwiązanie: konwersja `iconv('UTF-8', 'WINDOWS-1250//TRANSLIT', $text)` w obie strony.
• Sfera SDK tylko na Windows – bridge między Subiektem a sklepem musi stać na Windowsie (usługa webhook). W praktyce używa się middleware typu Sote, Selly, Sky-Shop albo własnego .NET service.
• Magazyn domyślny – jeśli Subiekt ma wiele magazynów, trzeba wybrać jeden jako "sklepowy". Inaczej stany się gubią.

Comarch Optima / XL – problemy typowe:

• Brak natywnego REST API w starszych wersjach – do Optimy integrujesz się przez COM albo Comarch e-Sklep. Nowsze wersje (2024+) mają REST.
• Kolekcje w Optimie vs atrybuty w WooCommerce – mapping 1:1 rzadko działa. Trzeba tworzyć słownik atrybutów.

enova365 – problemy typowe:

• Licencja Business = dodatkowa opłata za API – standardowy pakiet nie zawiera API. Dopłata około 200-400 zł/mies.
• Wielofirmowość – enova pozwala na wiele firm w jednej bazie. API musi wiedzieć, do której firmy pisze. W nagłówku zawsze przekazuj `X-CompanyId`.

Cała ERP integracja sklepu to temat na książkę. Podstawy w erp integracja WooCommerce. Jeśli integrujesz po raz pierwszy – porozmawiaj z nami przed wyborem middleware. Zły wybór kosztuje później 15-30 tys. zł migracji.

Marketplace'y nie są prawdziwymi integracjami – to pliki XML albo CSV pobierane przez partnera z Twojego serwera. Brzmi prosto, ale diabeł tkwi w formacie.

Ceneo XML – najczęstsze błędy:

• Brak pól obowiązkowych: ``, ``, ``, ``, ``, ``. Ceneo odrzuca cały feed, jeśli choć jeden produkt nie ma któregoś z nich.
• Nieprawidłowy URL obrazków – muszą być absolutne (https://) i publicznie dostępne bez autoryzacji. Często CDN z hotlink protection blokuje boty Ceneo.
• Kategoria niemapowana – Ceneo ma własne drzewo kategorii. Twoje "Buty sportowe męskie" musi dopasować się do ceneovej "Moda > Obuwie > Męskie > Sportowe".
• Duplikaty EAN/GTIN – jeden kod kreskowy może mieć tylko jeden produkt. Jeśli masz warianty (rozmiary), każdy wariant potrzebuje własnego EAN.

Amazon – najczęstsze błędy:

• Listing Quality – Amazon odrzuca oferty z tytułami powyżej 200 znaków, bez Brand Name, bez obrazków 1000x1000 na białym tle.
• Compatible barcode – bez GTIN/EAN/UPC nie wystawisz produktu (chyba że masz GTIN exemption).
• Pricing errors – Amazon ma algorytm wykrywający "za wysokie ceny" (30-50% powyżej konkurencji). Produkt zostaje zawieszony do wyjaśnienia.

Empik Marketplace – najczęstsze błędy:

• Empik wymaga ISBN dla książek i UPC dla reszty. Bez tego – reject.
• Opisy w HTML są ograniczone – dozwolone tylko `

  `, `
  `, `

  `, `
  • `, ``. Reszta jest stripowana.

  Więcej o technicznym prowadzeniu sklepu na WooCommerce i optymalizacji feedów produktowych znajdziesz w powiązanych artykułach.

  Zasada ogólna: każdy marketplace ma własny feed validator – używaj go przed każdym uploadem, a nie po tym, jak zobaczysz, że nic się nie wystawiło. Na Ceneo to `/sprzedajacy/raporty`, na Amazonie Feeds Report, na Empiku panel partnerski.