Ekspertyza · Sklepy internetowe

Sklep, w którym katalog jest odczytywany w czasie rzeczywistym, a nie raz skopiowany i zapomniany.

Budujemy sklepy i, ponad nimi, warstwę, której zwykle brakuje: agent odpowiadający klientowi odczytuje cenę i stan magazynowy bezpośrednio ze sklepu, w momencie pytania, i odmawia wymyślania nieopublikowanej ceny.

Omów projekt

Już zbudowaneMożna to sprawdzić z zewnątrz już teraz, bez pytania nas. Nasz punkt katalogu dostarczony dystrybutorowi odpowiada 200 i mówi „154 wyniki”; publiczny interfejs jego sklepu, zapytany bezpośrednio, zwraca nagłówek `x-wp-total: 154`. Ta sama liczba, dwa niezależne źródła, sprawdzone 06.09.2026. Druga implementacja jest zintegrowana z platformą asystentów: usługa `storeCatalog.service.js` plus trzy narzędzia, które agent może wywołać. Zastrzeżenie, które trzeba powiedzieć: ta druga ścieżka stoi na gałęzi rozwojowej (`feat/store-catalog-global`, `481cfa0`) i nie jest jeszcze scalona z pniem — więc jest dostarczona dla klientów, których podłączyliśmy, a nie uruchomiona domyślnie dla wszystkich.

Większość „integracji katalogu” to tak naprawdę eksport. Ktoś pobiera produkty raz, wkleja je do pliku, a od tego momentu agent rozmawiający z klientem czyta stare zdjęcie sklepu. Działa to bez zarzutu aż do pierwszej zmiany ceny albo pierwszego wyczerpanego produktu — a wtedy myli się z przekonaniem, co jest gorsze niż milczenie.

My czytamy sklep w momencie pytania. Dla sklepów na WooCommerce istnieje publiczny interfejs — Store API — który zwraca produkty, ceny i dostępność bez kluczy, bez konta, bez zainstalowanego pluginu. Adres to `/wp-json/wc/store/v1/products`, prosimy o 100 produktów na stronę, z maksymalnym czasem oczekiwania 20 sekund, i z nagłówka odpowiedzi dowiadujemy się, ile jest stron, zamiast zgadywać. Pierwszą stronę pobieramy samodzielnie, resztę równolegle.

Część, która oddziela poprawną integrację od takiej, która tylko wygląda na poprawną, to tłumaczenie ceny. Store API nie zwraca „129,90”; zwraca ciąg cyfr w jednostkach mniejszych oraz osobno liczbę miejsc dziesiętnych waluty. Kto z przyzwyczajenia dzieli przez 100, popełnia cichy błąd dla każdej waluty, która nie ma dwóch miejsc dziesiętnych. I jeszcze ważniejsze: cena zero nie znaczy za darmo, tylko nieopublikowana. U nas zero staje się „cena na zapytanie — do potwierdzenia przez współpracownika”, a agent dostaje wyraźną instrukcję, by niczego nie wymyślać. Widać to już teraz w publicznej odpowiedzi punktu katalogowego.

Na katalog nakładają się pozostałe elementy, każdy ze swoim rzeczywistym stanem: koszyk i wysyłka zamówienia do systemu zarządzania restauracji lub sklepu, płatność przez interfejs MAIB dla handlowców lub przez Stripe, odzyskiwanie porzuconych koszyków, śledzenie stanu zamówienia z synchronizacją co 15 minut. Tam, gdzie nie mamy działającej integracji — a są takie przypadki — poniżej napisz dokładnie, które.

Co obejmuje

Praca, komponent po komponencie

Katalog odczytywany w czasie rzeczywistym, bez kluczy i bez pluginu

