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.

Najważniejsze ustawienia w wersji 4.14.7

Instrukcja opisuje zachowanie paczki 4.14.7. Ustawienia i mapowania dotyczą wybranego połączenia, chyba że przy danej opcji wskazano wspólny zakres dla sklepu.

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.

Przed aktualizacją do 4.14.7

1. Wykonaj kopię bazy i katalogu modułu, w tym istniejących etykiet.
2. Nadpisz pliki pełną paczką w modules/astraerli/. Nie resetuj ani nie odinstalowuj modułu.
3. Zapewnij zapis do modules/astraerli/etykieta/ i zablokuj bezpośrednie pobieranie zawartości tego katalogu przez WWW — szczegóły w punkcie 15.8.
4. Wyczyść cache PrestaShop i odśwież panel przez Ctrl+F5. Jeżeli serwer nadal wykonuje stary kod PHP, odśwież także OPcache.
5. Sprawdź import jednego nowego produktu z zamówienia, etykietę z listy i wyliczenie stanu jednej oferty.

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.

Uprawnienia klucza API

W zakładce Połączenia sprawdź panel Uprawnienia klucza API ERLI. Odczyt katalogu lub zamówień i zapis zmian mogą wymagać różnych zakresów. Opcjonalne kolejki potrzebują uprawnienia order lub product, ponieważ potwierdzają przetworzenie zdarzeń. Sam zakres odczytu nie wystarczy.

Jeżeli ERLI nie zwróci listy scopes, starszy klucz może nadal działać. Oceniaj wynik konkretnej operacji, zamiast zakładać brak uprawnień wyłącznie z powodu braku tej listy.

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

5.6. Masowe kopiowanie kategorii i mapowań

1. Przygotuj kategorię wzorcową PrestaShop z poprawną kategorią ERLI oraz mapowaniami cech i wartości.
2. Kliknij Masowo użyj mapowania z… i wybierz wzorzec.
3. Odszukaj kategorie docelowe po nazwie lub ID. Możesz filtrować po obecnej kategorii ERLI i statusie mapowania.
4. Zaznacz cele i wybierz Zastosuj mapowanie do zaznaczonych. Sprawdź raport operacji.

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, domyślnie 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.

7.5. „Importuj i utwórz produkt z ERLI” na liście zamówień

1. Otwórz listę zamówień ERLI i znajdź zamówienie z informacją o brakującym mapowaniu.
2. Jeżeli produkt już istnieje w PrestaShop, powiąż go z właściwą pozycją. Jeżeli go nie ma, użyj Importuj i utwórz produkt z ERLI.
3. Po operacji sprawdź kartę utworzonego produktu: opis, zdjęcia, cenę, stan, cechy i mapowanie. Odczytaj ewentualne ostrzeżenia.
4. Sprawdź wynik importu zamówienia. Jeśli import zatrzymał się na innym błędzie, np. przewoźniku, popraw ustawienie i ponów import zamówienia.

7.6. Opisy i nazwy cech

Import z katalogu i z zamówienia odczytuje sekcje opisu ERLI z tekstem, HTML i obrazami, zachowując ich kolejność. Nazwy cech i wartości są rozwiązywane przez słowniki właściwej kategorii ERLI. Powtarzające się cechy są łączone. Import z zamówienia może utworzyć brakujące cechy o rozpoznanych nazwach; import katalogowy stosuje ostrożną politykę opisaną w punkcie 7.4.

Jeżeli nazwa nie jest dostępna, moduł pokazuje ostrzeżenie zamiast zapisywać sam numer jako nazwę cechy. Sprawdź kategorię produktu, odśwież słownik cech i wartości dla bieżącego połączenia oraz zweryfikuj dostępność danych w ERLI.

7.7. Stan nowo utworzonego produktu

Przy tworzeniu produktu z zamówienia moduł zapisuje aktualny stan pobrany z ERLI. Import tego samego zamówienia nie odejmuje drugi raz kupionej ilości od właśnie zapisanego stanu.

