Dokumentacja - Import XML dla PrestaShop

Wymagania instalacyjne

Moduł wymaga kilku podstawowych usług na serwerze, które w większości przypadków są aktywne.
Gdyby któraś z wymienionych opcji nie była dostępna - należy ją włączyć w panelu serwera lub napisać do administratora.

1. PHP:5.6 - 7.3
2. ionCube: tak

Instalacja

Moduł możesz znaleźć na liście jako

1. Nazwa: X13Import
2. Opis: Integracja z hurtownią
3. Autor: x13.pl
4. Kategoria: Rynek
5. Filtruj po: Zainstalowane i niezainstalowane / Aktywne i nieaktywne

Mapowanie kategorii

W zakładce Import XML → Mapowanie kategorii, mamy wszystkie dostępne opcje dotyczące kategorii z modułu, ustawiania dla nich narzutu jak i mapowania ich z kategoriami w preście.

Podstawowe przyciski w tej zakładce – umieszczone po prawej górnej stronie panelu to:

• Usuń produktu z hurtowni – funkcja ta usuwa wszystkie produkty zaimportowane z hurtowni (bez względu na to z której hurtowni został dodany produkt, i czy obecnie kategoria taka jest włączona czy też nie)
• Wyłącz produktu z hurtowni – wybór tej opcji spowoduje wyłączenie wszystkich produktów z hurtowni (aktywność na NIE), jej opcje działają analogicznie do opcji Usuń produkty z hurtowni.
• Pobierz kategorie z hurtowni - powoduje pobranie wszystkich kategorii, z wszystkich dodanych hurtowni na podstawie aktualnych plików XML.
  Funkcję tą zawsze wybieramy po zainstalowaniu modułu / dodaniu hurtowni, jak i zalecamy co jakiś czas pobierać kategorię – jeśli hurtownia doda je w pliku XML
• Importuj kategorie do sklepu - za pomocą tej opcji zaimportujemy kategorię w strukturze 1:1 z wybranych kategorii hurtowni.
  Kategorie importowane są do kategorii głównej sklepu (możemy przenosić je do innych kategorii, czy też zmieniać nazwę po imporcie), powiązanie jest realizowane za pomocą ID kategorii z hurtowni oraz ID kategorii z PrestaShop.
  Aby kategorie zostały zaimportowane musimy włączyć ich aktywność, za pomocą aktywacji pola „import” w danej linii kategorii, możemy również zrobić to za pomocą opcji Działania masowe.

Import drzewa kategorii z hurtowni 1:1 do sklepu

Aby zaimportować kategorię w strukturze 1:1 takiej jak w XMLu od hurtowni musimy zrobić proste 3 czynności.

• kategorie muszą być pobrane – przycisk Pobierz kategorie z hurtowni
• wybrane kategorie muszą być aktywne (ikonka potwierdzenia) – możemy aktywować ją ręcznie lub zrobić to z Działania masowe
• klikamy przycisk Importuj kategorie do sklepu - w tym momencie rozpocznie się import dodawania kategorii do sklepu, po dodaniu ostatniej aktywnej kategorii pojawi się informacja o zakończeniu importu, a strona zostanie odświeżona

Ręczne mapowanie kategorii

Aby zaimportować kategorię w strukturze 1:1 takiej jak w XMLu od hurtowni musimy zrobić proste 3 czynności.

• kategorie muszą być pobrane – przycisk Pobierz kategorie z hurtowni
• przy wybranej kategorii klikamy Edytuj
  • wzorzec nazwy produktu – możemy stworzyć własny wzorzec nazwy produktu, np. nazwa produktu z hurtowni i słowo PROMOCJA!
  • importuj dane – pole odpowiada za importowanie produktów z danej kategorii hurtowni do sklepu
  • narzut – procentowy narzut dla cen w stosunku do jej wartości w XMLu
  • kategorie w sklepie, zaznaczamy do jakiej/ich kategorii produkt ma być dodawany podczas importu i aktualizacji
  • kategoria główna – produkty będą do niej przypisane jako „domyślnej” wg PrestaShop

Zarządzanie cenami

Moduł umożliwia zarządzanie cenami na 2 sposoby.

• przypisywanie narzutu według kategorii danej hurtowni
• zarządzanie cenami według przedziałów cenowych dla konkretnej hurtowni.