Dla WooCommerce używamy Store API, publicznego interfejsu sklepu: `/wp-json/wc/store/v1/products`, 100 produktów na stronę, maksymalny czas oczekiwania 20 sekund, własny identyfikator klienta w nagłówku i akceptacja wyłącznie kodu 200. Liczbę stron odczytujemy z nagłówka `x-wp-totalpages`, a łączną liczbę produktów z `x-wp-total` — nie stronicujemy aż do zdrady. Pierwsza strona pobiera się samodzielnie, reszta równolegle, z limitem 30 stron. Niczego nie instaluje się w sklepie i nie otrzymujemy kluczy handlowca.

Cena przetłumaczona poprawnie, a zero traktowane jako nieopublikowane

Store API zwraca cenę jako ciąg w jednostkach mniejszych, plus liczbę miejsc dziesiętnych waluty. Dzielimy przez dziesięć do potęgi tej liczby, a nie na sztywno przez 100 — inaczej każda waluta z inną liczbą miejsc dziesiętnych wyjdzie błędnie i nikt tego nie zauważy. Zero staje się `null`, a w odpowiedzi pojawia się „cena na żądanie — potwierdza to zespół”, wraz z wyraźną instrukcją daną agentowi, by nie wymyślał i poprosił o potwierdzenie innej osoby z zespołu. Cena wychodzi w dwóch formach jednocześnie: tekst gotowy do wyświetlenia w interfejsie i liczba do logiki po stronie zaplecza.

Trzy narzędzia, które agent może wywołać

W platformie asystentów katalog jest udostępniony jako trzy wbudowane narzędzia — wyszukiwanie po słowach, dopasowanie po urządzeniu lub przypadku użycia oraz pobranie produktu po identyfikatorze. Agent widzi je pod nazwami `catalog_cauta`, `catalog_potrivire` i `catalog_produs`, każde z własnymi zadeklarowanymi parametrami. Gdy platforma sklepu nie jest tą oczekiwaną albo brakuje adresu, narzędzie odmawia wprost zamiast zwracać pustą listę, którą można by zinterpretować jako „nie mamy produktu”.

Słowa łączące nie psują wyniku

„Filtr do wody” wyszukiwane dosłownie dopasowuje wszystko, co zawiera „do”. W dostarczonym punkcie katalogu i w wyszukiwaniu z widżetu głosowego odcinamy listę pustych słów — `i`, `lub`, `do`, `z`, `przy`, `ze`, `na`, `w`, `dla` — i jeśli po odcięciu nie zostaje nic użytecznego, wracamy do słów dłuższych niż dwie litery. Dopasowanie częściowe ma próg: produkt trafia do wyników tylko wtedy, gdy obejmuje co najmniej połowę pozostałych słów.

Gdy sklep nie ma interfejsu, czytamy stronę

Nie każdy sklep ma Store API. Dla pozostałych mamy ekstraktor, który otwiera strony listowania i czyta z nich karty produktów, z budżetem zapisanym w kodzie: maksymalnie 20 stron listowania, 200 produktów, 24 strony szczegółów, 50.000 znaków HTML na stronę, 5 sekund na żądanie i termin 45 sekund na całą operację. Najpierw czyta strukturalne dane typu produkt ze strony, potem karty, a potem metadane udostępniania — w tej kolejności, ponieważ pierwsze źródło to to, które sklep zapisał celowo.

Świeżość z zapisanymi limitami, nie z nadzieją

Katalog jest przechowywany w pamięci przez 10 minut na sklep, a jednoczesne żądania dla tego samego sklepu łączą się w jedno, aby dziesięć osób pytających w tym samym momencie nie powodowało dziesięciu pobrań. Na publicznym punkcie katalogu odpowiedź niesie też instrukcję cache dla sieci dystrybucji: 5 minut świeże, jeszcze 10 minut serwowane stare, podczas gdy odświeżanie trwa w tle. Liczba zwracanych wyników jest ograniczona do 20, z wartością domyślną 6.

Zamówienie, koszyk i połączenie z systemem zarządzania