Informacja o pobranym stanie jest zachowywana również przy ponowieniu importu po błędzie. Wcześniej utworzony produkt można wyrównać akcją Pobierz stan z ERLI do Presty, po sprawdzeniu mapowania i upewnieniu się, że stan ERLI jest właściwym źródłem.

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

Formularz modułu wymaga wskazania producenta GPSR przy wystawianiu oferty. Możesz użyć producenta produktu, stałego producenta albo danych ręcznych. Pole podmiotu odpowiedzialnego w module jest opcjonalne; uzupełnij je, jeśli jest wymagane dla danego produktu.

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.

8.6. Warunki zwrotów, reklamacji i gwarancji

Listy warunków są pobierane bezpośrednio z ERLI. W panelu Warunki w ERLI — nowe API można odczytać i, zgodnie z uprawnieniami, utworzyć lub zmienić warunki. Zaawansowana edycja korzysta z formularza JSON. Przed zapisaniem zweryfikuj właściwy identyfikator i rynek.

Błąd odświeżenia nie oznacza usunięcia istniejących warunków — moduł zachowuje listę z pamięci lokalnej i wyświetla komunikat. Warunki używane przez oferty lub domyślne mogą nie pozwalać na usunięcie; konflikt jest pokazywany w panelu.

Wybór rynku w operacjach na warunkach nie oznacza pełnej automatycznej obsługi sprzedaży zagranicznej, przeliczania PLN/EUR ani tłumaczenia ofert.

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

Regułę można ustawić wspólnie dla ofert danego połączenia albo indywidualnie dla produktu lub wariantu. Okno „Synchronizuj stan” pokazuje źródło reguły i pełne wyliczenie.

11.1. Wspólna korekta i próg dla wielu ofert

1. Wybierz właściwe połączenie i otwórz ERLI → Cron → Stany magazynowe i ceny.
2. Włącz Automatycznie wysyłaj stany magazynowe do ERLI.
3. Ustaw Globalną korektę stanu oraz Wyłącz ofertę przy stanie ≤.
4. Zapisz formularz, sprawdź wynik jednej oferty i uruchom cron stanów z małym limitem zmian.

11.2. Jak obliczany jest stan

Próg jest porównywany ze stanem PrestaShop przed korektą. Jeśli próg działa i stan PS jest mniejszy lub równy progowi, do ERLI trafia 0 i oferta jest wyłączana. W pozostałych przypadkach ilość wynosi max(0, stan PS + korekta). Dodatnia ilość pozwala na aktywność oferty, z uwzględnieniem ustawienia z punktu 11.3.

11.3. Produkt nieaktywny w PrestaShop

Opcja Dezaktywuj ofertę ERLI, gdy produkt ma active=0 w PrestaShop decyduje, czy wyłączenie produktu PS ma dodatkowo wyłączyć ofertę ERLI.

• Włączona: oferta ERLI otrzymuje status nieaktywny. Pole Stan przy automatycznej dezaktywacji pozwala wybrać „Zachowaj wyliczony stan” albo „Wyślij stock=0”.
• Wyłączona: sama nieaktywność produktu PS nie wymusza wyłączenia ERLI. Nadal działają korekta, próg i reguły synchronizacji ceny.

11.4. Własna reguła lub powrót do ustawień globalnych

1. W Mapowaniu produktów otwórz Synchronizuj stan dla właściwego produktu lub wariantu.
2. Aby wprowadzić wyjątek, wybierz Własna zasada produktu / wariantu, wpisz korektę i próg, a następnie wyślij stan.
3. Aby przywrócić dziedziczenie, wybierz Ustawienia crona (domyślna zasada) i wyślij stan.

Zwykłe wysłanie stanu z ustawień crona nie zapisuje przypadkowo własnej reguły. Powrót do dziedziczenia nie usuwa indywidualnych ustawień ceny. Podgląd, wysłanie i pobranie stanu uwzględniają wariant wskazany w mapowaniu.

