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

Narysuj drogę konkretnego obiektu: zamówienie w WooCommerce, pobranie do Base, przekazanie do ERP, dokument i etykieta. Przy każdym etapie zapisz identyfikator, czas oraz oczekiwany wynik. Nie zawsze ten sam numer jest widoczny we wszystkich panelach, dlatego potrzebne jest powiązanie identyfikatora źródłowego z docelowym.

REST API, webhook i plik danych opisują różne sposoby komunikacji. API może służyć do cyklicznego pobierania, webhook powiadamiać o zdarzeniu, a plik przekazywać katalog. Jeden proces może wykorzystywać wszystkie te mechanizmy. Middleware jest rolą oprogramowania pośredniczącego, a nie kolejnym formatem danych.

Zachowaj próbkę logu z potrzebnymi identyfikatorami, bez sekretów i zbędnych danych osobowych. Dzięki temu osoba naprawiająca sklep internetowy może odtworzyć kolejność zdarzeń, zamiast zmieniać kilka ustawień jednocześnie.

Sprawdź, czy nadawca rzeczywiście utworzył zdarzenie oraz próbował wysłać je pod właściwy adres. Potem odczytaj status dostarczenia, czas odpowiedzi i log odbiorcy. Brak wpisu może oznaczać zły URL, problem DNS, certyfikat, blokadę albo brak subskrypcji danego zdarzenia. Nie zakładaj od razu błędu kodu sklepu.

Odbiór webhooka i wykonanie operacji biznesowej są osobnymi etapami. Aplikacja może przyjąć zdarzenie, a zadanie zapisujące dokument zatrzyma się później. Potrzebny jest ślad kolejki i wynik przetwarzania, nie tylko kod odpowiedzi serwera.

Dokumentacja Stripe pokazuje znaczenie podpisu weryfikowanego na surowej treści oraz obsługi powtórzeń i zdarzeń poza kolejnością. Dla innego dostawcy stosuj jego schemat podpisu i odpowiedzi. Własny odbiornik powinien weryfikować pochodzenie, trwale zapisać przyjęte zdarzenie i chronić operację biznesową przed niezamierzonym powtórzeniem.

WooCommerce opisuje statusy i logi webhooków; zapis aktywnego webhooka może wysłać ping. Przypadkowy POST do produkcyjnego endpointu płatności nie jest miarodajnym testem i może uruchomić niechciane działanie. Uzgodnij środowisko oraz syntetyczne dane, korzystając z mechanizmu testowego danego dostawcy.

Jeśli przeszkodą jest ochrona sieciowa, sprawdź konkretny tryb. Cloudflare wyjaśnia, że zwykłego Bot Fight Mode nie można ominąć regułą Skip lub Bypass w WAF. Dobór rozwiązania wymaga rozpoznania konfiguracji, a nie wyłączenia całej ochrony sklepu.

Timeout oznacza, że potwierdzenie nie dotarło w oczekiwanym czasie. Nie mówi, czy odbiorca zdążył wykonać operację. Przy dokumencie, przesyłce lub płatności najpierw odczytaj stan po stronie docelowej. Dopiero później podejmuj decyzję o ponowieniu.

HTTP 429 wskazuje ograniczenie liczby lub kosztu żądań. Limity mają różne jednostki i zakresy, dlatego nie można porównywać ich jedną liczbą bez kontekstu.

Base API podaje: "The API request limit is 100 requests per minute." Allegro opisuje limit główny oraz odrębne ograniczenia zasobów, a Shopify wyjaśnia rozliczanie kosztu zapytań. Warunki sprawdzono 12 września 2026.

Po przejściowym błędzie stosuj zasady dostawcy, odstępy między próbami, ograniczenie ich liczby i kontrolę stanu operacji. Błędnej wartości pola nie naprawi wielokrotne wysłanie identycznych danych. Cache dobieraj do rodzaju informacji i dopuszczalnej nieaktualności; status płatności nie powinien automatycznie dziedziczyć zasad cache katalogu. Podnoszenie timeoutu PHP bez wskazania wolnego etapu może jedynie wydłużyć oczekiwanie.

