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ę.

Wersja bazy 3.3.8PrestaShop od 1.7.6.4PHP od 7.2Osobne paczki hurtowni

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.

Zakres tej instrukcjiInstrukcja opisuje bazę 3.3.8 i zasady obsługi paczek integracji. Rozdział VIVAB2B dotyczy paczki 1.3.0. Opcje właściwe dla dostawcy pojawiają się po zainstalowaniu jego paczki i wybraniu hurtowni.

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

ElementWymaganie / zalecenie
PrestaShopOd 1.7.6.4; linie 1.7, 8 i 9 zgodnie z wymaganiami używanej paczki i środowiska sklepu.
PHPOd 7.2. Wersja PHP musi być także obsługiwana przez daną wersję PrestaShop.
Rozszerzenia PHPcURL, DOM, GD, Mbstring, ZIP, OpenSSL i XMLReader.
PołączenieDostęp serwera do źródła danych, API i serwerów zdjęć dostawcy. Wymagane poprawne certyfikaty HTTPS.
Zapis plikówProces PHP musi móc zapisywać pliki robocze modułu, paczki integracji oraz zdjęcia produktów.
HarmonogramDostę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.
Nie łącz dwóch mechanizmów aktualizacji tego samego katalogu bez uzgodnienia.Drugi importer lub ręczne zmiany mogą nadpisywać ceny, ilości i opisy aktualizowane przez moduł.

3. Instalacja modułu bazowego

  1. W panelu PrestaShop otwórz Moduły → Menedżer modułów i skorzystaj z opcji wgrania modułu.
  2. Wskaż instalacyjny ZIP modułu bazowego Astrabit XML Integrator. Nie wybieraj w tym miejscu ZIP-a samej hurtowni.
  3. Po instalacji otwórz konfigurację modułu lub przejdź do Katalog → Integracje XML.
  4. Otwórz Pakiety integracji i zainstaluj zakupioną paczkę hurtowni, zgodnie z kolejnym rozdziałem.
  5. 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.

Trzy różne elementyZIP modułu bazowego instalujesz w Menedżerze modułów. ZIP hurtowni instalujesz w „Pakietach integracji”. XML, CSV lub XLSX z produktami wgrywasz jako źródło w zakładce „Import” wybranej hurtowni.

4. Dodawanie paczek integracji

  1. Otwórz konfigurację modułu i wybierz Pakiety integracji.
  2. W polu Paczka integracji Astrabit (.zip) wskaż otrzymany plik hurtowni.
  3. Kliknij Zainstaluj lub zaktualizuj integrację. Moduł sprawdzi podpis, zawartość oraz zgodność wersji.
  4. Sprawdź nazwę i wersję na liście Zainstalowane pakiety.
  5. 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.

Nie modyfikuj zawartości podpisanego ZIP-a.Zmiana plików paczki może spowodować odrzucenie podpisu. Do instalacji używaj oryginalnego archiwum otrzymanego od Astrabit.

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ładkaDo czego służy
UstawieniaPołączenie, źródło, kategorie, ceny, podatki, dostępność oraz opcje paczki.
ImportWgrywanie pliku, analiza źródła, test, import paczkowy i jego bieżący stan.
MapowaniaPrzypisanie kategorii i cech dostawcy do istniejących elementów sklepu.
HistoriaOstatnie 25 uruchomień danej hurtowni w bieżącym sklepie.
ZarządzanieAdres 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

  1. Wybierz Źródło danych → Wgrany plik i zapisz hurtownię.
  2. Otwórz Import, wskaż plik zgodny z integracją i kliknij Wgraj plik.
  3. Uruchom analizę oraz test. Gdy dostawca prześle aktualizację, wgraj nową wersję pliku.
Plik lokalny nie odświeża się sam.CRON przetwarza zapisane źródło. Nie pobierze nowych cen z platformy dostawcy, jeżeli integracja korzysta jedynie z ręcznie wgrywanego CSV lub XLSX.

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