Ustawienia narzutu według kategorii zostały opisane w informacjach o mapowaniu kategorii.

Istnieje możliwość dodania również zarządzania według ceny produktu, aby to zrobić przechodzimy do Import XML → Zarządzanie cenami. Przy dodawaniu nowego zakresu cenowego wybieramy:

• hurtownie której dotyczy dany zakres
• cenę od
• cenę do
• rodzaj narzutu
  • kwota
  • procent
• wartość
• nadpisywanie narzutu kategorii (jeśli wybierzemy tą opcję narzut według kategorii zostanie pominięty, przy wyłączonej konfiguracji narzut zostanie dodany do siebie)

W tej zakładce również możemy włączyć opcję Sumuj narzut z zakresów cenowych, w takim przypadku jeśli produkt będzie w cenie która obejmuje 2 zakresy zostaną one do siebie dodane (np. 10% dla produktów od 0zł do 1000zł, oraz +5zł dla produktów od 0zł do 10zł).

Wykluczanie produktów

Jeśli po imporcie produktów chcemy wykluczyć dany z aktualizacji ceny lub całkowitej aktualizacji przechodzi do zakładki Import XML → Mapowanie kategorii.

W module mamy 2 opcje do wykluczania aktualizacji:

• Wyklucz aktualizację - opcja ta wyłącza aktualizację wszystkich informacji o produkcie (nie zmienią się żadne dane, dostępność, ilość, cena, teksty itd)
• Wyklucz aktualizację ceny - włączenie tej opcji spowoduje nie aktualizowanie ceny dla takiego produktu (ceny zakupu, sprzedaży, cen specyficznych)

Konfiguracja

W tej zakładce znajdziemy wszystkie opcje konfiguracyjne modułu.

Zadania CRON

Aby moduł zaczął importować produkty, jak i później je aktualizował wymagane jest ustawienie zadań CRON na serwerze

W sytuacji gdy mamy wgrany moduł, ustawione opcje importu jak i zaimportowane kategorie czeka Nas ostatni krok.
Jest to utworzenie 2 zadań CRON, dzięki którym import będzie działał całkowicie automatycznie - w myśl zasady "uruchom i zapomnij"

Prawidłowe ustawienie jest wymagane dla automatycznego importu jak i aktualizacji produktów.

Wywołujemy co 2 godziny i w każdej 23 minucie

/usr/bin/lynx --dump "http://domena.pl/modules/x13import/cron.php?token=xXxxXxx" >/dev/null 2>&1 

plik cron.php pobiera wszystkie pliki XML z hurtowni, dodaje je do bazy w zrozumiałej dla modułu strukturze, jak i przetwarza wszystkie aktualizacje produktów (ilości, ceny, opis itd zgodnie z konfiguracją)
standardowo czas wykonania skrypty to od 2s do 500s (im więcej hurtowni/produktów tym czas ten jest dłuższy)

Wywołujemy co 15 minut

/usr/bin/lynx --dump "http://domena.pl/modules/x13import/update.php?token=xXxxXxx" >/dev/null 2>&1 

plik update.php dodaje nowe produkty z hurtowni, działa do maksymalnego czasu ustawionego na serwerze (timout) nie dłużej niż 600 sekund
standardowo dodaje do 500 produktów na uruchomienie (Jeśli produkt ma 10 atrybutów to liczymy to jako 10 produktów)

Zamiast xXxxXxx wpisujemy poprawny indywidualny token, cały poprawny link znajdziemy w Import XML Konfiguracja, na samej górze w boxie Adresy skryptów.

Jak dodać zadanie CRON na serwerze ?

Powyższe przykłady dodania zadań CRON są dla serwerów z systemem DirectAdmin, szczegółową instrukcję jak i przykłady dla innych serwerów znajdą Państwo tutaj

Aktualizazacja modułu

Od 2021 roku, zawsze aktualną wersję modułu możesz pobrać z zakładki "moje konto" następnie "pobierz dodatki".

Jeśli posiadasz moduł w wersji minimum 4.0.X, możesz samodzielnie pobrać najnowszą wersję i wgrać na obecny moduł (ważne! nie odinstalowujemy poprzedniej wersji modułu).
1. Logujemy się na konto w x13.pl i pobieramy najnowszą wersję dodatku
2. Logujemy sie do swojego sklepu PrestaShop
3. Przechodzimy do zakładki Moduły -> Moduły
4. Po prawej u góry strony wybieramy Załaduj moduł i wskazujemy wcześniej pobrane archiwum

