Astra ERLI dla PrestaShop

1. Do czego służy Astra ERLI

Astra ERLI łączy sklep PrestaShop z marketplace ERLI i obsługuje dwa główne obszary: katalog ofert oraz zamówienia. Moduł może wystawiać i aktualizować oferty, synchronizować stany, aktywność i ceny, prowadzić czasowe promocje, pobierać katalog ERLI do mapowania lub importu, a także importować zamówienia do standardowych zamówień PrestaShop.

2. Zalecana kolejność pierwszej konfiguracji

1. Połączenie: dodaj token ERLI i wybierz środowisko Produkcyjne lub Sandbox.
2. Kategorie i cechy: załaduj lokalny plik kategorii, zmapuj kategorie PrestaShop → ERLI i wymagane cechy.
3. Marki i GPSR: skonfiguruj mapowanie marek, producenta GPSR i opcjonalny podmiot odpowiedzialny.
4. Ustawienia ofert: ustaw czas wysyłki, cennik dostawy, dokumenty, źródło kodu producenta, opis i domyślny status oferty.
5. Oferta testowa: wystaw jeden produkt lub wariant i sprawdź wynik w ERLI.
6. Katalog ERLI: zsynchronizuj oferty z ERLI i sprawdź automatyczne mapowanie istniejących produktów.
7. Wysyłki: pobierz typy dostawy ERLI, ustaw przewoźników, fallback i statusy startowe.
8. Zamówienie testowe: pobierz jedno zamówienie, sprawdź produkt, przewoźnika, status, COD i tracking.
9. Statusy: skonfiguruj reguły ERLI → PrestaShop i PrestaShop → ERLI.
10. Cron: uruchom kontrolnie cztery niezależne adresy z install=1, potem dodaj je do harmonogramu.

3. Instalacja, aktualizacja i zgodność

Instalacja

1. W PrestaShop przejdź do Moduły i wgraj paczkę ZIP Astra ERLI.
2. Po instalacji otwórz konfigurację modułu. Moduł sam przygotowuje wymagane elementy bazy danych.
3. Jeżeli paczka jest zakodowana ionCube, serwer musi mieć zgodny ionCube Loader.
4. Po pierwszym wejściu skonfiguruj połączenie i dopiero potem przejdź do mapowań.

Aktualizacja

Nową wersję wgrywaj na istniejący moduł. Nie odinstalowuj starej wersji, jeśli chcesz zachować mapowania, połączenia, reguły i ustawienia.

• wyczyść cache PrestaShop po podmianie plików,
• otwórz konfigurację Astra ERLI po aktualizacji,
• sprawdź aktywne połączenie,
• sprawdź ustawienia crona, wysyłek i statusów,
• wykonaj test jednej oferty i jednego zamówienia.

4. Połączenia ERLI

Każde konto ERLI jest osobnym połączeniem. Mapowania i automatyzacje są przypisane do konkretnego połączenia, dlatego przed zmianą ustawień zawsze sprawdź aktywne konto.

1. Wejdź w ERLI → Połączenia.
2. Dodaj nazwę połączenia i token API.
3. Wybierz środowisko Produkcyjne albo Sandbox.
4. Zapisz i sprawdź status połączenia.

5. Kategorie ERLI, cechy i marki

Mapowanie kategorii określa, do jakiej kategorii ERLI ma trafić produkt oraz jakie atrybuty i wartości należy zbudować z danych PrestaShop.

5.1. Słownik kategorii

1. Kliknij Załaduj kategorie z pliku modułu, aby szybko zapełnić lokalny indeks kategorii.
2. Opcjonalnie użyj Start / Wznów z API, aby odświeżyć drzewo z ERLI.
3. Osobno odświeżaj Cechy kategorii ERLI i Wartości cech ERLI.
4. W Cron ERLI możesz włączyć rotacyjne odświeżanie słowników i cech używanych kategorii.

5.2. Mapowanie kategorii PrestaShop → ERLI

Wybierz kategorię PrestaShop, wyszukaj kategorię ERLI po nazwie lub ścieżce i zapisz mapowanie.

5.3. Kopiowanie mapowań