Przy 401 sprawdź token, jego ważność i sposób przekazania. Przy 403 zweryfikuj zakres uprawnień oraz dostęp do zasobu. Odpowiedź 422 wymaga sprawdzenia wartości pól i reguł walidacji, a nie wymiany hasła do konta sprzedawcy.

Zachowaj Trace-Id oraz treść błędu, w szczególności wskazane pole. Przy ofercie porównaj kategorię, wymagane parametry i powiązanie produktu. Nie wstawiaj przypadkowego identyfikatora parametru z innego przykładu. Cena i waluta powinny odpowiadać formatowi konkretnego zasobu.

Dokumentacja zamówień Allegro opisuje dziennik `GET /order/events`. Status `READY_FOR_PROCESSING` może obejmować pobranie lub odbiór osobisty, więc nie oznacza zawsze otrzymanej zapłaty. Zamówienia Smart! odczytuje się przez ten sam mechanizm obsługi zamówień Allegro.

W opisanym przepływie autoryzacji Allegro access token ma ważność 12 godzin. Integracja powinna obsłużyć odnowienie zgodnie z odpowiedzią dostawcy i zachować aktualne dane odświeżania. Nie przenoś tej ważności na wszystkie systemy OAuth.

Po poprawieniu błędu sprawdź jedną uzgodnioną operację i jej rezultat. Masowe ponawianie wystawiania ofert może tworzyć duplikaty. Usunięcie problemu z jednym polem nie potwierdza jeszcze poprawności dostawy, stanu i pozostałych wymagań produktu.

Jeżeli połączenie jest aktywne, ale zamówienie nie przechodzi, sprawdź ustawienia pobierania oraz statusy. Ustal, czy rekord nie został już pobrany pod innym widocznym numerem. Potem porównaj identyfikator produktu i wariantu, metodę dostawy oraz magazyn.

Rozróżniaj token używany do Base API od pary kluczy WooCommerce. Błędny dostęp wymaga sprawdzenia użytkownika, uprawnień i adresu. Natomiast brak konkretnego pola może wynikać z możliwości wtyczki lub mapowania. Nie każdy problem wymaga rotacji kluczy.

Automatyczna akcja ma warunek uruchomienia. Jeśli faktura lub etykieta nie powstała, sprawdź, czy zdarzenie spełniło ten warunek oraz czy dane były kompletne. Sama obecność zamówienia w panelu nie oznacza, że reguła powinna się wykonać. Zobacz także, czy podobnej czynności nie wykonuje już inna wtyczka sklepu.

Przy zadaniach działających w WordPressie sprawdź właściwy harmonogram i log kolejki. Nie wyłączaj WP-Cron bez zweryfikowanego zastępstwa i nie zakładaj, że cały Base jest obsługiwany przez zadania sklepu. Część komunikacji wykonuje system zewnętrzny.

Dokładniejsze kroki znajdziesz w poradniku o problemach z Base w sklepie. Najpierw usuń przyczynę błędnego przepływu, dopiero później rozważaj zmianę narzędzia. Sama liczba zamówień nie dowodzi, że trzeba przenieść obsługę do innego integratora.

Przy połączeniu z ERP zapisz pełną wersję programu, wymagane moduły, podmiot, operatora i magazyn. Częsty błąd diagnostyczny polega na sprawdzaniu danych w innej firmie lub magazynie niż te skonfigurowane w łączniku. Porównaj również typ dokumentu i jego numer źródłowy.

Base Bridge dla Subiekta GT wymaga aktywnej Sfery oraz działającej aplikacji. Sprawdź zgodność i połączenie zgodnie z dokumentacją; nie udostępniaj publicznie SQL jako domyślnej naprawy. Dla nexo PRO potrzebna jest dokumentacja i zgodność dodatku właściwa tej linii, a nie instrukcja Sfery GT.