12. Ceny i promocje

12.1. Cena źródłowa

Źródłem jest aktualna cena sprzedaży PrestaShop, uwzględniająca ceny specyficzne i reguły cenowe katalogu. Następnie moduł stosuje narzut lub obniżkę procentową, stałą korektę i zaokrąglenie. Włącz Automatycznie wysyłaj ceny do ERLI w sekcji „Stany magazynowe i ceny”. Ceny obsługuje ten sam cron co stany i aktywność.

12.2. Zakres korekty

Narzut i stała korekta mogą dotyczyć wszystkich produktów, tylko produktów bez aktywnej obniżki PS albo tylko produktów z aktywną obniżką PS. Obniżka jest rozpoznawana przez porównanie aktualnej ceny sprzedaży z ceną bazową.

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 i w górę do końcówki 0,99.

12.4. Promocja czasowa kategorii i produktów

1. Włącz harmonogram promocji w ustawieniach crona stanów i cen.
2. Zaznacz zmapowane kategorie PrestaShop lub wskaż produkty, korzystając z wyszukiwarki ID/nazwy.
3. Wpisz ujemny procent obniżki oraz początek i koniec promocji. Zapisz ustawienia.
4. Sprawdź wynik po uruchomieniu crona. Rozpoczęcie i zakończenie promocji zależy od jego wykonania.

Kategorie i produkty są łączone jako OR: wystarczy spełnienie jednego z tych warunków. Dla produktów z kombinacjami obejmowane są ich zmapowane oferty/warianty.

12.5. Zmiana ceny i zakończenie promocji

Zmiana ceny źródłowej w trakcie promocji powoduje ponowne wyliczenie wartości z obniżką. Wyłączenie harmonogramu, zakończenie jego terminu lub usunięcie produktu z zakresu powoduje przywrócenie zwykłej ceny przy kolejnym przebiegu crona.

12.6. Kontrola zgodności i limity

Limit zmian cen określa liczbę rzeczywistych zmian w jednym przebiegu, w tym zmian z harmonogramu. Kontrolne odświeżanie cen działa osobno: moduł dobiera najstarsze aktywne oferty i dostosowuje liczbę do częstotliwości uruchamiania. Celem jest sprawdzenie katalogu w około 20 godzin, z zapasem do 24 godzin; duża zaległość, limit czasu lub błędy mogą wydłużyć ten okres.

Rotacyjny audyt odczytuje ceny w ERLI i kieruje rozbieżności do wspólnej kolejki. Oferty pominięte przez warunki aktywności lub stanu nie muszą oznaczać błędu — sprawdź reguły dla tych ofert.

12.7. Blokada ceny po starszej wersji

Jeżeli starsza wersja pozostawiła frozen.price=true, moduł odblokowuje wyłącznie cenę, sprawdza wynik i dopiero wtedy wysyła nową wartość. Pozostałe pola blokad oferty pozostają bez zmian.

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

W obrębie danego połączenia 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.

14.6. Punkty nadania

Wybierz połączenie, kliknij Pobierz punkty nadania z API i ustaw Domyślny punkt nadania albo wybór przy konkretnej metodzie dostawy.

14.7. Opcjonalna kolumna ERLI na liście zamówień

1. Otwórz ERLI → Ustawienia wysyłek.
2. Znajdź Kolumna ERLI na liście zamówień.
3. Zaznacz lub odznacz Pokazuj kolumnę ERLI z przyciskiem etykiety i zapisz ustawienia wysyłek.
4. Otwórz lub odśwież standardową listę zamówień PrestaShop.

Domyślnie kolumna jest włączona. Po wyłączeniu znika w całości, a moduł pomija odczyt danych potrzebnych do jej przycisków. Ustawienie obejmuje wszystkie połączenia ERLI w wybranym kontekście sklepu PrestaShop. Obsługa w szczegółach zamówienia i akcje masowe pozostają dostępne.