Koszyk, wysłanie zamówienia i przekazanie go do systemu zarządzania klienta są funkcjami oddzielnymi, a nie formularzem. Istnieje też odzyskiwanie porzuconych koszyków, zamówienie przez rozmowę i śledzenie statusu zamówienia, z dwoma zadaniami zaplanowanymi, które uruchamiają się co 15 minut — jedno synchronizuje wynik zamówień, drugie uzupełnia statusy w systemie zarządzania z okna dwóch dni wstecz i jednego dnia naprzód.

Płatności: co działa, a co nie

Działa i jest w kodzie: interfejs MAIB dla handlowców — token, a potem żądanie płatności, z poświadczeniami każdego sklepu odczytywanymi z bazy danych i funkcją aktywowaną jawnie — oraz Stripe, z kwotą przeliczoną na jednostki mniejsze i wpływem zapisanym w ewidencji. To, co NIE działa, żeby nie było niespodzianek: Paynet, Netopia i mobilPay nie mają implementacji, a kod odmawia wprost, gdy są żądane. Trasa Moldindconbank jest szkieletem, który zwraca błąd bez poświadczeń. Traktujemy to w projekcie jako zadanie, a nie jako istniejącą integrację.

Agent nie wymyśla, gdy sieć pada

Jeśli zapytanie do sklepu się nie powiedzie, narzędzie nie zwraca pustej listy — zwraca komunikat, który mówi agentowi, by nie formułował odpowiedzi o katalogu. Różnica jest ważna: pusta lista tłumaczy się jako „nie mamy”, a błędnie wypowiedziane „nie mamy” traci zamówienie tak samo pewnie jak błędna cena.

Jak to wygląda

Trasa, krok po kroku.

Sprawdzenie sklepu, przed jakąkolwiek obietnicą

Pytamy publiczny interfejs jednym żądaniem, z maksymalnym czasem oczekiwania 15 sekund, i czytamy z nagłówka, ile ma produktów. Z tej odpowiedzi wiemy, czy żywa ścieżka jest możliwa, ile jest produktów i jak kompletna jest informacja o cenie. Jeśli sklep nie odpowiada, mówimy to przed ofertą, a nie podczas wdrażania.

Podłączenie katalogu i pierwsze przejście przez ceny

Dostarczamy połączenie, plus przejście przez produkty z ceną zero lub bez ceny — to niemal zawsze prawdziwe produkty, nie błędy, a sposób, w jaki obsługuje je agent, jest decyzją sklepu, nie naszą. Dostarczamy też dokładny tekst, którym agent odmawia podania nieopublikowanej ceny.

Narzędzia agenta i ich ograniczenia

Konfigurujemy wyszukiwanie, dopasowanie i pobieranie produktu, każde z maksymalną liczbą wyników ustaloną wspólnie. Tu zapisuje się też własne synonimy sklepu — jak klient nazywa produkt, a jak nazywa go katalog. Bez tego kroku wyszukiwanie jest poprawne technicznie i bezużyteczne praktycznie.

Zamówienie, płatność i połączenie z systemem magazynowym

Buduje się to w tej kolejności, a każdy element wchodzi dopiero po sprawdzeniu rzeczywistego dostępu do systemu po drugiej stronie. Dla płatności startuje się tylko od jednego dostawcy, dla którego mamy działającą implementację; resztę traktuje się jako nową pracę, z wcześniej opisanym ryzykiem, a nie jako checkbox w ofercie.

Przekazanie, z listą braków

Przekazujemy adresy, konfiguracje, limity zapisane w kodzie i listę tego, co nie jest objęte. Na przykład: publiczny punkt katalogu dostarczony nie ma maksymalnego czasu oczekiwania na żądanie do sklepu — jeśli sklep odpowiada bardzo wolno, żądanie się wydłuża. To jest realny brak, wpisujemy go na listę przekazania i do planu napraw, nie do notatki wewnętrznej.

Sklep, agent odpowiadający klientom, system zarządzania i dostawca płatności — cztery osobne systemy, z jednym źródłem prawdy dla ceny: sklep, czytany w chwili pytania.