Jeżeli kilka kategorii PrestaShop ma korzystać z tego samego układu ERLI, nie trzeba odtwarzać wszystkiego ręcznie.

• Skopiuj całe mapowanie z — przy tworzeniu nowego mapowania kopiuje kategorię ERLI, cechy i mapowania wartości.
• Użyj mapowania z — w tabeli zapisanych mapowań można skopiować mapowania cech pomiędzy kategoriami PrestaShop wskazującymi na to samo ID kategorii ERLI.
• W oknie Mapuj cechy dostępna jest również akcja kopiowania mapowań.

5.4. Źródła cech

Dla cech ERLI można korzystać m.in. z cech PrestaShop, grup kombinacji, producenta/marki, EAN, SKU/reference, nazwy, ID produktu, stanu oraz kodu producenta wyliczanego przez moduł.

5.5. Marka a producent GPSR

6. Katalog i mapowanie produktów ERLI ↔ PrestaShop

Lista ofert ERLI jest pobierana paczkami i zapisywana lokalnie. Moduł może automatycznie łączyć ofertę z produktem lub wariantem PrestaShop.

6.1. Synchronizacja całego katalogu

W Liście ofert na ERLI akcja synchronizacji pobiera katalog partiami po 200 pozycji. Każda paczka jest osobnym requestem, dzięki czemu duży katalog nie kończy się na pierwszych 200 ofertach.

6.2. Automatyczne dopasowanie

W Mapowaniu produktów można określić, czy moduł ma dopasowywać po:

• EAN13,
• SKU / reference,
• nazwie produktu.

6.3. Warianty

Mapowanie może wskazywać konkretną kombinację PrestaShop. Dzięki temu wariant 60 ml i 120 ml albo dwa rozmiary mogą mieć niezależne EAN, SKU, stock i osobne oferty ERLI.

6.4. Ręczne mapowanie

Jeżeli automatyczne dopasowanie jest błędne lub nie znajduje produktu, wybierz właściwy produkt/variant ręcznie. Wyszukiwanie obsługuje ID, nazwę, EAN i SKU.

7. Import ofert ERLI → PrestaShop

Niezmapowaną ofertę ERLI można nie tylko powiązać z istniejącym produktem, ale również utworzyć z niej nowy produkt w katalogu PrestaShop.

7.1. Polityka automatycznego importu

W Cron ERLI dostępne są trzy tryby:

7.2. Ręczny import z podglądem

Przycisk Importuj do PrestaShop przy pojedynczej ofercie otwiera podgląd. Przed wykonaniem importu widzisz nazwę, EAN/SKU, cenę, stock i kategorię ERLI oraz możesz zmienić decyzję:

• utwórz nowy produkt PrestaShop,
• powiąż z istniejącym produktem po podaniu jego ID,
• wybierz inną kategorię docelową PrestaShop.

7.3. Jak wybierana jest kategoria

Przy tworzeniu produktu moduł próbuje kolejno:

1. znaleźć zapisane mapowanie kategorii ERLI → PrestaShop dla aktywnego połączenia,
2. dopasować kategorię PrestaShop po nazwie najgłębszej kategorii ERLI,
3. użyć kategorii domyślnej sklepu.

W imporcie ręcznym operator może nadpisać tę sugestię.

7.4. Jakie dane są importowane

• nazwa produktu,
• SKU/reference, EAN i MPN,
• opis i opis skrócony,
• cena z ERLI przeliczana z groszy na walutę sklepu,
• stawka VAT,
• stan magazynowy i aktywność,
• producent,
• zdjęcia,
• istniejące cechy PrestaShop o tej samej nazwie.

8. Ustawienia wystawiania ofert

8.1. Czas wysyłki i cennik dostawy

Ustaw domyślny dispatch time i cennik dostawy. Są używane przy nowych ofertach.

8.2. Dokumenty ERLI

Listy dokumentów można odświeżać z ERLI. Puste pole oznacza użycie domyślnych warunków konta tam, gdzie ERLI to dopuszcza.

8.3. Kod producenta

Możesz wskazać źródła kodu producenta i ich kolejność: reference, MPN, UPC, EAN/JAN, ISBN. Moduł używa pierwszego niepustego źródła. Automatyczne ustalanie można wyłączyć.