UstawienieDziałanie
Kategoria nadrzędnaDocelowe miejsce dla importu i punkt odniesienia przy tworzeniu kategorii.
Twórz brakujące kategoriePozwala utworzyć kategorie odczytane ze źródła, jeżeli nie znaleziono odpowiedniego przypisania.
Dodawaj podkategorie na podstawie cechTworzy dodatkowe przypisania według rozpoznanych cech i reguł integracji. Nie jest to dowolny generator reguł dla każdego pola.
Twórz warianty produktówUmożliwia zapis kombinacji rozpoznanych przez paczkę, np. kolorów i parametrów kamienia.
Importuj cechyWłącza przenoszenie parametrów produktu do cech PrestaShop.
Twórz brakujące cechyPozwala dodać cechy, których nie ma jeszcze w sklepie.
Importuj zdjęciaWłącza synchronizację zdjęć i tworzenie wymaganych miniaturek.
Aktywuj importowane produktyPozwala aktywować produkty w ramach importu. Dla pierwszej próby można pozostawić je nieaktywne.
Tryb katalogowy — ukryj standardową cenę i koszykWyłą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ódleSł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.

Powiązania są ważniejsze niż podobna nazwa.Moduł zapisuje własne przypisania identyfikatorów dostawcy do produktów i wariantów. Nie zakładaj, że po usunięciu hurtowni lub dodaniu jej od nowa istniejące produkty zostaną automatycznie rozpoznane po EAN.

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

  1. Po zapisaniu połączenia otwórz Import i kliknij Analizuj feed, kategorie i cechy.
  2. Sprawdź liczbę wpisów, grup i wariantów oraz rozpoznane kategorie, cechy i waluty.
  3. Otwórz Mapowania. Przypisz kategorię dostawcy do właściwej istniejącej kategorii sklepu.
  4. Powiąż cechy dostawcy z odpowiednimi cechami PrestaShop i zapisz mapowania.
  5. 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.

Przykład
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.

PoleJak ustawić
Grupa podatkowaWybierz 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ą VATZaznacz 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 bruttoWybierz brak dodatkowego zaokrąglania albo zaokrąglanie w górę do pełnych 10 zł.
Sama stawka „23” nie przypisuje reguły podatkowej do produktu.Sprawdź jednocześnie grupę podatkową oraz końcową cenę netto i brutto na karcie produktu. Ustawienie „Brak podatku” może spowodować nieprawidłową prezentację ceny mimo prawidłowego przeliczenia kwoty netto.

Narzut procentowy

Wartość polaMnożnikPrzykład dla 100 zł podstawy
30%×1,30130 zł
100%×2,00200 zł
−40%×0,6060 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.

Sprawdź zasady ręcznej korekty ilości.W zwykłej synchronizacji kolejny import może zastąpić ilość wpisaną ręcznie na karcie produktu. Oddzielny magazyn własny jest dodatkową funkcją paczki VIVAB2B, opisaną w rozdziale 15.

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

  1. Zapisz ustawienia. Wskaż źródło, kategorię, VAT, narzut i potrzebne opcje. Na początek możesz pozostawić produkty nieaktywne.
  2. Przeanalizuj źródło. Kliknij „Analizuj feed, kategorie i cechy” i zweryfikuj rozpoznane dane.
  3. Zapisz mapowania. Sprawdź docelowe kategorie i cechy.
  4. Wykonaj próbę. Rozwiń „Import ręczny / diagnostyczny”, ustaw „Limit grup” na 1 oraz „Pomiń” na 0 i wybierz „Test bez zapisu”.
  5. Zapisz produkt testowy. Dla tego samego zakresu wybierz „Uruchom ręcznie”. Test bez zapisu sam nie tworzy produktu do podglądu.
  6. Sprawdź panel i sklep. Zweryfikuj cenę, podatek, koszt zakupu, zdjęcia, warianty, opis, EAN, kategorię i dostępność.
  7. Powtórz import tej samej grupy. Upewnij się, że produkt jest aktualizowany i nie powstaje nowy duplikat.
  8. Uruchom cały katalog. Dopiero po poprawnej weryfikacji skorzystaj z importu paczkowego i później ustaw harmonogram.
Limit dotyczy grup, nie pojedynczych wierszy.Jedna grupa może zawierać produkt z wieloma wariantami. „Pomiń” określa liczbę grup do pominięcia, a nie numer SKU.

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 / przyciskZnaczenie
Maks. grup w paczcePoczątkowy limit grup na żądanie; rozmiar jest później dostosowywany automatycznie. Formularz udostępnia zakres 3–80.
Budżet czasu paczkiDocelowy czas paczki: 10–50 sekund. Dla limitu serwera 60 sekund punktem wyjścia jest 35 sekund.
Rozpocznij od grupyDla całego katalogu pozostaw 0.
Test bez zapisuPróba przetwarzania bez zapisu katalogu produktów.
Importuj cały katalogRozpoczyna nowy import paczkowy.
ZatrzymajWstrzymuje import; zapisany postęp można wznowić.
WznówKontynuuje wstrzymany import od zapisanego miejsca.
Odśwież statusOdczytuje zapisany stan działania.
AnulujKoń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.