Dane

Czego dotykamy, gdzie to leży i jak długo zostaje

Pytania, które zadaje każdy, kto ma inspektora ochrony danych — postawione tutaj, zanim on je zada.

Dane katalogu: Nazwa, krótki opis, bieżąca cena i cena listowa, dostępność, obraz, kategoria i adres produktu — wszystko odczytywane z publicznego interfejsu sklepu, który i tak publikuje je każdej osobie odwiedzającej. Nie kopiujemy bazy danych sklepu i nie prosimy o klucze handlowe. Zostają po stronie klienta; my odczytujemy je na żądanie.
Gdzie są przechowywane i jak długo: Katalog jest trzymany w pamięci procesu przez 10 minut na sklep i znika po ponownym uruchomieniu — u nas nie istnieje jego trwała kopia. Na publicznym punkcie katalogu sieć dystrybucyjna trzyma go jeszcze 5 minut jako świeży i 10 minut jako starą wersję podczas odświeżania. Zamrożony eksport, gdy jest jedyną techniczną opcją, jest wyraźnie oznaczony jako migawka z datą, a nie jako żywe źródło.
Dane rozmowy i zamówienia: To, o co pyta klient, i to, co zamawia, przechodzą przez platformę rozmowy i, w razie potrzeby, do systemu magazynowego sklepu. Kto ma dostęp, jak długo są przechowywane i co jest usuwane, ustala się dla projektu, z rejestrem przetwarzania zapisanym przed startem, nie po pierwszym incydencie.
Poświadczenia płatności: Poświadczenia handlowe są przechowywane w bazie danych platformy, per sklep, i są odczytywane tylko wtedy, gdy funkcja płatności jest wyraźnie aktywowana dla tego sklepu. Nie trafiają na publiczną stronę i nie przechodzą przez rozmowę. Konfigurację konta handlowego wykonuje posiadacz konta, nie my.
Czego nie dotykamy: Nie przejmujemy danych karty. Nie prosimy o dostęp administratora do sklepu do odczytu katalogu — używany interfejs jest publiczny. Gdy projekt rzeczywiście wymaga dostępu uprzywilejowanego, prosi się o niego osobno, z zapisanym celem, i nie trzyma się go „na wszelki wypadek".

Przykład

Katalog 154 produktów, odczytywany w momencie pytania

Sytuacja

Dystrybutor kawy i wody z Kiszyniowa, ze sklepem na WooCommerce i agentami, którzy odpowiadają klientom tekstowo i przez telefon. Katalog zmienia się często; skopiowana raz lista staje się błędna w ciągu kilku dni, a błędna cena podana przez telefon nie zostaje cofnięta.

Co zbudowaliśmy

Zamontowaliśmy osobny punkt katalogu, który odpyta publiczny interfejs sklepu: 100 produktów na stronę, liczba stron odczytywana z nagłówka, pierwsza strona pobierana osobno, a reszta równolegle, limit 30 stron. Cena jest przeliczana z jednostek mniejszych według liczby miejsc dziesiętnych zadeklarowanej przez sklep; zero staje się „cena na zapytanie — do potwierdzenia przez zespół”, z pisemną instrukcją dla agenta, aby nie wymyślać. Wyszukiwanie usuwa słowa łączące i wymaga, aby produkt trafił co najmniej w połowę pozostałych słów, zanim pojawi się w wynikach. Odpowiedź jest trzymana 10 minut w pamięci i 5 minut w sieci dystrybucji, z kolejnymi 10 minutami serwowanymi w wersji starej, podczas gdy jest odświeżana. Agenci głosowi wywołują go jako zwykły punkt webowy, nie jako specjalną integrację.

Co z tego wyszło

Sprawdzone 06.09.2026, w dwóch niezależnych żądaniach: punkt katalogu odpowiada „154 wyniki” i wyświetla pierwszy produkt z ceną i dostępnością, a drugi z „cena na zapytanie — do potwierdzenia przez zespół”; zapytany bezpośrednio interfejs sklepu zwraca w nagłówku `x-wp-total: 154`. Ta sama liczba z dwóch źródeł, które nie znają się nawzajem — to jest weryfikacja, nie nasza deklaracja.