8.4. GPSR

Producent GPSR jest wymagany do wystawienia oferty. Możesz użyć producenta produktu, stałego producenta albo danych ręcznych. Podmiot odpowiedzialny pozostaje opcjonalny.

8.5. Opis

Cechy PrestaShop mogą być dopisywane do opisu zawsze, tylko przy braku opisu albo nigdy. Położenie bloku cech można ustawić nad lub pod opisem.

9. Wystawianie i aktualizowanie ofert

Produkty oraz warianty PrestaShop są traktowane jako osobne pozycje, dzięki czemu każda kombinacja może mieć własne mapowanie i ofertę ERLI.

9.1. Filtry

• wyszukiwanie po produkcie,
• aktywność produktu PrestaShop,
• status oferty ERLI,
• stan magazynowy,
• Wszystkie / Tylko ze zdjęciami / Tylko bez zdjęć.

9.2. Konfigurator pojedynczej oferty

1. Sprawdź kategorię ERLI i mapowanie cech.
2. Sprawdź cenę, stock i domyślny status.
3. Sprawdź GPSR, dokumenty, EAN/SKU, zdjęcia i opis.
4. W razie potrzeby zmień externalId lub wybierz utworzenie nowej oferty.
5. Użyj podglądu payloadu i dopiero potem wyślij ofertę.

9.3. Masowe wystawianie

Masowo wystawiaj dopiero produkty z poprawnymi mapowaniami kategorii i cech. Produkty z wariantami są liczone jako osobne pozycje.

10. Lista ofert na ERLI

Lista służy do kontroli lokalnego mapowania i ostatnich danych odczytanych z API ERLI.

10.1. Filtry

• externalId, nazwa, EAN, SKU,
• status aktywne / nieaktywne / archiwalne,
• stan PrestaShop > 0 lub ≤ 0,
• kategoria PrestaShop,
• minimalna różnica ceny ERLI względem ceny docelowej.

10.2. Akcje przy ofercie

W pierwszej linii znajdują się akcje statusu, stanu i ceny. Jeżeli oferta ERLI nie ma produktu PrestaShop, osobny przycisk Importuj do PrestaShop jest pokazany niżej, aby nie rozszerzać tabeli.

10.3. Synchronizacja stanu

Okno stanu pokazuje stock PrestaShop, ostatni stock ERLI, stock live z API, źródło reguły i szczegółowe wyliczenie.

10.4. Ręczna cena

Możesz wysłać cenę ręcznie. Jest to operacja jednorazowa — późniejszy cron cen może ponownie policzyć cenę według ustawień globalnych.

11. Stany magazynowe i aktywność ofert

Od 4.12 reguły stanu są jawne: oferta może korzystać z ustawień crona albo z własnej reguły produktu/wariantu. W oknie synchronizacji widać, skąd pochodzi wynik.

11.1. Reguła globalna

W Cron ERLI ustawiasz:

• Globalną korektę stanu,
• Wyłącz ofertę przy stanie ≤,
• Zeruj stan produktów nieaktywnych.

11.2. Próg wyłączenia

11.3. Produkt nieaktywny w PrestaShop

Produkt z active=0 zawsze otrzymuje w ERLI status inactive. Osobne ustawienie decyduje o ilości:

• Nie — zachowaj wyliczony stan: oferta jest nieaktywna, ale stock po korekcie zostaje zachowany.
• Tak — stock=0: po całym wyliczeniu moduł dodatkowo wymusza zero.

11.4. Reguła własna produktu

Domyślnie oferta bierze korektę i próg z crona. Dopiero po wybraniu Własna zasada produktu / wariantu zapisuje się indywidualna korekta i próg. Powrót do ustawień crona usuwa własną regułę stanu, ale nie narusza indywidualnych ustawień ceny.

12. Ceny i promocje

12.1. Cena źródłowa w 4.12.9

Źródłem zwykłej ceny jest aktualna cena sprzedaży PrestaShop. Oznacza to cenę po SpecificPrice i Catalog Price Rules. W obecnej wersji pole źródła jest ustawione na tryb current.