Pozostaw kartę otwartą.Zamknięcie karty zatrzymuje wysyłanie kolejnych paczek. Zapisany postęp pozostaje. Po powrocie sprawdź stan i wznów istniejące zadanie, zamiast rozpoczynać drugi import.

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.

Tożsamość lokalnych zdjęćWersja 3.3.8 zawiera mechanizm stabilnych powiązań dla obsługiwanych źródeł lokalnych. Nie oznacza to automatycznego rozpoznawania każdej zmiany dowolnego zewnętrznego URL. Nie usuwaj mapowań zdjęć podczas migracji.

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.

Zakres dedykowanego szablonuObsługa konkretnego XLSX nie oznacza importu dowolnego skoroszytu Excel. Nowe układy arkuszy, formuły cenowe lub typy materiałów wymagają sprawdzenia zgodności z paczką.

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.

DaneZastosowanie / limit
Plik katalogowyOpis i dane oferty. Maksymalnie dwa pobrania na dobę; paczka korzysta z pamięci podręcznej katalogu.
Plik cen i stanówAktualne ceny i ilości. Maksymalnie jedno pobranie na godzinę.
priceCena detaliczna brutto.
cena1Cena 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

  1. Sprawdź wersję bazy i paczki, a następnie w ustawieniach VIVAB2B zaznacz Oddziel stan własny od stanu hurtowni.
  2. Zapisz ustawienia i zaimportuj jeden produkt testowy.
  3. Na karcie produktu otwórz Moduły → VIVAB2B — magazyny i termin wysyłki.
  4. Wpisz rzeczywistą ilość w polu Magazyn własny. Początkowa wartość wynosi 0.
  5. 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.
Własny zapas wpisuj w dedykowanym panelu.Standardowa ilość PrestaShop przedstawia łączną dostępną ilość. Nie edytuj jej tak, jakby oznaczała sam magazyn własny. Dawny stan nie jest automatycznie przejmowany, ponieważ mógł pochodzić z hurtowni.

Sprzedaż i terminy

Pokrycie zamawianej ilościTermin / działanie
Całość ze stanu własnegoWysyłka w 24h.
Choć część musi pochodzić z hurtowniWysyłka w 2–3 dni robocze.
Brak wystarczającej ilości w obu źródłachZakup 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

  1. Zamów brakujący towar w VIVAB2B we własnym zakresie.
  2. Poczekaj, aż plik hurtowni uwzględni tę zmianę, i odśwież stany z zachowaniem limitu pobrań.
  3. W panelu produktu przy odpowiednim zamówieniu wybierz Rozlicz po zamówieniu i odświeżeniu stanów hurtowni.
  4. Potwierdź rozliczenie dopiero po sprawdzeniu obu poprzednich warunków.
To nie jest rezerwacja w systemie dostawcy.Moduł nie składa zamówienia w VIVAB2B i nie blokuje towaru u hurtowni. Zbyt wczesne rozliczenie rezerwacji lokalnej może ponownie udostępnić ilość, której już nie ma.

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

  1. Skopiuj adres z panelu bez usuwania tokena i parametrów.
  2. Uruchom go kontrolnie i sprawdź odpowiedź oraz nowy wpis w historii.
  3. Dodaj zadanie w harmonogramie hostingu. Ustal częstotliwość zgodnie z aktualizacją źródła i limitami dostawcy.
  4. Ustaw terminy tak, aby kolejne wywołania jednej hurtowni nie nakładały się.
  5. 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.

Token jest poufny.Nie publikuj adresu CRON na stronie, w zgłoszeniach publicznych ani na zrzutach ekranu. Po zmianie domeny skopiuj aktualny adres z panelu i popraw harmonogram.

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
OpcjaZnaczenie
--providerIdentyfikator lub kod konfiguracji hurtowni; wymagany.
--shopIdentyfikator sklepu. Zalecane jawne wskazanie właściwego sklepu.
--dry-runWalidacja bez zmiany danych katalogu produktów.
--limitMaksymalna liczba grup; 0 oznacza brak limitu.
--offsetLiczba 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.