Czego nie mówi ten przypadek

Dostarczony punkt katalogu nie ma maksymalnego czasu oczekiwania na żądanie do sklepu: jeśli sklep odpowiada bardzo wolno, żądanie się wydłuża zamiast czysto upaść. To realny brak, zauważony przy ponownym czytaniu kodu, i znajduje się na liście poprawek — nie na liście funkcji. Osobno: filtr słów pustych opisany wyżej jest aktywny w dostarczonym punkcie i w wyszukiwaniu w widżecie głosowym; w wersji wbudowanej w platformę nie został jeszcze przeniesiony, więc tam wyszukiwanie z wieloma słowami łączącymi daje szersze wyniki.

Pytania

O co pytają ludzie, zanim zadzwonią

Co oznacza „żywy katalog” i jak sprawdzam, że to nie są puste słowa?

Oznacza to, że agent czyta sklep w momencie pytania. Sprawdza się to w dwóch żądaniach, bez nas: nasz punkt katalogu dla dystrybutora odpowiada „154 wyniki”, a publiczny interfejs jego sklepu, zapytany bezpośrednio, zwraca w nagłówku `x-wp-total: 154`. Ta sama liczba, dwa niezależne źródła, tego samego dnia. Katalog skopiowany raz nie może tego zrobić — rozjeżdża się przy pierwszej zmianie.

Czy muszę dawać wam klucze lub dostęp do sklepu?

Do odczytu katalogu na WooCommerce — nie. Store API to publiczny interfejs sklepu: te same dane, które widzi każda odwiedzająca osoba, podane w formacie czytelnym dla programu, bez klucza handlowego i bez instalacji wtyczki. Komentarz jest zapisany w naszym kodzie właśnie po to, żeby się nie zgubił. Uprzywilejowanego dostępu żądamy tylko tam, gdzie funkcja rzeczywiście go wymaga — na przykład przy wysyłaniu zamówień do systemu zarządzania — i wtedy z zapisanym celem.

Co dzieje się z produktami bez ceny?

Są traktowane jako nieopublikowane, a nie jako darmowe. W interfejsie sklepu brak ceny przychodzi jako zero, a naiwna integracja pokazuje „0 MDL”. U nas zero staje się „cena na zapytanie — do potwierdzenia przez zespół”, a agent dostaje wyraźną instrukcję, aby nie wymyślać cyfry i poprosić o potwierdzenie od człowieka. Widać to w odpowiedzi publicznej: drugi produkt z listy pojawia się dokładnie tak.

Jak świeża jest cena, konkretnie?

Maksymalnie 10 minut starości na poziomie platformy, na sklep, a równoczesne żądania dla tego samego sklepu łączą się w jedno pobranie. Na publicznym punkcie katalogu sieć dystrybucji serwuje przez 5 minut wersję świeżą i przez kolejne 10 minut wersję starą, podczas gdy odświeża ją w tle. Wartości są konfigurowalne per projekt; są zapisane jako zmienne, nie ukryte.

Mój sklep nie jest na WooCommerce. Co robicie?

To zależy od tego, co wystawia. Jeśli ma własny interfejs, czytamy go jak każdy inny. Jeśli nie ma nic, mamy ekstraktor, który otwiera strony listowania i czyta karty produktów, z budżetem zapisanym w kodzie: 20 stron, 200 produktów, 5 sekund na żądanie, 45 sekund limit czasu. Najpierw czyta dane strukturalne ze strony, potem karty, potem metadane udostępniania. To uczciwe rozwiązanie zapasowe, nie równoważne: sklep, który zmieni motyw, może zepsuć ekstraktor, a interfejs — nie.

Jakie płatności możecie zintegrować już teraz?