12.2. Zakres korekty

Narzut i stała korekta mogą dotyczyć:

• wszystkich produktów,
• tylko produktów bez aktywnej obniżki PrestaShop,
• tylko produktów z aktywną obniżką PrestaShop.

12.3. Zaokrąglenie

Dostępne są: brak dodatkowego zaokrąglenia, matematycznie do pełnych złotych, w górę do pełnych złotych oraz w górę do końcówki 0,99.

12.4. Promocja czasowa dla kategorii i produktów

Harmonogram promocji działa jako osobny /discount ERLI nakładany dodatkowo na zwykłą cenę wyliczoną powyżej.

• możesz zaznaczyć wiele zmapowanych kategorii PrestaShop,
• możesz wskazać konkretne produkty,
• kategorie i produkty są łączone jako OR,
• dla produktu z kombinacjami promocja obejmuje wszystkie jego zmapowane oferty/warianty,
• ustawiasz ujemny procent, datę/godzinę startu i końca.

12.5. Zmiana ceny w trakcie promocji

Jeżeli zmienia się cena bazowa produktu, moduł kończy starą promocję technicznie, potwierdza nową cenę zwykłą i zakłada promocję ponownie. Wyłączenie harmonogramu lub usunięcie produktu z zaznaczenia również kończy promocję przy najbliższym przebiegu.

12.6. Starsze promocje

Moduł rozpoznaje własne starsze wpisy promocji oraz przypadki frozen.price=true. Przy migracji odblokowuje wyłącznie cenę i nie zmienia innych pól frozen.

13. Pobieranie i import zamówień

Automat zamówień ma dwa niezależne filtry: status realizacji oraz sposób płatności/COD. Ręczne pobranie służy do świadomego importu poza tymi ograniczeniami.

13.1. Tryb płatności

13.2. Jak rozpoznawany jest COD

Najpierw po delivery.cod. Jeżeli pole nie występuje, moduł może użyć typu dostawy ERLI zapisanego jako metoda pobraniowa.

13.3. Statusy pobierane przez automat

Można zaznaczyć m.in.:

created, canceled, readyToProcess, inProgress, sent, readyToPickup, received, returned, returningToSender, unknown.

13.4. Pobieranie po zmianach

Cron pracuje po polu updated, dlatego starsze zamówienie może wejść ponownie do synchronizacji, jeśli w ERLI zmienił się status, tracking lub inne dane.

13.5. Ręczne „Pobierz i importuj zamówienia”

Ręczna akcja jest świadomym wyjątkiem:

• omija filtr płatności/COD,
• omija filtr statusów pobieranych przez automat,
• zawsze ignoruje aktywność przewoźnika.

Ręczne pobranie nadal wymaga danych, z których da się zbudować zamówienie — np. produkt musi być zmapowany albo utworzony, a przewoźnik nie może być rekordem usuniętym z PrestaShop.

13.6. Brak mapowania produktu

Z listy zamówień możesz wykonać szybkie mapowanie produktu ERLI do produktu PrestaShop. Jeżeli oferta nie ma odpowiednika, najpierw można utworzyć produkt z ERLI, a następnie ponowić import zamówienia.

13.7. Ochrona przed duplikatami

Jedno ID zamówienia ERLI odpowiada jednemu zamówieniu PrestaShop. Moduł nie tworzy ponownie drugiego zamówienia z tego samego ID ERLI.

14. Wysyłki, przewoźnicy i fallback

14.1. Typy wysyłki ERLI

W ERLI → Ustawienia wysyłek kliknij Pobierz dostępne typy z API. Lista może być również uzupełniana automatycznie, gdy nowy typ pojawi się w pobieranych zamówieniach.

14.2. Mapowanie

Dla każdego typu ERLI możesz ustawić:

• przewoźnika PrestaShop,
• status startowy PrestaShop.

14.3. Fallback

Jeżeli metoda ERLI nie ma własnego mapowania, używany jest:

• Fallback przewoźnika PS,
• Fallback status startowy PS.

14.4. Nieaktywny przewoźnik

Ustawienie Ignoruj aktywność przewoźnika przy imporcie zamówień steruje automatem:

