Jak jeden błąd w paginacji API zgubił kilkadziesiąt zamówień przez 6 tygodni

Kilka tygodni temu dostałem telefon od klienta. Marek prowadzi firmę dystrybucyjną - sprzedaje przez kilka kanałów jednocześnie: własny sklep, Allegro, Kaufland, Morele. Wszystko spina w Base. Mój skrypt automatycznie przenosi zamówienia między jego kontami i wystawia dokumenty magazynowe (WZ).

“Słuchaj, coś mi się nie zgadza w rozliczeniach” - powiedział. “Brakuje mi kilku zamówień z ostatniego miesiąca.”

Sprawdziłem logi. Skrypt działał bez błędów. Zero czerwonych linii, zero wyjątków. Wszystko wyglądało idealnie.

Kiedy “działa bez błędów” nie znaczy “działa dobrze”

Problem z integracjami API jest taki, że mogą tracić dane po cichu. Nie dostajesz żadnego errora. System nie krzyczy. Po prostu część rekordów nie dociera z punktu A do punktu B, a Ty dowiadujesz się o tym dopiero gdy klient dzwoni z pytaniem o brakujące faktury.

W przypadku Marka sprawa wyglądała tak: Base ma API, przez które pobieram listę zamówień. Standardowa paginacja - pobieram 100 zamówień, zapamiętuję najwyższe ID, następnym razem zaczynam od tego ID w górę.

Brzmi prosto i logicznie, prawda?

Pułapka ukryta w sortowaniu

Okazuje się, że API Base ma pewną nieoczywistą cechę. Gdy filtrujesz zamówienia po dacie, wyniki są sortowane po dacie potwierdzenia zamówienia - a nie po ID zamówienia. To dwa różne timeline’y.

Wyobraź sobie taką sytuację: zamówienie z Allegro wpada do systemu o 14:00 i dostaje ID 1000. Zamówienie z Kaufland wpada o 14:01 i dostaje ID 1001. Ale zamówienie z Allegro zostaje potwierdzone o 14:05, a to z Kaufland - o 14:02.

Gdy pobierasz batch 100 zamówień posortowanych po dacie potwierdzenia, zamówienie z Kaufland (ID 1001) jest wcześniej niż zamówienie z Allegro (ID 1000). Moja paginacja brała najwyższe ID z batcha (1001) i następny batch zaczynała od 1002. Zamówienie 1000? Przepadło.

Skala problemu

Gdy to odkryłem i przejrzałem dane wstecz, okazało się że skrypt gubił zamówienia od ponad sześciu tygodni. Łącznie brakowało kilkudziesięciu zamówień. Nie były to jakieś drobne kwoty - suma sięgała kilku tysięcy złotych.

Najgorsze? Problem nasilał się proporcjonalnie do liczby kanałów sprzedaży. Im więcej integracji (Allegro, Kaufland, Morele, sklep własny), tym więcej zamówień wpada w różnej kolejności i tym więcej “dziur” powstaje między ID a datą potwierdzenia.

Z jednym kanałem sprzedaży problem praktycznie nie występuje. Z dwoma - rzadko. Ale z sześcioma kanałami na jednym koncie? Statystycznie gwarantowane.

Jak to naprawiłem

Zamiast paginować po ID zamówień (które jest zależne od sortowania), przeszedłem na filtrowanie po dokumentach WZ w Base. Dokumenty WZ są wystawiane w momencie realizacji zamówienia i mają jednoznaczną datę. Nie ma rozbieżności między kolejnością tworzenia a kolejnością potwierdzenia.

Dodatkowo dodałem mechanizm audytu - co kilka dni skrypt porównuje liczbę zamówień w źródle z liczbą wystawionych dokumentów. Jeśli się nie zgadza, dostaję powiadomienie.

Czego możesz się z tego nauczyć?

1. Nie ufaj paginacji po ID gdy filtrujesz po dacie. To najczęstsza pułapka w API systemów e-commerce. Jeśli API sortuje wyniki inaczej niż po ID - paginacja po ID będzie gubić rekordy.

2. “Zero błędów w logach” to nie to samo co “wszystko działa”. Ciche błędy danych są gorsze niż głośne crashe. Crash naprawiasz od razu. Brakujące rekordy odkrywasz po tygodniach.

3. Zawsze buduj mechanizm weryfikacji. Nie polegaj na tym, że “skrypt działa od miesiąca bez problemów”. Dodaj porównanie ilościowe: ile rekordów powinno być vs ile jest. To 10 linii kodu, które mogą zaoszczędzić tygodnie szukania.

4. Testuj z realnymi wolumenami i wieloma kanałami. Paginacja, która działa idealnie na 50 zamówieniach z jednego sklepu, może się wysypać przy 500 zamówieniach z sześciu kanałów. Skalowanie ujawnia błędy, które na małych danych są niewidoczne.

Jeśli masz integrację, która “po prostu działa” od dłuższego czasu - może warto sprawdzić, czy na pewno niczego nie gubi po drodze. Czasem najdroższe błędy to te, o których nie wiesz.

Potrzebujesz audytu swoich integracji? [https://optymo.pl/kontakt/](Napisz do mnie) - sprawdzę czy Twoje dane płyną tam, gdzie powinny.