Problemy i ich rozwiązania

Odinstalowanie modułu

UWAGA !!! odinstalowanie modułu powoduje bezpowrotne usunięcie powiązań produktów z hurtowni z tymi już dodanymi w sklepie - nie będą się poprawnie aktualizowały, oraz zostaną zduplikowane przy ponownej instalacji.

Biała strona po dodaniu modułu lub "Chińskie znaki" po dodaniu modułu

Brak zainstalowanego ionCube loader na serwerze - zobacz rozwiązanie, lub na serwerze nie jest ustawione PHP 5.3 - 7.0.

Moduł nie dodaje produktów

• czy mamy ustawione wszystkie dane dodanych hurtowni (jeśli moduł napotka na problem/brak danych do chociażby jednej z hurtowni, żadne produkty nie zostaną dodane)
• czy zmapowane/przypisane są kategorie (również ze sprawdzeniem czy nie ma nowych w hurtowni Import XML -> Kategorie i pobierz kategorie
• czy mamy ustawione zadania CRON na serwerze na plik cron.php i update.php
• czy uruchamiając ręcznie 1raz plik cron.php, a następnie update.php produkty zaczną się dodawać
• czy sklep jest włączony (Preferncje -> Obsługa i włącz sklep), jeśli sklep jest wyłączony musimy dodać IP serwera w opcji Adres IP do zarządzania - wtedy zadanie CRON będzie mogło się poprawnie wykonać

Moduł nie aktualizuje produktów

W przypadku kiedy moduł nie aktualizuje produktów w sklepie musimy sprawdzić

• czy mamy ustawione wszystkie dane dodanych hurtowni (jeśli moduł napotka na problem/brak danych do chociażby jednej z hurtowni, żadne produkty się nie zaktualizują)
• czy zmapowane/przypisane są kategorie (również ze sprawdzeniem czy nie ma nowych w hurtowni Import XML -> Kategorie i pobierz kategorie
• czy w przypadku uruchomienia ręcznie pliki CRON.php z przeglądarki nie mamy żadnego błędu oraz otrzymujemy na końcu SCRIPT COMPLETE -- EXECUTE TIME: - jeśli nie sprawdzamy czy mamy ustawiony na serwerze czas dla PHP na 600sekund i RAM na 512MB
• czy sklep jest włączony (Preferncje -> Obsługa i włącz sklep), jeśli sklep jest wyłączony musimy dodać IP serwera w opcji Adres IP do zarządzania - wtedy zadanie CRON będzie mogło się poprawnie wykonać

MAX ONE INSTANCE!

Informacja MAX ONE INSTANCE!, może pojawiać się z kilku powodów:

• jest już uruchomione inne zdanie np trwa zadanie cron.php, i próbujemy odpalić plik update.php
• pojawił się błąd podczas dodawania produktu - może to być błąd np z faktu zmienionej klasy w preście, niepoprawnego opisu w XMLu itd - w takim przypadku polecamy włączyć tryb debugowania w PrestaShop, i uruchomić zadanie ręcznie

Błąd 403 przy uruchomieniu pliku update lub cron - na serwerze hekko itd

Po ręcznym uruchomieniu pliku update lub cron otrzymujemy 403 w adresie.

Musimy dla plików w module x13import ustawić chmody na 644, oraz dla wszystkich folderów prawa na 755

Fatal error - podczas uruchomienia zadania UPDATE.php

Należy sprawdzić czy nie korzystają Państwo z wtyczki MailChimp Integration, powoduje ona problem przy dodawaniu produktów.
Najłatwiej wyłączyć moduł, w innym przypadku należy poprawić jego kod.

Zdjęcia w opisie wystają za jego pole

W przypadku gdy zdjęcia w opisie produktu są większe niż pole opisu - np na telefonie komórkowym, należy dodać styl CSS który ograniczy ich szerokość - niestety nie wszystkie hurtownie dodają do zdjęć w opisie odpowiednią klasę od responsywności.
W przypadku PrestaShop 1.7 edytujemy plik themes/nazwa/assets/css/custom.css i na jego końcu dodajemy: Najłatwiej wyłączyć moduł, w innym przypadku należy poprawić jego kod.

#product .product-description img{
    max-width: 100%;
    height: auto;
}