Funkcjonalnie i w kodzie: interfejs MAIB dla sprzedających — pobranie tokenu, potem żądanie płatności, z poświadczeniami każdego sklepu czytanymi z bazy danych i funkcją aktywowaną jawnie — oraz Stripe, z kwotą przeliczoną na jednostki mniejsze i zaksięgowaniem zapisanym w ewidencji. To, co nie jest funkcjonalne, powiedziane przed umową: Paynet, Netopia i mobilPay nie mają implementacji, a kod odmawia wprost, gdy są żądane; ścieżka Moldindconbank to szkielet, który zwraca błąd bez poświadczeń. Każde z nich można zbudować, ale wchodzi jako nowa praca, z własnym ryzykiem.

Czy agent może wymyślić produkt, którego nie macie?

Być może, jeśli tego nie powstrzymasz — a tym zajmujemy się my. Trzy bariery: nieopublikowana cena przychodzi z pisemną instrukcją, by nie zgadywać; niewłaściwa platforma albo brak adresu sprawiają, że narzędzie odmawia wprost, a nie zwraca pustą listę; a awaria sieci zwraca komunikat, który mówi agentowi, by nie formułował odpowiedzi o katalogu. Różnica między „pustą listą” a „nie mogłam przeczytać” to różnica między utraconym zamówieniem a odłożonym o jedną frazę.

Dlaczego ma znaczenie, kto dzieli przez 100?

Ponieważ interfejs nie wysyła „129,90”. Wysyła ciąg cyfr w jednostkach mniejszych oraz osobno liczbę miejsc dziesiętnych waluty. Dzielenie przez 100 jest poprawne dla walut z dwoma miejscami dziesiętnymi i po cichu błędne dla pozostałych — nikt nie dostaje błędu, tylko złe liczby. My dzielimy przez dziesięć do potęgi liczby zadeklarowanej przez sklep. To jedna linia kodu i dokładnie ten rodzaj linii, po której widać, czy ktoś przeczytał dokumentację, czy zgadywał.

Czego nie przyjmujecie na siebie?

Nie przejmujemy danych karty i nie konfigurujemy konta sprzedawcy zamiast osoby uprawnionej. Nie gwarantujemy, że ekstraktor stron wytrzyma zmianę motywu sklepu — dlatego preferujemy interfejs, gdy istnieje. Nie obiecujemy wzrostu sprzedaży; to, co możemy pokazać, to że liczba podana przez agenta zgadza się z liczbą w sklepie, w tym samym dniu. I nie przedstawiamy jako integracji czegoś, co w kodzie jest szkieletem: powyższa lista mówi, czym one są.

Na czym opierają się powyższe stwierdzenia (18 źródeł)

Dostarczony punkt katalogowy odpowiada 200 i mówi „Z katalogu <sklep> (154 wyniki, pierwsze 2)”, z drugim produktem oznaczonym „cena na zapytanie — potwierdzana przez zespół”https://coffywater-ai.vercel.app/api/catalog?limit=2&scurt=1 · 2026-09-06
Publiczny interfejs tego samego sklepu zwraca `x-wp-total: 154` i `x-wp-totalpages: 154` — ta sama liczba co punkt katalogowy, z niezależnego źródłahttps://coffywater.md/wp-json/wc/store/v1/products?per_page=1 · 2026-09-06

16 z nich to kod i pliki z naszych repozytoriów. Nie publikujemy ich nazw ani numerów linii: razem, na jednej stronie, opisałoby to zbyt dokładnie, jak zbudowane są systemy, które nie należą tylko do nas. Przechodzimy je razem z Tobą, w repozytorium, na życzenie — weryfikacja pozostaje możliwa, tylko odbywa się w rozmowie.

Jak pracujemy Wszystkie usługi

Co chcesz, żeby działało lepiej?

Opowiedz nam o swoim procesie. Wspólnie ustalimy, co warto zbudować, co da się połączyć i jak sprawdzimy wynik.

Porozmawiajmy