Webhook to tylko sygnał
Każde zdarzenie kończy się tą samą operacją: zbuduj rekord produktu z aktualnych danych API. Duplikaty i zła kolejność zdarzeń nie psują indeksu.
case study · integracja
Szybka wyszukiwarka produktów oparta o Algolię dla sklepu na platformie Shoper, która nie ma gotowej integracji. Własna usługa synchronizacji, podpowiedzi podczas pisania i strona wyników z filtrami, osadzone w szablonie sklepu jednym plikiem.
01 / wyzwanie
Sklep potrzebował wyszukiwania, które wybacza literówki, zna synonimy, pokazuje wyniki w trakcie pisania i pozwala filtrować jak w dużych sklepach. Shoper nie ma integracji z Algolią, więc całość trzeba było zbudować: od pobierania katalogu z REST API po komponent osadzony w szablonie. Do tego część zachowań API nie jest opisana w publicznej dokumentacji.
02 / założenia
Prace szły w podejściu Spec-Driven Development: specyfikacja zaakceptowana przed pierwszą linią kodu, a każda faza kończyła się podsumowaniem i commitem. Każde twierdzenie o API Shopera miało w specyfikacji status, a założenia zamieniały się w fakty dopiero po sprawdzeniu na prawdziwych odpowiedziach.
Każde zdarzenie kończy się tą samą operacją: zbuduj rekord produktu z aktualnych danych API. Duplikaty i zła kolejność zdarzeń nie psują indeksu.
Frontend dostaje wyłącznie klucz tylko do wyszukiwania. Build kończy się błędem, jeśli w pliku pojawi się coś, co wygląda na klucz admin.
Webhooki zamówień niosą dane osobowe. Usługa zapisuje z nich wyłącznie identyfikatory, a analityka Algolii startuje dopiero po zgodzie klienta sklepu.
Atomowa podmiana indeksu, blokada przed jego wyczyszczeniem i powrót do natywnej wyszukiwarki Shopera przy awarii Algolii. Jedna flaga wyłącza integrację.
03 / architektura
Usługa synchronizacji w jednym kontenerze przyjmuje webhooki, kolejkuje je i odświeża produkty. Co 20 minut dociąga zmiany po dacie modyfikacji, a raz na dobę porównuje cały katalog z indeksem i naprawia różnice. Przeglądarka rozmawia z Algolią bezpośrednio.
04 / co wdrożono
05 / efekt
Zrzuty z prawdziwego sklepu na szablonie Storefront z katalogiem demonstracyjnym. Kliknij zrzut, aby go powiększyć.


06 / co pokazało prawdziwe API
Weryfikacja na żywym sklepie i żywej Algolii wychwyciła zachowania, które przy pracy „z pamięci” skończyłyby się cichymi błędami na produkcji.
| Obszar | Co się okazało | Rozwiązanie |
|---|---|---|
| Paginacja Shopera | Strona większa niż 50 pozycji po cichu wraca do 10. | Klient zawsze pobiera maksymalnie 50. |
| Limity API | Odpowiedź 429 przychodzi jako HTML, bez Retry-After. | Dławienie według nagłówków X-Shop-Api-* i własny backoff. |
| Filtry API | Nieznana składnia filtra jest ignorowana i zwraca cały katalog. | Każdą składnię sprawdza test „data z przyszłości daje 0 wyników”. |
| Webhooki | X-Webhook-Id to ID konfiguracji, nie dostawy; zdarzenia potrafią przyjść razem minutę później. | Deduplikacja po treści i idempotentne odświeżanie z API. |
| Usunięte zamówienie | Pozycji nie da się już pobrać z API, a stan wraca bez zmiany daty modyfikacji. | ID produktów brane z treści webhooka, awaryjnie dobowa synchronizacja kontrolna. |
| Podmiana indeksu | Atomowa podmiana w SDK Algolii zawiesza się, gdy indeks jeszcze nie istnieje. | Pierwszy import zapisuje wprost, kolejne podmieniają z limitem czasu. |
| Połączenie z Algolią | SDK nie przełącza się na zapasowe hosty przy błędzie DNS. | Własne ponawianie błędów połączenia. |
| Szablon Storefront | Zgody obsługuje inne API niż w starszym szablonie, a sklep ma Service Workera. | Integracja z modułem zgód Storefront i wersjonowanie adresu skryptu. |
07 / wskaźniki
deferWskaźniki pochodzą ze środowiska testowego: sklep Shoper (Storefront) z katalogiem demonstracyjnym 80 produktów i aplikacja Algolia na planie darmowym. Nie są to dane biznesowe klienta. Wpływ na konwersję i liczbę wyszukiwań bez wyników mierzy się po uruchomieniu na produkcji w Algolia Analytics.
08 / proces
technologie
co dalej
Przed produkcją zostają decyzje biznesowe: plan Algolii, lista synonimów, zakres analityki i reguła dostępności. Architektura jest przygotowana na kolejne kroki: rekomendacje, personalizację, wyszukiwanie w treściach bloga i indeksy dla kolejnych języków.
następny krok
Opisz, co chcesz osiągnąć. Wrócę z konkretną propozycją, wyceną i planem wdrożenia.