Limity dostawcy obowiązują także CRON.VIVAB2B nie należy odpytywać o stany częściej niż raz na godzinę, a o pełny katalog częściej niż dwa razy na dobę. Dla plików wgrywanych ręcznie zadbaj o dostarczenie aktualnej wersji źródła.

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.

StatusCo oznacza
ZakończonyPrzetwarzanie dobiegło końca; nadal warto sprawdzić ostrzeżenia i próbkę produktów.
Zakończony z błędamiCzęść danych wymaga sprawdzenia. Popraw przyczynę i ponów odpowiedni import.
BłądNie udało się poprawnie wykonać zadania.
WstrzymanyZadanie ma zapisany postęp i można je wznowić lub anulować.
AnulowanyZadanie zakończono bez kontynuacji; zapisane wcześniej dane pozostały.
W trakcie / PrzygotowanieTrwa 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.

„0 błędów” nie wyklucza ostrzeżeń.Nieudane pobranie pojedynczego zdjęcia może być zapisane jako ostrzeżenie, mimo że licznik błędów grup pozostał równy 0. Przy brakujących zdjęciach sprawdzaj także wpisy dotyczące zdjęć i zachowania galerii.

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

  1. Zakończ lub anuluj niezakończone importy i poczekaj, aż bieżące przetwarzanie zwolni blokadę. Na czas aktualizacji wstrzymaj zadania CRON.
  2. Wykonaj kopię bazy oraz całego katalogu modules/astrabitxmlimport.
  3. Wgraj aktualizację zgodnie z dołączoną instrukcją. Przy podmianie plików scalaj katalogi i zachowaj istniejące integrations oraz var.
  4. Uruchom aktualizację modułu w Menedżerze modułów. Sama zmiana plików nie zastępuje migracji bazy i rejestracji wymaganych hooków.
  5. Wyczyść cache PrestaShop. W razie utrzymywania starego kodu sprawdź OPcache z administratorem serwera.
  6. Sprawdź wersję i zapis ustawień. Zaktualizuj potrzebne paczki, wykonaj mały test i przywróć harmonogram.
Nie resetuj i nie odinstalowuj modułu w celu aktualizacji.Reset lub usunięcie konfiguracji może naruszyć ciągłość mapowań. Nie zastępuj całego katalogu modułu pustą bazą bez zachowania zakupionych integracji.

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ętePozostanie w sklepie
Konfiguracja hurtowni, zapisany plik źródłowy, historia importów i powiązania z produktami.Produkty, ich zdjęcia, warianty i kategorie.
  1. Otwórz „Zarządzanie” wybranej hurtowni.
  2. Jeżeli panel wskazuje niezakończony import, najpierw anuluj go w „Import” i poczekaj na zakończenie pracy.
  3. Wpisz dokładną nazwę hurtowni, zaznacz potwierdzenie i użyj „Usuń hurtownię”.
To nie jest sposób na naprawę importu.Ponowne dodanie hurtowni nie odtwarza skasowanych powiązań i może utworzyć duplikaty produktów. W celu czasowego wyłączenia korzystaj z ustawień aktywności i harmonogramu zamiast kasowania konfiguracji.

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

InformacjaPrzykład zakresu
ŚrodowiskoWersja PrestaShop, PHP strony, modułu bazowego i paczki.
IntegracjaNazwa hurtowni, identyfikator konfiguracji i identyfikator sklepu.
ImportNumer uruchomienia, czas zdarzenia, status oraz pełny komunikat.
PrzykładSKU / EAN / model, identyfikator produktu oraz oczekiwany i otrzymany wynik.
MateriałyZrzut ustawień bez sekretów, fragment logu lub raport oraz mała próbka źródła.
Ostatnia zmianaAktualizacja 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.

Gotowość do pracyKonfiguracja jest gotowa do regularnego użycia po sprawdzeniu importu próbki, ponownej aktualizacji tych samych produktów, ceny brutto, dostępności oraz wyniku pierwszego wywołania harmonogramu.

Zacznij od jednej grupy

Sprawdź cenę, warianty, zdjęcia i ponowny import. Potem uruchom pełną ofertę.

Pierwszy import
Astrabit · Instrukcja Astrabit XML Integrator · Baza 3.3.8 · Aktualizacja: 2 listopada 2026
Opcje paczek hurtowni mogą różnić się zależnie od ich wersji i zakresu zakupionej integracji.