W Optimie zweryfikuj specyfikację wybranego łącznika i obsługiwane dokumenty. Sam rok wersji nie potwierdza obecności uniwersalnego REST API. Producent enova opisuje WebAPI jako REST z JWT i moduł dodatkowy; warunki licencji należy sprawdzić dla używanej konfiguracji. Nie ma podstaw, by przypisywać każdemu wdrożeniu identyczną dopłatę.

Jeśli znikają polskie znaki, zachowaj oryginalną próbkę i ustal kodowanie nadawcy oraz odbiorcy. Ta sama konwersja uruchomiona w obu kierunkach nie naprawia automatycznie danych, a transliteracja może je zmienić nieodwracalnie. Testuj na kontrolowanej kopii, także dla nazw i adresów z różnymi znakami.

Przy szerszej zmianie użyj planu integracji WooCommerce z ERP: mapa pól, dokumenty, odbiór błędów i odpowiedzialność za aktualizacje.

Najpierw ustal, jak konkretny kanał pobiera dane: przez plik, API czy konektor pośredniczący. Nazwa marketplace nie określa jednego wspólnego formatu dla wszystkich sposobów integracji. Pobierz aktualną specyfikację używanego połączenia i porównaj ją z rzeczywiście wysłaną wersją danych.

Przy pliku sprawdź dostępność adresu, czas wygenerowania, format oraz raport importu. To, że plik otwiera się w przeglądarce, nie potwierdza poprawności identyfikatorów, kategorii i wymaganych pól. Odbiorca może odrzucić część pozycji, więc oddziel błędny cały import od problemu jednego produktu.

Wybierz wadliwe ID i porównaj je z podobną poprawną pozycją. Sprawdź wariant, markę, identyfikatory produktu, cenę, walutę, dostępność i URL strony. Nie zastępuj brakującego GTIN przypadkowym kodem ani nie kopiuj parametru kategorii z innego asortymentu. Wymagania dla zdjęć i tytułów zależą od kanału oraz kategorii.

Po korekcie sprawdź wynik kontrolowanej aktualizacji i raport odbiorcy. Dopiero potem rozszerz poprawkę na podobne rekordy. Zachowaj wersję danych sprzed zmiany, aby móc wskazać, które pole wpłynęło na wynik. W ten sposób nie trzeba jednocześnie przebudowywać całego feedu i tracić możliwości porównania.

Rozpocznij od sprawdzenia, czy dokument nie istnieje już w systemie fakturowym. Przerwa w transmisji potwierdzenia może sprawić, że sklep nadal pokazuje błąd, chociaż faktura została utworzona. Ponowne wysłanie polecenia bez odczytu stanu może stworzyć drugi dokument.

Porównaj kontrahenta, pozycje, ilości, walutę, rabaty i sposób przedstawienia podatku. Różnica kwoty wymaga sprawdzenia danych wejściowych oraz zasad obliczeń obu aplikacji. Nie zmieniaj globalnej metody zaokrągleń tylko po to, aby zniknął jeden komunikat. Uzgodnij rozwiązanie z osobą odpowiedzialną za rozliczenia i sprawdź wpływ na pozostałe dokumenty.

Przy danych kontrahenta uwzględnij kraj i właściwy format identyfikatora. Polski NIP nie jest wzorcem dla każdego zagranicznego nabywcy. Z kolei brak numeru PDF lub załącznika może oznaczać, że dokument czeka na kolejny etap, a nie że należy go wystawić ponownie.

Jeżeli proces obejmuje KSeF, sprawdź osobno stan dokumentu w aplikacji i stan jego dalszego przekazania. Obowiązki oraz konfigurację rozliczeń należy ustalić dla konkretnego przypadku. Samo połączenie API nie potwierdza prawidłowości wszystkich dokumentów.

Na końcu sprawdź regułę dostarczenia faktury klientowi. Wiadomość e-mail, link przy zamówieniu i załącznik są odrębnymi funkcjami. Ustal jednego odpowiedzialnego wykonawcę każdego działania, aby nie wysyłać dokumentu kilkoma automatyzacjami jednocześnie.