15. Tracking, list przewozowy i etykiety

15.1. Tracking ERLI → PrestaShop

Cron zamówień pobiera zwrócony przez ERLI numer listu i zapisuje go przy zamówieniu PrestaShop. Wyszukiwanie po dacie zmiany pozwala pobrać numer dopisany później. Komunikat „bez zmiany listu” oznacza, że odebrany numer jest już zgodny; licznik 0 nowych numerów nie jest sam w sobie błędem.

15.2. Tracking PrestaShop → ERLI

W regule statusu zaznacz wyślij list przewozowy i włącz wykonywanie reguł w cronie statusów. Moduł szuka najnowszego niepustego numeru w danych przewoźników zamówienia, a następnie w numerze wysyłki zamówienia. Dla przesyłek zewnętrznych przekazuje numer do ERLI lub aktualizuje już istniejącą przesyłkę.

Ta funkcja nie tworzy numeru w systemie firmy kurierskiej. Numer musi wcześniej powstać w ERLI lub module przewoźnika i zostać zapisany w PrestaShop.

15.3. Status i numer listu działają niezależnie

Brak numeru listu nie blokuje wysłania statusu zamówienia do ERLI. Jeżeli reguła wymaga trackingu, moduł zapamiętuje to zadanie i ponawia wysłanie numeru po jego pojawieniu się — również wtedy, gdy zamówienie przeszło już na inny status. Nie trzeba ponownie ustawiać poprzedniego statusu.

15.4. Pobranie etykiety z listy zamówień

Na standardowej liście zamówień PrestaShop kolumna ERLI zawiera mały przycisk przy zamówieniach pochodzących z ERLI. Podpowiedź po najechaniu brzmi „Etykieta ERLI”. Lista nie odpytuje w tle etykiet dla kolejnych zamówień.

1. Kliknij ERLI przy wybranym zamówieniu.
2. Moduł najpierw sprawdza zapisaną kopię etykiety w swoim folderze. Jeśli jest dostępna, pobiera plik bez odpytywania ERLI.
3. Jeżeli kopii brakuje, sprawdza istniejące przesyłki w ERLI i pobiera ich etykiety.
4. Dopiero po potwierdzeniu braku aktywnej przesyłki zleca jej utworzenie i pobranie etykiety — dla metod obsługiwanych przez generator ERLI.

Przycisk jest blokowany na czas operacji. Gdy przesyłka już istnieje, ale PDF jest jeszcze przygotowywany, moduł oczekuje na plik do około 2 minut. Sprawdzanie dotyczy wyłącznie klikniętego zamówienia.

15.5. Szczegóły zamówienia i dodatkowa przesyłka

W bloku ERLI na zamówieniu można pobrać etykietę oraz świadomie użyć Wygeneruj dodatkową etykietę ERLI, gdy zamówienie wymaga kolejnej paczki. Ta druga akcja tworzy dodatkową przesyłkę — nie służy do zwykłego ponownego pobrania istniejącego pliku.

Przy generowaniu używane są ustawienia paczki i punktu nadania. Metody o identyfikatorze zaczynającym się od erli są obsługiwane przez generator ERLI. Pracownik musi mieć odpowiednie uprawnienia; samo prawo podglądu pozwala pobrać istniejący plik, ale nie uprawnia do automatycznego utworzenia przesyłki.

15.6. Pobieranie masowe i format pliku

Na liście zamówień zaznacz pozycje i wybierz akcję Generuj Etykiety ERLI. Zamówienia spoza ERLI są pomijane. Wyniki poszczególnych operacji należy sprawdzić w raporcie.

W ERLI → Etykiety, w sekcji „Pobieranie etykiet ERLI”, ustaw sposób pobierania, gdy jest więcej niż jedna etykieta:

• Scalony PDF — wszystkie etykiety w jednym pliku.
• ZIP — osobne pliki PDF.