• Nie: automat wymaga aktywnego przewoźnika.
• Tak: automat może utworzyć zamówienie także na przewoźniku wyłączonym w PrestaShop.

Przewoźnik usunięty lub nieprzypisany do bieżącego sklepu nadal blokuje import. Ręczny import zawsze ignoruje samą aktywność przewoźnika.

14.5. COD i moduł InPost

Jeżeli zamówienie ERLI jest pobraniowe, dane COD są zachowane w kontekście zamówienia. Na stronie zamówienia skrypt Astra ERLI może ustawić przełącznik COD w formularzu modułu InPost, jeżeli wykryje obsługiwane pola tego modułu.

15. Tracking, list przewozowy i etykiety

15.1. Tracking ERLI → PrestaShop

Jeżeli ERLI zwraca deliveryTracking.trackingNumber, cron zamówień może zapisać numer listu do order_carrier.tracking_number w PrestaShop. Ponieważ wyszukiwanie działa po updated, numer dodany później w ERLI może zostać pobrany przy kolejnym przebiegu.

15.2. Tracking PrestaShop → ERLI

W regule PrestaShop → ERLI można zaznaczyć wyślij list przewozowy. Dla zewnętrznych metod wysyłki moduł może utworzyć wpis przez shipping/external i wysłać numer trackingu.

15.3. Kolejność przy statusie sent

Gdy reguła wymaga trackingu oraz statusu sent, tracking jest wysyłany przed końcową zmianą statusu, aby ERLI nie otrzymało „wysłane” bez danych przesyłki.

15.4. Etykiety ERLI

Typ wysyłki, którego identyfikator zaczyna się od erli, jest traktowany jako metoda obsługiwana przez generator etykiet ERLI. Masowe generowanie jest dostępne na liście zamówień PrestaShop przez akcję Generuj Etykiety ERLI.

• dla braku etykiety moduł zleca jej utworzenie,
• dla istniejącej etykiety pobiera aktualny plik,
• przy wielu etykietach może utworzyć ZIP,
• zamówienia spoza ERLI są pomijane.

15.5. Additional information

W ustawieniach etykiet można budować shipping.additionalInformation z danych pozycji zamówienia, ustalać kolejność składników, separatory, limit długości, skracanie nazwy i czyszczenie tekstu.

16. Synchronizacja statusów i akcji

Reguły są rozdzielone na dwa kierunki i działają niezależnie.

16.1. ERLI → PrestaShop

Wybierz status/zdarzenie ERLI i status, który ma zostać ustawiony w PrestaShop. Ten sam niezmieniony status ERLI jest stosowany tylko raz — ręczna zmiana statusu w PrestaShop nie jest później cofana przez ten sam stary stan ERLI.

16.2. PrestaShop → ERLI

Dla statusu PrestaShop można skonfigurować:

• status ERLI,
• status paczki,
• wysłanie trackingu,
• opcjonalny e-mail do klienta.

16.3. Kolizja kilku reguł dla tego samego statusu PS

Jeżeli kilka aktywnych reguł wychodzących wskazuje ten sam status PrestaShop, moduł wybiera bardziej zaawansowany status ERLI. Ma to zapobiec cofnięciu np. z sent do readyToProcess.

16.4. Status po utworzeniu etykiety

Można wskazać status PrestaShop ustawiany bezpośrednio po poprawnym utworzeniu paczki w ERLI. Nie trzeba czekać na późniejsze pobranie PDF ani numeru trackingowego.

17. Cron i automatyzacja

Aktualna wersja używa czterech niezależnych adresów cron. Każdy ma osobną blokadę bazodanową i limit czasu. Stany, aktywność i ceny działają w jednym cronie.

17.1. Pierwsze uruchomienie

1. Otwórz ERLI → Cron.
2. Dla każdego z czterech adresów kliknij Pierwsze uruchomienie / kontrola bazy.
3. Po poprawnym teście dodaj adresy do harmonogramu serwera.
4. Zalecane uruchomienie: co minutę.

* * * * *

17.2. Limit czasu i blokady