Odczytaj komunikat dla konkretnego ID, kraju oraz źródła danych. Porównaj cenę, walutę i dostępność w przesłanym rekordzie ze stroną produktu. Sprawdź także wybrany wariant i to, czy strona jest osiągalna. Ostrzeżenie oraz odrzucenie oferty nie są tym samym stanem.

Ważna zmiana techniczna: Google opisuje harmonogram wycofania Content API, zaktualizowany 10 września 2026. Po sunset 18 sierpnia od 1 września projekty bez aktywnego przedłużenia mogą okresowo otrzymywać HTTP 410. Pełne wyłączenie zapowiedziano na początek 2027, a termin może się zmienić. Kolejne próby nie zastępują przejścia do Merchant API. Przy gotowej platformie sprawdź z dostawcą konektora, kto odpowiada za migrację.

Pomoc Google dotycząca obrazów zapowiada egzekwowanie minimum 500 × 500 pikseli od 31 stycznia 2027. Do tego czasu wskazuje ogólne minima 100 × 100 poza odzieżą i 250 × 250 dla odzieży, z osobnym warunkiem YouTube Shopping na TV. Dlatego najpierw odczytaj dokładny rodzaj komunikatu.

Przy GTIN sprawdź zasady identyfikatorów produktu. Własna marka nie uprawnia automatycznie do pominięcia istniejącego kodu. Nie wymyślaj identyfikatora dla produktu, który go nie ma.

Po zmianie sprawdź stan przetwarzania i wynik w Merchant Center. Aktualizacja danych nie daje gwarantowanego terminu dopuszczenia oferty ani natychmiastowej publikacji wszystkich produktów.

Porównuj potrzebne operacje, a nie samą liczbę dostępnych integracji. Gotowy konektor powinien obsługiwać właściwe wersje, pola, dokumenty i wyjątki. Zapytaj, kto aktualizuje go po zmianie API oraz gdzie zgłasza się problem wynikający z różnicy danych między aplikacjami.

Własne rozwiązanie może być potrzebne przy nietypowym mapowaniu, wielu źródłach lub regułach, których gotowy produkt nie obsługuje. W jego zakresie powinny znaleźć się logi, obsługa błędów, kontrola powtórzeń i dokumentacja. Potrzeba kolejki nie oznacza automatycznie konieczności użycia konkretnego produktu, np. Redis. Technologię dobiera się do procesu i środowiska.

Przy automatyzacji procesów dolicz późniejsze utrzymanie, a nie tylko uruchomienie. Otwarty kod lub bezpłatny komponent nie eliminuje kosztu hostingu, aktualizacji, obserwacji błędów i pracy osoby odpowiedzialnej za przepływ danych.

Na pierwszy kontakt wystarczy adres sklepu lub platforma oraz opis objawu. Jeśli znasz czas zdarzenia, identyfikator zamówienia i nazwę łącznika, dopisz je. Nie musisz przesyłać pełnej bazy, wszystkich logów ani kompletu dostępów przed rozpoznaniem problemu.

Przydatne zgłoszenie opisuje oczekiwany i rzeczywisty wynik, np. brak dokumentu po pobraniu zamówienia. Dodaj informację o ostatniej zmianie: aktualizacji wtyczki, regule statusu, nowym magazynie lub odebranych uprawnieniach. Nie publikuj sekretów w zrzucie ekranu. Potrzebne dane i dostęp przekazuj dopiero uzgodnionym kanałem, w odpowiednim zakresie.

Wycena powinna rozdzielać diagnozę, poprawkę, testy i ewentualny rozwój. Oferta migracji i integracji WooCommerce KC obejmuje różne zakresy połączeń; nie oznacza jednej stałej ceny każdej awarii. Naprawa istniejącego mapowania może być innym zadaniem niż zbudowanie nowego konektora albo przeniesienie platformy.

Po poprawce zapisz, który scenariusz sprawdzono, jaki jest wynik i jak rozpoznać powrót problemu. Warto ustalić także właściciela konfiguracji oraz zakres dalszego wsparcia. Opisz problem z integracją, a kolejny krok można oprzeć na danych z właściwego odcinka procesu.