Dla jednej etykiety pobierany jest pojedynczy PDF. Ustawienie formatu jest wspólne dla pojedynczych i masowych operacji w module.

15.7. Additional info na etykiecie

W ustawieniach etykiet można zbudować dodatkową informację z pozycji zamówienia: wybrać składniki i ich kolejność, separatory, limit długości, skracanie nazw oraz czyszczenie tekstu. Sprawdź wynik na jednej etykiecie przed użyciem masowym.

15.8. Gdzie zapisywane są etykiety

W wersji 4.14.7 etykiety PDF/ZIP oraz pliki robocze zapisują się w modules/astraerli/etykieta/. Dane zadań masowych znajdują się w modules/astraerli/etykieta/_jobs/. Brak praw zapisu powoduje błąd; etykiety nie są wtedy zapisywane poza modułem.

Kopia lokalna powstaje po pobraniu gotowego pliku z ERLI. Samo utworzenie przesyłki nie oznacza jeszcze, że PDF został zapisany. Dostępne starsze pliki z poprzedniej prywatnej lokalizacji są kopiowane do folderu modułu bez usuwania oryginałów i bez nadpisywania nowszych plików.

• Apache: paczka zawiera blokadę .htaccess; hosting musi respektować jej reguły.
• Nginx lub Nginx obsługujący pliki przed Apache: administrator serwera musi zastosować reguły z config/nginx-labels.conf.example w konfiguracji sklepu. Samo wgranie pliku przykładowego na FTP nie włącza blokady.
• Kontrola po wdrożeniu: bezpośredni adres istniejącej etykiety powinien zwracać 403/404, a pobranie tej samej etykiety z panelu powinno działać.

16. Synchronizacja statusów i akcji

Reguły działają w dwóch kierunkach. W cronie statusów najpierw obsługiwane są zmiany PrestaShop → ERLI, a następnie odczyt ERLI → PrestaShop.

16.1. ERLI → PrestaShop

Przypisz status lub zdarzenie ERLI do właściwego statusu PrestaShop i włącz jego synchronizację. Powtórne odczytanie tego samego, niezmienionego statusu ERLI nie powinno cofać ręcznej zmiany wykonanej później w PS. Moduł chroni świeże zmiany lokalne również wtedy, gdy API ERLI zwraca jeszcze poprzedni stan.

16.2. PrestaShop → ERLI

Dla statusu PS możesz skonfigurować status zamówienia ERLI, status paczki, wysłanie numeru listu oraz opcjonalną wiadomość e-mail do klienta. Włącz Wykonuj reguły statusów, listów, anulowań i wiadomości, sprawdź datę Statusy / tracking od i uruchamiaj cron statusów.

Nowe wpisy historii statusów PS są przetwarzane chronologicznie, także gdy kilka zmian nastąpiło pomiędzy uruchomieniami crona. Pierwszy przebieg po aktualizacji uwzględnia bieżący status bez ponownego rozsyłania całej wcześniejszej historii. Zmiany wywołane importem statusu z ERLI są rozpoznawane, aby nie odsyłać ich jako nowej zmiany sprzedawcy.

16.3. Status, tracking i potwierdzenie wyniku

Status zamówienia jest wysyłany niezależnie od dostępności numeru listu. Tracking dopisany później pozostaje osobnym zadaniem do ponowienia. Moduł zapisuje powodzenie dopiero po potwierdzeniu przez ERLI; błąd pojedynczej pozycji odpowiedzi API również oznacza niepowodzenie.

Przy kilku regułach dla tego samego statusu PS sprawdź, czy nie są sprzeczne. Wybór bardziej zaawansowanego statusu w ramach takiej kolizji nie zastępuje chronologicznego przetwarzania rzeczywistych zmian historii zamówienia.

16.4. Status przesyłki