Każdy cron może pracować około 15–30 sekund. Jeżeli poprzednie uruchomienie danego typu nadal działa, kolejne zostanie zablokowane, ale pozostałe trzy typy mogą działać niezależnie.

17.3. Daty startowe niezależnych cronów

Pod każdym adresem crona znajduje się pole daty. Pozwala ono dołożyć automat później bez przetwarzania niepotrzebnej historii.

17.4. Adres zgodności

Starszy wspólny adres crona nadal może być używany, ale od 4.12.9 nie ma sztywno zaszytej listy etapów. Pod adresem są checkboxy:

• Zamówienia,
• Statusy i tracking,
• Katalog ofert,
• Stany, aktywność i ceny.

Każdy zaznaczony etap respektuje blokadę i datę startową odpowiadającego mu niezależnego crona. Dla zgodności wstecznej domyślnie aktywne są zamówienia, katalog oraz stany/ceny. Statusy i tracking są domyślnie wyłączone, aby aktualizacja modułu nie uruchomiła historycznego pushu na wszystkich starych zamówieniach.

17.5. Najważniejsze ustawienia crona

• Zamówienia: automatyczny import, płatność/COD, data startowa, liczba stron, limit importu i statusy.
• Statusy: data startowa, pobieranie zmian ERLI oraz wykonywanie reguł wychodzących i trackingu.
• Stany: data uruchomienia, limit, korekta, próg, zerowanie produktu nieaktywnego.
• Ceny: narzut, korekta kwotowa, zakres, zaokrąglenie i promocja czasowa kategorii/produktów.
• Katalog: data uruchomienia, automatyczne odświeżanie katalogu i polityka importu ERLI → PrestaShop.
• Słowniki: odświeżanie kategorii, atrybutów i wartości.

18. Codzienna praca — gotowe scenariusze

Nowy produkt z PrestaShop → ERLI

1. Uzupełnij nazwę, SKU/EAN, cenę, stan i zdjęcia.
2. Sprawdź mapowanie kategorii i cech.
3. Otwórz konfigurator oferty i sprawdź GPSR oraz dokumenty.
4. Wyślij pojedynczą ofertę.
5. Po poprawnym teście używaj działań masowych.

Oferta istnieje w ERLI, ale nie w PrestaShop

1. Synchronizuj katalog ERLI.
2. Sprawdź, czy automat znalazł produkt po EAN/SKU/nazwie.
3. Jeżeli nie — użyj Importuj do PrestaShop.
4. W podglądzie wybierz powiązanie z istniejącym produktem albo utworzenie nowego.
5. Sprawdź proponowaną kategorię i zatwierdź.

Nowe zamówienie ERLI

1. Automat pobiera zamówienie, jeśli przejdzie filtr płatności/COD i statusu.
2. Jeżeli produkt jest zmapowany i przewoźnik jest dopuszczony, tworzy zamówienie PrestaShop.
3. Jeżeli chcesz świadomie pobrać zamówienie poza filtrem, użyj importu ręcznego.
4. Po imporcie kontroluj zakładkę ERLI na zamówieniu.
5. Tracking dodany później w ERLI zostanie pobrany po zmianie updated.

Nieaktywna metoda przewoźnika

1. Jeżeli chcesz, aby automat jej nie używał — pozostaw „Ignoruj aktywność przewoźnika” = Nie.
2. Jeżeli ma być dopuszczona — ustaw Tak.
3. Ręczny import zawsze pomija kontrolę aktywności.

Bezpieczny test stanów i cen

• ustaw limit zmian na 1,
• otwórz okno „Synchronizuj stan” i sprawdź pełne wyliczenie,
• porównaj wynik ERLI live,
• dopiero potem zwiększ limit.

19. Diagnostyka i najczęstsze sytuacje

Najważniejsze logi przy zgłoszeniu

• cron-runner-YYYY-MM-DD.log — przebieg automatyzacji,
• erli-api-YYYY-MM-DD.log — request/response API,
• erli-orders-search-YYYY-MM-DD.log — wyniki i filtry wyszukiwania zamówień,
• order-import-YYYY-MM-DD.log — tworzenie zamówienia PrestaShop,
• logi pojedynczego zamówienia/oferty — do diagnozy konkretnego ID.