Instrukcja obsługi modułu
Astrabit XML Integrator dla PrestaShop
Konfiguracja i codzienna obsługa importu hurtowni: od instalacji zakupionych paczek, przez produkty, warianty i wycenę, po dostępność, harmonogram oraz diagnostykę.
1. Wprowadzenie
Astrabit XML Integrator pobiera ofertę hurtowni do PrestaShop i aktualizuje powiązane produkty, warianty, ceny, dostępność oraz zdjęcia. Każda hurtownia ma własną konfigurację, mapowania i historię importów.
Katalog
Tworzenie i aktualizacja produktów oraz wariantów.
Wycena
VAT, narzuty i zaokrąglanie cen.
Mapowania
Przypisywanie kategorii i cech dostawcy.
Automatyzacja
Import paczkowy, harmonogram i historia.
Moduł bazowy i paczki hurtowni
Moduł bazowy zawiera wspólny panel i mechanizmy importu. Paczka integracji dodaje obsługę konkretnego dostawcy: odczyt jego danych, reguły grupowania i dodatkowe ustawienia. Poszczególne integracje są nabywane osobno i instalowane w panelu modułu.
Rozszerzenie pliku nie określa całej jego struktury. Paczka odczytuje format przygotowany dla danego dostawcy; moduł nie służy do dowolnego mapowania każdego pliku XML, CSV lub Excel bez odpowiedniej integracji.
2. Wymagania i przygotowanie
| Element | Wymaganie / zalecenie |
|---|---|
| PrestaShop | Od 1.7.6.4; linie 1.7, 8 i 9 zgodnie z wymaganiami używanej paczki i środowiska sklepu. |
| PHP | Od 7.2. Wersja PHP musi być także obsługiwana przez daną wersję PrestaShop. |
| Rozszerzenia PHP | cURL, DOM, GD, Mbstring, ZIP, OpenSSL i XMLReader. |
| Połączenie | Dostęp serwera do źródła danych, API i serwerów zdjęć dostawcy. Wymagane poprawne certyfikaty HTTPS. |
| Zapis plików | Proces PHP musi móc zapisywać pliki robocze modułu, paczki integracji oraz zdjęcia produktów. |
| Harmonogram | Dostęp do CRON w hostingu, jeżeli aktualizacje mają odbywać się automatycznie. |
Wersja bazowa 3.3.8 wraz z rozdzieleniem magazynów VIVAB2B była sprawdzana na PrestaShop 1.7.6.4 i PHP 7.2. Niestandardowy motyw, moduły magazynowe i inne modyfikacje sklepu wymagają kontroli na miejscu.
- Przygotuj kopię bazy danych i plików sklepu.
- Uzyskaj od hurtowni aktualne źródło, dane dostępowe i zasady cen netto/brutto.
- Ustal kategorię docelową, stawkę VAT i sposób przeliczania cen.
- Sprawdź limity pobierania pliku narzucone przez dostawcę.
- Przeznacz kilka produktów na import testowy przed uruchomieniem całej oferty.
3. Instalacja modułu bazowego
- W panelu PrestaShop otwórz Moduły → Menedżer modułów i skorzystaj z opcji wgrania modułu.
- Wskaż instalacyjny ZIP modułu bazowego Astrabit XML Integrator. Nie wybieraj w tym miejscu ZIP-a samej hurtowni.
- Po instalacji otwórz konfigurację modułu lub przejdź do Katalog → Integracje XML.
- Otwórz Pakiety integracji i zainstaluj zakupioną paczkę hurtowni, zgodnie z kolejnym rozdziałem.
- Dodaj hurtownię, zapisz połączenie i wykonaj import testowy.
Jeżeli otrzymana paczka zawiera katalog pliki-do-podmiany, jest to zestaw do wdrożenia zgodnie z dołączoną instrukcją. Jego zawartość wgrywa się do katalogu głównego sklepu, scalając katalogi. Nie jest to ZIP przeznaczony bezpośrednio do formularza instalacji paczki hurtowni.
4. Dodawanie paczek integracji
- Otwórz konfigurację modułu i wybierz Pakiety integracji.
- W polu Paczka integracji Astrabit (.zip) wskaż otrzymany plik hurtowni.
- Kliknij Zainstaluj lub zaktualizuj integrację. Moduł sprawdzi podpis, zawartość oraz zgodność wersji.
- Sprawdź nazwę i wersję na liście Zainstalowane pakiety.
- Wybierz Dodaj hurtownię przy odpowiedniej integracji i skonfiguruj jej połączenie.
Instalacja paczki udostępnia typ integracji. Dopiero dodanie hurtowni tworzy konfigurację z własnym źródłem, narzutem i mapowaniami. Paczki są wspólne dla sklepów w jednej instalacji PrestaShop; konfigurację otwieraj w kontekście właściwego sklepu.
Brakuje wcześniej używanej hurtowni
Sprawdź listę paczek. Komunikat Brak pakietu integracji nie oznacza automatycznie usunięcia konfiguracji. Zainstaluj ponownie właściwą zakupioną paczkę i otwórz istniejącą hurtownię. Nie twórz od razu nowej konfiguracji, aby nie utracić ciągłości powiązań.
5. Poruszanie się po panelu
Najpierw wybierz hurtownię. Jej ustawienia i dodatkowe narzędzia są wyświetlane w kontekście tej integracji. Ustawienia specjalne jednego dostawcy nie powinny służyć do konfigurowania innego.
| Zakładka | Do czego służy |
|---|---|
| Ustawienia | Połączenie, źródło, kategorie, ceny, podatki, dostępność oraz opcje paczki. |
| Import | Wgrywanie pliku, analiza źródła, test, import paczkowy i jego bieżący stan. |
| Mapowania | Przypisanie kategorii i cech dostawcy do istniejących elementów sklepu. |
| Historia | Ostatnie 25 uruchomień danej hurtowni w bieżącym sklepie. |
| Zarządzanie | Adres CRON, polecenie CLI i usuwanie konfiguracji hurtowni. |
Nazwa hurtowni pomaga rozpoznać konfigurację w panelu. Kod integracji jest używany między innymi w poleceniu CLI. Hurtownia aktywna określa aktywność konfiguracji; nie zastępuje osobnej opcji aktywowania importowanych produktów.
6. Podłączenie źródła danych
Adres URL
Wybierz Źródło danych → Adres URL, wklej pełny adres udostępniony przez hurtownię i zapisz ustawienia. Zachowaj wymagane parametry dostępu. Adres musi prowadzić do danych odczytywanych przez paczkę, a nie do strony logowania lub podglądu oferty.
Wgrany plik
- Wybierz Źródło danych → Wgrany plik i zapisz hurtownię.
- Otwórz Import, wskaż plik zgodny z integracją i kliknij Wgraj plik.
- Uruchom analizę oraz test. Gdy dostawca prześle aktualizację, wgraj nową wersję pliku.
Połączenie API
W paczkach API uzupełnij pola połączenia wskazane przez dostawcę i użyj dostępnych narzędzi testowych. Dane dostępowe, wymagane parametry i dodatkowe źródła zdjęć zależą od konkretnej integracji.
Po zapisaniu odśwież formularz i upewnij się, że ustawienia pozostały zapisane. Jeśli pojawi się błąd zapisu, rozwiąż go przed importem; samo zaznaczenie opcji w formularzu nie potwierdza zapisu w bazie.
7. Produkty, warianty i kategorie
| Ustawienie | Działanie |
|---|---|
| Kategoria nadrzędna | Docelowe miejsce dla importu i punkt odniesienia przy tworzeniu kategorii. |
| Twórz brakujące kategorie | Pozwala utworzyć kategorie odczytane ze źródła, jeżeli nie znaleziono odpowiedniego przypisania. |
| Dodawaj podkategorie na podstawie cech | Tworzy dodatkowe przypisania według rozpoznanych cech i reguł integracji. Nie jest to dowolny generator reguł dla każdego pola. |
| Twórz warianty produktów | Umożliwia zapis kombinacji rozpoznanych przez paczkę, np. kolorów i parametrów kamienia. |
| Importuj cechy | Włącza przenoszenie parametrów produktu do cech PrestaShop. |
| Twórz brakujące cechy | Pozwala dodać cechy, których nie ma jeszcze w sklepie. |
| Importuj zdjęcia | Włącza synchronizację zdjęć i tworzenie wymaganych miniaturek. |
| Aktywuj importowane produkty | Pozwala aktywować produkty w ramach importu. Dla pierwszej próby można pozostawić je nieaktywne. |
| Tryb katalogowy — ukryj standardową cenę i koszyk | Wyłącza standardową prezentację ceny i zakupu dla produktów obsługiwanych w tym trybie. Paczka może udostępniać własną wycenę i zakup konfigurowanego produktu. |
| Wyłącz produkty nieobecne w pełnym źródle | Służy do wyłączania zarządzanych produktów, które zniknęły z kompletnej oferty dostawcy. |
Produkt a grupa w źródle
Wiele wierszy dostawcy może tworzyć jeden produkt z wariantami. Dlatego liczba wpisów XML nie musi być równa liczbie produktów. Sposób rozpoznawania modelu i jego wariantów określa paczka integracji.
Import może aktualizować nazwy, opisy i inne zarządzane dane. Ręczne zmiany tych pól sprawdź po ponownym imporcie. Wyłączenie zdjęć nie zamienia importu w tryb aktualizacji wyłącznie cen i stanów.
8. Mapowanie kategorii i cech
- Po zapisaniu połączenia otwórz Import i kliknij Analizuj feed, kategorie i cechy.
- Sprawdź liczbę wpisów, grup i wariantów oraz rozpoznane kategorie, cechy i waluty.
- Otwórz Mapowania. Przypisz kategorię dostawcy do właściwej istniejącej kategorii sklepu.
- Powiąż cechy dostawcy z odpowiednimi cechami PrestaShop i zapisz mapowania.
- Zaimportuj małą próbkę i sprawdź rzeczywiste przypisania produktu.
Mapowania kategorii mogą kierować ofertę do istniejących kategorii także wtedy, gdy automatyczne tworzenie nowych kategorii jest wyłączone. Przy braku mapowania i wyłączonym tworzeniu kategorii produkt trafia do wskazanej kategorii nadrzędnej.
Kategoria źródłowa
Zegarki > Damskie → istniejąca kategoria sklepu Zegarki damskie. Cecha Materiał koperty → odpowiednia cecha w sklepie.Lista przedstawia kategorie występujące w analizowanym źródle. Jeśli plik zawiera tylko pierścionki z czarnym diamentem, sama taka pozycja na liście jest prawidłowa. Inne kategorie pojawią się po dostarczeniu i przeanalizowaniu odpowiednich danych.
Po zmianie struktury pliku lub rozszerzeniu oferty ponów analizę. Sprawdź nowe kategorie przed pełnym importem, aby nie utworzyć przypadkowych duplikatów w drzewie sklepu.
9. Ceny, VAT i zaokrąglanie
Najpierw ustal znaczenie ceny źródłowej
Hurtownia może przekazywać cenę zakupu, cenę sugerowaną lub obie wartości. Paczka rozpoznaje odpowiednie pola. Nie stosuj identycznego założenia do wszystkich dostawców.
| Pole | Jak ustawić |
|---|---|
| Grupa podatkowa | Wybierz właściwą aktywną grupę podatkową PrestaShop, np. grupę ze stawką 23% dla odpowiedniej sprzedaży. |
| Stawka VAT (%) | Podaj stawkę wykorzystywaną w przeliczeniach importu, zgodną z konfiguracją podatkową. |
| Ceny w źródle zawierają VAT | Zaznacz dla źródłowych cen brutto; pozostaw wyłączone dla cen netto, zgodnie z zasadami paczki. |
| Narzut na cenę (%) | Procent zwiększenia lub obniżenia podstawy ceny. Nie jest to procent marży. |
| Zaokrąglanie końcowej ceny brutto | Wybierz brak dodatkowego zaokrąglania albo zaokrąglanie w górę do pełnych 10 zł. |
Narzut procentowy
| Wartość pola | Mnożnik | Przykład dla 100 zł podstawy |
|---|---|---|
| 30% | ×1,30 | 130 zł |
| 100% | ×2,00 | 200 zł |
| −40% | ×0,60 | 60 zł |
Przykład obniżki o 40%: wpisz −40 w polu narzutu. Dozwolone minimum pola to −99%. Specjalne reguły wyceny, np. oddzielne mnożniki materiału i kamieni, są obsługiwane przez odpowiednią paczkę.
Zaokrąglenie do 10 zł
761,95 zł → 770,00 zł760,00 zł → 760,00 zł3583,57 zł → 3590,00 złZaokrąglenie jest stosowane po narzucie i VAT. Dotyczy produktów i wariantów tej hurtowni. Przy innej walucie lub stawce VAT faktyczna kwota prezentowana kupującemu może się różnić. Dla obcych walut sprawdź kursy skonfigurowane w PrestaShop.
Po zapisaniu ustawień uruchom ponowny import, aby przeliczyć zarządzane produkty. Sprawdź co najmniej jeden produkt prosty i jeden wariant.
10. Stany i dostępność
W standardowym trybie moduł zapisuje dostępność odczytaną ze źródła zgodnie z regułami paczki. Dostępność dostawcy nie zawsze oznacza fizyczny stan w Twoim magazynie.
Mnożnik stanu magazynowego pozwala przeliczyć ilość źródłową w integracjach, które korzystają z tego ustawienia. Wartość 1 oznacza brak skalowania ilości. Nie służy do prowadzenia oddzielnego magazynu własnego.
Produkty wycofane z oferty
Opcję Wyłącz produkty nieobecne w pełnym źródle włącz dopiero po sprawdzeniu, że plik zawiera kompletną ofertę. Mechanizm nie powinien traktować importu z limitem lub testu jako pełnego katalogu. Ostateczne działanie wymaga zakończenia pełnego importu zgodnie z jego regułami bezpieczeństwa.
Termin dostawy wyświetlany w motywie i rzeczywista ilość to osobne informacje. Sprawdź kartę produktu, koszyk i komunikat dla zamawianej liczby sztuk; sam status „dostępny” nie potwierdza prawidłowego terminu.
11. Pierwszy import krok po kroku
- Zapisz ustawienia. Wskaż źródło, kategorię, VAT, narzut i potrzebne opcje. Na początek możesz pozostawić produkty nieaktywne.
- Przeanalizuj źródło. Kliknij „Analizuj feed, kategorie i cechy” i zweryfikuj rozpoznane dane.
- Zapisz mapowania. Sprawdź docelowe kategorie i cechy.
- Wykonaj próbę. Rozwiń „Import ręczny / diagnostyczny”, ustaw „Limit grup” na 1 oraz „Pomiń” na 0 i wybierz „Test bez zapisu”.
- Zapisz produkt testowy. Dla tego samego zakresu wybierz „Uruchom ręcznie”. Test bez zapisu sam nie tworzy produktu do podglądu.
- Sprawdź panel i sklep. Zweryfikuj cenę, podatek, koszt zakupu, zdjęcia, warianty, opis, EAN, kategorię i dostępność.
- Powtórz import tej samej grupy. Upewnij się, że produkt jest aktualizowany i nie powstaje nowy duplikat.
- Uruchom cały katalog. Dopiero po poprawnej weryfikacji skorzystaj z importu paczkowego i później ustaw harmonogram.
Test bez zapisu służy do kontroli przetwarzania bez zmiany katalogu produktów. Nie zastępuje sprawdzenia rzeczywistego zapisu, szablonu sklepu ani zachowania koszyka.
12. Pełny import i pasek postępu
W zakładce Import sekcja Pełny import z paskiem postępu przetwarza katalog krótkimi żądaniami AJAX. Postęp jest zapisywany po każdej grupie, a kolejne paczki są uruchamiane przez otwartą kartę przeglądarki.
| Parametr / przycisk | Znaczenie |
|---|---|
| Maks. grup w paczce | Początkowy limit grup na żądanie; rozmiar jest później dostosowywany automatycznie. Formularz udostępnia zakres 3–80. |
| Budżet czasu paczki | Docelowy czas paczki: 10–50 sekund. Dla limitu serwera 60 sekund punktem wyjścia jest 35 sekund. |
| Rozpocznij od grupy | Dla całego katalogu pozostaw 0. |
| Test bez zapisu | Próba przetwarzania bez zapisu katalogu produktów. |
| Importuj cały katalog | Rozpoczyna nowy import paczkowy. |
| Zatrzymaj | Wstrzymuje import; zapisany postęp można wznowić. |
| Wznów | Kontynuuje wstrzymany import od zapisanego miejsca. |
| Odśwież status | Odczytuje zapisany stan działania. |
| Anuluj | Kończy zadanie bez kontynuowania kolejnych grup. Nie cofa zapisanych produktów. |
W statystykach sprawdzisz liczbę przetworzonych grup, produktów, kombinacji, błędów, cech i kategorii oraz czas działania. Procent postępu opisuje liczbę grup, a nie równomierny czas do końca: jedna grupa z wieloma zdjęciami może trwać znacznie dłużej.
Zatrzymanie lub anulowanie może zaczekać na aktualnie przetwarzaną grupę. Komunikat o przekroczeniu czasu żądania nie oznacza, że proces serwera przestał pracować. Nie usuwaj pliku blokady, aby wymusić równoległe uruchomienie.
13. Zdjęcia i materiały produktów
Opcja Importuj zdjęcia uruchamia pobieranie lub odczyt plików i przygotowanie miniaturek PrestaShop. Przypisanie fotografii do wariantów zależy od danych źródłowych i możliwości paczki.
- Sprawdź zdjęcie główne, kolejność galerii i zmianę fotografii po wyborze wariantu.
- Upewnij się, że nazwy lokalnych plików, rozszerzenia i wielkość liter odpowiadają źródłu.
- Dla zdjęć lokalnych wskaż prawidłowy katalog czytelny dla procesu PHP.
- Dla zdjęć zewnętrznych sprawdź, czy serwer hurtowni udostępnia pliki bez logowania i nie blokuje połączeń.
Dlaczego import zdjęć trwa dłużej?
Nowe lub wymagające uzupełnienia zdjęcia trzeba pobrać i przeskalować do formatów sklepu. Zmiana źródłowych adresów, brak plików na dysku lub niekompletne miniatury także mogą wymagać dodatkowej pracy. Na próbę wyłącz zdjęcia i porównaj czas importu tej samej oferty.
Wyłączenie zdjęć przyspiesza typowe odświeżanie, ale nie jest osobnym trybem „tylko ceny i stany”. Pozostałe włączone elementy importu nadal są przetwarzane.
Zmiana domeny lub katalogu sklepu
Zachowaj bazę, mapowania modułu, katalog zdjęć produktów oraz źródła lokalne. Przed przeniesieniem zaktualizuj moduł i sprawdź odczyt istniejących zdjęć. Po przeniesieniu popraw ścieżki źródeł i wykonaj test na kilku modelach.
Wideo, katalogi lokalnych materiałów i galerie specjalne są obsługiwane tylko przez paczki, które udostępniają takie funkcje. Zwykłe wgranie pliku MP4 do standardowego źródła XML nie dodaje automatycznie obsługi filmu.
14. Opcje poszczególnych integracji
Poniższe informacje dotyczą odpowiednich zakupionych paczek. Nie są wspólnymi ustawieniami każdej hurtowni. Szczegółowy zestaw pól zależy od wersji paczki.
GESE — Atom / XML
Podłącz źródło zgodne z paczką GESE, przeanalizuj grupy i mapowania oraz sprawdź, czy cena oznacza wartość sugerowaną przez dostawcę. Obniżkę o 40% ustawisz jako narzut −40%. W razie potrzeby włącz zaokrąglanie końcowej ceny brutto w górę do pełnych 10 zł, a następnie przelicz produkty importem.
BestDiamonds — XML
Paczka grupuje rozpoznane pozycje modelu w jeden produkt z kombinacjami. Sprawdź kolory, wariant kamienia, wycenę i galerię po zmianie kombinacji. Parametry techniczne kamienia mogą pozostać w nazwie wariantu; uproszczone cechy do filtrowania są osobną warstwą prezentacji.
Dostępność oferty nie musi być dokładną liczbą sztuk fizycznych. Brakujących rozmiarów nie należy dopisywać na podstawie przypuszczeń: zakres ustal z dostawcą lub według uzgodnionej konfiguracji paczki.
PZ Stelmach — API i zdjęcia lokalne
Połącz API, wskaż katalog materiałów i skonfiguruj kategorie kolekcji oraz wycenę. Paczka może udostępniać odrębne reguły materiału, usługi i kamieni, opcje konfiguratora, dopłaty oraz zakup skonfigurowanego produktu.
- Warianty i dostępność opcji powinny odpowiadać definicji modelu z API.
- Kategorie kolekcji, w tym tantalu, muszą wskazywać istniejące kategorie sklepu.
- Kosztów już wliczonych w odpowiedź API nie doliczaj ponownie; dotyczy to m.in. potwierdzonych przez dostawcę składników ceny materiału.
- Standardowa cena produktu i cena konfiguratora to różne elementy prezentacji. Sprawdź wycenę po zmianie parametrów oraz zapis w koszyku, jeżeli zakup jest włączony.
- Błąd HTTP 502 na etapie wyceny wymaga diagnostyki zapytania i odpowiedzi API; zmiana narzutu nie naprawia błędu połączenia.
WamaGold — CSV
Import dotyczy źródła CSV obsługiwanego przez paczkę. Zewnętrzny konfigurator osadzony skryptem działa po stronie dostawcy. Sam import katalogu nie oznacza przekazania konfiguracji i jej ceny do koszyka PrestaShop.
Własny katalog XLSX — paczka dedykowana
Pracuj na uzgodnionym szablonie, z wymaganymi arkuszami, identyfikatorami i strukturą danych. Nie zmieniaj samodzielnie nazw kolumn ani powiązań. Warianty, cennik kamieni, skład produktu i materiały muszą używać spójnych identyfikatorów. Brak ceny do uzupełnienia pozostaw jako brak danych, zamiast wpisywać sztuczne zero.
15. VIVAB2B — ceny i dwa magazyny
Rozdzielenie magazynu własnego i zapasu hurtowni jest dostępne w bazie 3.3.8 z paczką VIVAB2B 1.3.0. W zwykłym trybie jedna ilość produktu nie pozwala odróżnić tych dwóch źródeł.
Źródła i ceny
Integracja korzysta z pliku katalogowego Ceneo oraz dodatkowego pliku cen i stanów. Wprowadź dane źródła zgodnie z formularzem paczki, z zachowaniem klucza dostępu otrzymanego od hurtowni.
| Dane | Zastosowanie / limit |
|---|---|
| Plik katalogowy | Opis i dane oferty. Maksymalnie dwa pobrania na dobę; paczka korzysta z pamięci podręcznej katalogu. |
| Plik cen i stanów | Aktualne ceny i ilości. Maksymalnie jedno pobranie na godzinę. |
price | Cena detaliczna brutto. |
cena1 | Cena zakupu brutto, zapisywana odrębnie jako koszt własny po przeliczeniu na netto. |
Przy VAT 23% przykładowa cena sprzedaży 119 zł brutto oznacza około 96,75 zł netto, a zakup 79,53 zł brutto około 64,66 zł netto. Cena sprzedaży nie powinna zastępować ceny zakupu.
Włączenie rozdzielania stanów
- Sprawdź wersję bazy i paczki, a następnie w ustawieniach VIVAB2B zaznacz Oddziel stan własny od stanu hurtowni.
- Zapisz ustawienia i zaimportuj jeden produkt testowy.
- Na karcie produktu otwórz Moduły → VIVAB2B — magazyny i termin wysyłki.
- Wpisz rzeczywistą ilość w polu Magazyn własny. Początkowa wartość wynosi 0.
- Sprawdź termin dla jednej sztuki i dla ilości przekraczającej własny zapas. Ponów import i upewnij się, że własny stan pozostał zachowany.
Sprzedaż i terminy
| Pokrycie zamawianej ilości | Termin / działanie |
|---|---|
| Całość ze stanu własnego | Wysyłka w 24h. |
| Choć część musi pochodzić z hurtowni | Wysyłka w 2–3 dni robocze. |
| Brak wystarczającej ilości w obu źródłach | Zakup niedostępnej ilości jest blokowany. |
Sprzedaż w pierwszej kolejności zużywa własny zapas. Część hurtowa jest rezerwowana lokalnie, aby kolejne odświeżenie pliku nie udostępniało ponownie tego samego zapasu.
Rozliczenie rezerwacji hurtowej
- Zamów brakujący towar w VIVAB2B we własnym zakresie.
- Poczekaj, aż plik hurtowni uwzględni tę zmianę, i odśwież stany z zachowaniem limitu pobrań.
- W panelu produktu przy odpowiednim zamówieniu wybierz Rozlicz po zamówieniu i odświeżeniu stanów hurtowni.
- Potwierdź rozliczenie dopiero po sprawdzeniu obu poprzednich warunków.
Anulowanie, zwroty i ograniczenia
Anulowanie zamówienia i jego ponowne otwarcie rozlicza przypisane ilości. Sam zwrot pieniędzy nie przywraca własnego zapasu; potrzebne jest faktyczne przywrócenie towaru na stan w PrestaShop. Starsze zamówienia sprzed uruchomienia rozdzielania dla produktu i ich zwroty wymagają rozliczenia ręcznego.
Funkcja dotyczy standardowych produktów VIVAB2B, bez kombinacji, zestawów oraz współdzielenia stanów w grupie multistore. Po zainicjowaniu stanów przełącznik chroni przed przypadkowym wyłączeniem. Niestandardowe bloki terminu w motywie należy sprawdzić po wdrożeniu.
Gdy panel produktu zgłasza zmianę danych w tle, odśwież go przed wpisaniem nowej bezwzględnej ilości. Chroni to przed nadpisaniem zmian po sprzedaży lub imporcie.
16. Automatyzacja CRON i CLI
Otwórz wybraną hurtownię, przejdź do Zarządzanie i rozwiń Pokaż polecenie CLI i adres harmonogramu. Moduł pokazuje adres dla tej konfiguracji oraz polecenie konsolowe.
Adres CRON
- Skopiuj adres z panelu bez usuwania tokena i parametrów.
- Uruchom go kontrolnie i sprawdź odpowiedź oraz nowy wpis w historii.
- Dodaj zadanie w harmonogramie hostingu. Ustal częstotliwość zgodnie z aktualizacją źródła i limitami dostawcy.
- Ustaw terminy tak, aby kolejne wywołania jednej hurtowni nie nakładały się.
- Kontroluj wynik zadania; sam wpis w harmonogramie nie potwierdza udanego importu.
Adres wykorzystuje parametry provider i token; może obsługiwać także limit oraz offset. Korzystaj z adresu wygenerowanego przez sklep. Nie zastępuj go adresem przykładowym innej instalacji.
Import przez konsolę
Dla administratora serwera: użyj interpretera PHP zgodnego z daną instalacją i uruchom polecenie w katalogu sklepu. Zastąp przykładowy kod hurtowni i identyfikator sklepu własnymi wartościami.
cd /sciezka/do/sklepu
php bin/console astrabit:xml-import --provider=KOD_HURTOWNI --shop=1
| Opcja | Znaczenie |
|---|---|
--provider | Identyfikator lub kod konfiguracji hurtowni; wymagany. |
--shop | Identyfikator sklepu. Zalecane jawne wskazanie właściwego sklepu. |
--dry-run | Walidacja bez zmiany danych katalogu produktów. |
--limit | Maksymalna liczba grup; 0 oznacza brak limitu. |
--offset | Liczba grup do pominięcia; 0 oznacza początek. |
php bin/console astrabit:xml-import --provider=KOD_HURTOWNI --shop=1 --dry-run --limit=1 --offset=0
Import CLI i wywołanie CRON nie są tym samym mechanizmem co kolejne paczki AJAX w otwartej przeglądarce. Nie zakładaj, że nowe wywołanie automatycznie wznowi zatrzymany import paczkowy. Dla dużych katalogów administrator powinien dobrać czas wykonania i zasoby serwera.
17. Historia, logi i kontrola wyników
Zakładka Historia przedstawia ostatnie 25 uruchomień wybranej hurtowni w bieżącym sklepie: numer importu, początek, status, liczbę nowych i zaktualizowanych produktów oraz błędy.
| Status | Co oznacza |
|---|---|
| Zakończony | Przetwarzanie dobiegło końca; nadal warto sprawdzić ostrzeżenia i próbkę produktów. |
| Zakończony z błędami | Część danych wymaga sprawdzenia. Popraw przyczynę i ponów odpowiedni import. |
| Błąd | Nie udało się poprawnie wykonać zadania. |
| Wstrzymany | Zadanie ma zapisany postęp i można je wznowić lub anulować. |
| Anulowany | Zadanie zakończono bez kontynuacji; zapisane wcześniej dane pozostały. |
| W trakcie / Przygotowanie | Trwa praca albo przygotowanie danych. Sprawdź bieżący komunikat i aktualizację postępu. |
Dla administratora: logi uruchomień znajdują się w katalogu modules/astrabitxmlimport/var/logs/, w plikach odpowiadających importom. Przed przekazaniem ich dalej usuń poufne adresy z kluczami i tokeny.
Co sprawdzać po zmianie konfiguracji
- Końcową cenę brutto i regułę podatkową.
- Odrębną cenę zakupu, jeżeli jest w źródle.
- Produkt prosty, produkt z wariantami i produkt bez zapasu.
- Zdjęcia po zmianie wariantu i przypisanie do kategorii.
- Wynik ponownego importu tej samej oferty.
- Koszyk i termin dostawy, jeśli integracja obsługuje zakup.
18. Aktualizacja i migracja sklepu
Aktualizacja modułu bazowego
- Zakończ lub anuluj niezakończone importy i poczekaj, aż bieżące przetwarzanie zwolni blokadę. Na czas aktualizacji wstrzymaj zadania CRON.
- Wykonaj kopię bazy oraz całego katalogu
modules/astrabitxmlimport. - Wgraj aktualizację zgodnie z dołączoną instrukcją. Przy podmianie plików scalaj katalogi i zachowaj istniejące
integrationsorazvar. - Uruchom aktualizację modułu w Menedżerze modułów. Sama zmiana plików nie zastępuje migracji bazy i rejestracji wymaganych hooków.
- Wyczyść cache PrestaShop. W razie utrzymywania starego kodu sprawdź OPcache z administratorem serwera.
- Sprawdź wersję i zapis ustawień. Zaktualizuj potrzebne paczki, wykonaj mały test i przywróć harmonogram.
Aktualizacja paczki hurtowni
W „Pakietach integracji” wgraj nowszy podpisany ZIP tej samej integracji. Sprawdź wymagania paczki dotyczące wersji bazy i PHP. Przed aktualizacją anuluj niezakończone importy tej hurtowni, także starsze wstrzymane zadania. Wstrzymanie nie oznacza anulowania.
Przeniesienie sklepu lub zmiana domeny
- Przenieś bazę oraz katalogi produktów i modułu wraz z paczkami i mapowaniami.
- Popraw lokalne ścieżki materiałów, jeżeli zmienił się katalog instalacji.
- Sprawdź połączenia do źródeł i uprawnienia plików nowego procesu PHP.
- Zmień adresy w harmonogramie CRON.
- Zaimportuj kilka istniejących produktów i sprawdź, czy są aktualizowane bez duplikatów i niepotrzebnego odtwarzania zdjęć.
19. Usuwanie konfiguracji hurtowni
Opcja Zarządzanie → Usuń hurtownię służy do trwałego usunięcia konfiguracji wybranej hurtowni z bieżącego sklepu. Przed jej użyciem zakończ importy i wykonaj kopię danych.
| Zostanie usunięte | Pozostanie w sklepie |
|---|---|
| Konfiguracja hurtowni, zapisany plik źródłowy, historia importów i powiązania z produktami. | Produkty, ich zdjęcia, warianty i kategorie. |
- Otwórz „Zarządzanie” wybranej hurtowni.
- Jeżeli panel wskazuje niezakończony import, najpierw anuluj go w „Import” i poczekaj na zakończenie pracy.
- Wpisz dokładną nazwę hurtowni, zaznacz potwierdzenie i użyj „Usuń hurtownię”.
20. Najczęstsze problemy
„Ta paczka wymaga innej wersji bazy lub PHP”
Chodzi o zgodność z wersją modułu bazowego i PHP, a nie o polecenie zmiany silnika MySQL. Sprawdź wersję bazy modułu, wymagania paczki oraz PHP używane przez stronę. Wgraj kompletną aktualizację bazy, uruchom jej aktualizację w PrestaShop i dopiero potem ponów instalację paczki. PHP konsoli może różnić się od PHP witryny.
„Przed aktualizacją paczki anuluj niezakończony import”
Sprawdź import bieżący i historię odpowiedniej hurtowni. Starszy import wstrzymany również może blokować aktualizację. Anuluj go narzędziami modułu i poczekaj na zwolnienie aktualnego przetwarzania. Nie zmieniaj statusów bezpośrednio w bazie ani nie usuwaj plików blokady jako pierwszego sposobu naprawy.
Ustawienie podatku nie zapisuje się / „Unable to update provider”
Odśwież formularz i sprawdź zapis po stronie serwera. Komunikat dotyczy nieudanej aktualizacji konfiguracji; samo poprawne wysłanie wartości z formularza nie wyjaśnia przyczyny. Zweryfikuj kompletność wersji plików i migracji modułu oraz log błędu. Nie importuj katalogu na ustawieniach, które nie zostały zapisane.
Cena jest prawidłowa netto, ale brutto jest za niska
Sprawdź „Ceny w źródle zawierają VAT”, stawkę oraz rzeczywiście przypisaną grupę podatkową produktu. Na karcie produktu upewnij się, że nie pozostało „Brak podatku”. Po poprawieniu ustawień ponów import próbki.
Import przekroczył czas żądania lub zatrzymał się przy końcu
Odśwież zapisany status. Sprawdź, czy rośnie postęp lub zmienia się informacja o pracy procesu. Duża grupa, zdjęcia albo wolny serwer źródłowy mogą przekroczyć czas pojedynczego żądania. Nie uruchamiaj drugiego zadania, gdy pierwsze nadal pracuje. Po jego zakończeniu sprawdź logi i porównaj próbę bez zdjęć.
Zdjęcia zgłaszają HTTP 421, 403 lub 404
Sprawdź dokładny adres obrazu i odpowiedź serwera dostawcy. Kod odpowiedzi HTTP nie jest sam w sobie dowodem problemu z nową domeną sklepu. Dostawca może blokować pobieranie lub przekazywać nieaktualny URL. Zachowaj numer produktu, czas próby i kod odpowiedzi do zgłoszenia.
Stelmach nie pobiera ceny, pojawia się HTTP 502
Sprawdź etap diagnostyki i model, dla którego wykonano zapytanie. Zweryfikuj połączenie API oraz parametry. Jeżeli dostępny jest raport, zachowaj go do analizy. Nie naprawiaj błędu połączenia zmianą mnożnika ceny; może być potrzebna odpowiedź administratora API.
Występuje błąd kategorii tantalu
W ustawieniach Stelmach wskaż istniejącą kategorię dla modeli tantalu i zapisz formularz. Następnie ponów test. Kategoria kolekcji musi istnieć w danym sklepie.
Powstają duplikaty zamiast aktualizacji
Sprawdź, czy nie utworzono nowej konfiguracji zamiast użycia dotychczasowej, nie usunięto mapowań i nie zmieniły się identyfikatory źródłowe. Zachowaj kopię bazy i zatrzymaj dalszy pełny import do wyjaśnienia przyczyny.
Własna ilość VIVAB2B znika po imporcie
Sprawdź wersję bazy 3.3.8 i paczki 1.3.0, włączenie rozdzielenia stanów oraz inicjalizację produktu importem. Własny zapas wpisuj w panelu „VIVAB2B — magazyny i termin wysyłki”, a nie w standardowym polu łącznej ilości.
Moduł porównywarki nie przejmuje nazwy lub danych
Sprawdź dane standardowego produktu PrestaShop oraz ustawienia dodatkowego eksportera. Import katalogu nie gwarantuje uzupełnienia prywatnych pól każdego zewnętrznego modułu. Do analizy potrzebne są jego nazwa, wersja i wymagane pole.
Plik CSV lub XLSX ma nowe kolumny i przestał się importować
Porównaj strukturę ze wzorem obsługiwanym przez paczkę. Nie zmieniaj nazw arkuszy i identyfikatorów bez uzgodnienia. Do zgłoszenia dołącz zanonimizowaną próbkę i wskaż zmianę formatu.
21. Codzienna praca i pomoc techniczna
Po każdym ważnym imporcie
- Sprawdź status, liczniki i ostrzeżenia ostatniego uruchomienia.
- Porównaj przykładową cenę zakupu i sprzedaży z aktualnym źródłem.
- Sprawdź nowe modele, zmienione warianty i wycofane produkty.
- Kontroluj dostępność oraz terminy na karcie produktu i w koszyku.
- W VIVAB2B rozlicz rezerwacje dopiero po zakupie towaru i odświeżeniu źródła.
Co dołączyć do zgłoszenia
| Informacja | Przykład zakresu |
|---|---|
| Środowisko | Wersja PrestaShop, PHP strony, modułu bazowego i paczki. |
| Integracja | Nazwa hurtowni, identyfikator konfiguracji i identyfikator sklepu. |
| Import | Numer uruchomienia, czas zdarzenia, status oraz pełny komunikat. |
| Przykład | SKU / EAN / model, identyfikator produktu oraz oczekiwany i otrzymany wynik. |
| Materiały | Zrzut ustawień bez sekretów, fragment logu lub raport oraz mała próbka źródła. |
| Ostatnia zmiana | Aktualizacja paczki, przeniesienie domeny, nowy plik, zmiana podatku lub motywu. |
Nie przesyłaj haseł, kluczy API ani pełnego adresu CRON w publicznych zgłoszeniach. Przed zmianą struktury importu, wyliczania cen lub prowadzenia magazynu uzgodnij zakres z Astrabit.
Zacznij od jednej grupy
Sprawdź cenę, warianty, zdjęcia i ponowny import. Potem uruchom pełną ofertę.