Reguły mogą przekazywać także doręczenie lub zwrot przesyłki, jeśli dany przewoźnik dopuszcza ręczną zmianę tego statusu w API. Odrzucenie takiej operacji sprawdź w logu; nie oznacza ono automatycznie błędu synchronizacji statusu samego zamówienia.

16.5. Status po utworzeniu etykiety

Można wskazać status PS ustawiany po potwierdzonym utworzeniu paczki w ERLI. Nie trzeba czekać na późniejsze pobranie PDF. Błąd utworzenia przesyłki nie powinien uruchamiać tej zmiany statusu.

17. Cron i automatyzacja

Aktualna wersja używa czterech podstawowych, niezależnych adresów cron oraz dwóch opcjonalnych adresów kolejek zdarzeń. 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.14.7 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, opcjonalna dezaktywacja produktu nieaktywnego i sposób wysyłania jego ilości.
• 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.

17.6. Dwie opcjonalne kolejki zdarzeń ERLI

W sekcji Nowe kolejki zdarzeń ERLI (opcjonalne) dostępne są osobne włączniki, daty startu, adresy, blokady i kontrola crona. Obie kolejki są domyślnie wyłączone.

1. Sprawdź zakresy klucza w Połączeniach. Uprawnienie wyłącznie do odczytu nie wystarcza do potwierdzania zdarzeń.
2. Wybierz datę startową i mały limit zdarzeń na przebieg, np. 1–3. Jedno zdarzenie może wymagać kilku zapytań.
3. Włącz potrzebną kolejkę, zapisz ustawienia i przetestuj jej adres z panelu.
4. Po sprawdzeniu wyniku dodaj włączony adres do harmonogramu, początkowo co kilka minut.

Zdarzenie jest potwierdzane dopiero po udanym przetworzeniu. Błąd importu, API lub potwierdzenia pozostawia je do ponowienia. Kolejki uzupełniają dotychczasowe crony — nie usuwaj z harmonogramu podstawowych zadań zamówień, statusów, katalogu i stanów/cen.

17.7. Jak czytać podsumowanie crona

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.

Etykieta bez otwierania zamówienia

1. Na liście zamówień kliknij ERLI przy wybranym zamówieniu.
2. Poczekaj na pobranie lub komunikat przygotowywania etykiety.
3. Gdy potrzebujesz tylko istniejącej etykiety, nie używaj akcji tworzenia dodatkowej przesyłki.

Wspólna korekta stanów

1. Ustaw korektę i próg w Cron → Stany magazynowe i ceny dla wybranego połączenia.
2. Sprawdź w oknie oferty, czy źródłem jest „Ustawienia crona”. Jeśli ma korzystać z reguły wspólnej, usuń wyjątek przez wybór tego źródła i wysłanie stanu.
3. Wykonaj kontrolny przebieg crona i porównaj ilość oraz aktywność oferty w ERLI.

19. Diagnostyka i najczęstsze sytuacje

Logi przy zgłoszeniu

Najpierw odczytaj tabelę logów w panelu crona. W razie potrzeby włącz diagnostykę plikową, wykonaj jedną konkretną operację i zanotuj godzinę, ID zamówienia/oferty oraz połączenie.

• cron-runner-YYYY-MM-DD.log — przebieg automatyzacji.
• erli-api-YYYY-MM-DD.log — kod HTTP, czas i metadane operacji; standardowy log nie zapisuje pełnej treści żądań i odpowiedzi ani nagłówka autoryzacji.
• erli-orders-search-YYYY-MM-DD.log — zakres i filtry wyszukiwania zamówień.
• order-import-YYYY-MM-DD.log — tworzenie zamówienia PS.
• Logi konkretnego zamówienia lub oferty — przyczyna błędu danej operacji.

Logi plikowe są przechowywane w prywatnej lokalizacji poza publiczną częścią sklepu, a ich domyślny okres przechowywania wynosi 14 dni. Ścieżka zależy od serwera. Jest to osobny mechanizm od folderu etykiet w module.