Instrukcja Erli

 

1. Zakres funkcjonalny

Moduł AS ERLI integruje sklep PrestaShop z kontem/kontami sprzedawcy ERLI w zakresie obsługi zamówień oraz etykiet wysyłkowych. Integracja opiera się o REST API ERLI i skrypty CRON uruchamiane na serwerze sklepu.

  • Pobieranie zamówień z ERLI i tworzenie odpowiadających im zamówień w PrestaShop (import).
  • Mapowanie metody dostawy ERLI na: status początkowy w PrestaShop oraz przewoźnika (Carrier) w PrestaShop.
  • Generowanie i pobieranie etykiet ERLI (pojedynczo w zamówieniu lub masowo z listy zamówień).
  • Synchronizacja wybranych zmian statusów: ERLI → PrestaShop (np. „w drodze”, „dostarczono”).

2. Dostęp do modułu w panelu PrestaShop

Po instalacji modułu pojawiają się następujące miejsca w panelu:

  • Moduły → Menedżer modułów → AS Erli | PrestaShop ⇄ Erli → Konfiguruj (ustawienia kont ERLI i mapowania).
  • Menu ERLI → Zamówienia ERLI (podgląd listy zamówień z ERLI i informacja, czy zostały już zaimportowane).
  • Widok pojedynczego zamówienia (Zamówienia → szczegóły) → dodatkowa zakładka „ERLI” (etykiety i informacje o zamówieniu ERLI).
  • Lista zamówień (Zamówienia) → akcja masowa „Generuj Etykiety ERLI” (jeżeli dostępna w danej wersji PrestaShop/konfiguracji).

3. Konfiguracja integracji

3.1. Zakładki ERLI (wiele kont lub wiele sklepów ERLI)

Moduł pozwala skonfigurować wiele „zakładek”, z których każda reprezentuje oddzielny zestaw danych dostępowych do ERLI (np. różne konta sprzedawcy lub różne środowiska).

  1. W panelu ERLI przejdź do: Ustawienia sklepu → Metoda integracji i wygeneruj Klucz API sklepu.
  2. W PrestaShop przejdź do: Moduły → Menedżer modułów → AS ERLI → Konfiguruj. W sekcji „Zakładki modułu” kliknij Dodaj i uzupełnij pola: Nazwa (dowolna), Token autoryzacyjny (wklej klucz API sklepu) oraz API URL: https://erli.pl/svc/shop-api/.
  3. Kliknij Zapisz (Save). Nowa zakładka pojawi się na liście u góry strony.

Wymagane pola:

  • Token autoryzacyjny – wklej Klucz API sklepu wygenerowany w ERLI.
  • Nazwa sklepu – dowolna nazwa zakładki (np. „ERLI – sklep główny”).
  • API URL – https://erli.pl/svc/shop-api/ (zalecane wraz z końcowym znakiem „/”).

3.2. Edycja lub usunięcie zakładki

  1. Wybierz zakładkę z listy u góry konfiguracji.
  2. Zmień wartości (Nazwa sklepu / Token / API URL) i kliknij Zapisz.
  3. Aby usunąć zakładkę, kliknij przycisk Usuń i potwierdź komunikat.

3.3. Weryfikacja połączenia

Po wejściu w zakładkę moduł weryfikuje połączenie z ERLI. Jeżeli autoryzacja jest poprawna, przy danej zakładce (obok przycisku „Usuń”) pojawią się trzy opcje konfiguracji: „Mapowanie Statusu Początkowego”, „Mapowanie Przewoźników” oraz „Mapowanie Kroków”. W przypadku problemu z połączeniem zobaczysz komunikat o braku połączenia (np. błędny klucz API lub niepoprawny API URL).

4. Mapowania (konfiguracja obowiązkowa przed uruchomieniem CRON)

Mapowania są konfigurowane osobno dla każdej zakładki ERLI. Przyciski mapowań są dostępne wyłącznie, gdy połączenie z ERLI działa (status „OK”).

4.1. Mapowanie statusu początkowego (metoda dostawy ERLI → status PrestaShop)

Ustaw, jaki status ma otrzymać nowo importowane zamówienie w PrestaShop w zależności od metody dostawy ERLI (typeId).

  1. W konfiguracji zakładki kliknij „Mapowanie Statusu Początkowego”.
  2. Dla każdej pozycji (metody dostawy ERLI) wybierz status zamówienia PrestaShop z listy.
  3. Kliknij Zapisz.

Uwaga: brak mapowania dla danej metody dostawy może uniemożliwić poprawne utworzenie zamówienia.

4.2. Mapowanie przewoźników (metoda dostawy ERLI → przewoźnik PrestaShop)

Ustaw, jakiego przewoźnika (Carrier) ma używać zamówienie w PrestaShop dla danej metody dostawy ERLI.

  1. W konfiguracji zakładki kliknij „Mapowanie Przewoznikow”.
  2. Dla każdej metody dostawy ERLI wybierz odpowiadającego przewoźnika PrestaShop.
  3. Kliknij Zapisz.

4.3. Mapowanie kroków zamówienia (statusy PrestaShop używane w automatyce)

Mapowanie kroków jest wykorzystywane przez automatyzację (cron.php) do wyboru statusów, które mają być ustawiane w PrestaShop podczas obsługi etykiet i statusów dostawy.

  1. W konfiguracji zakładki kliknij „Mapowanie Kroków”.
  2. Ustaw wartości:
  • status po wygenerowaniu etykiety (krok_generuj)
  • status po wysłaniu (krok_w_drodze)
  • status po dostarczeniu (krok_dostarczono)
  • status po zwróceniu (krok_zwrocono) – jeżeli obsługiwane w procesie
  1. Kliknij Zapisz.

5. Obsługa zamówień i etykiet

5.1. Podgląd zamówień ERLI w panelu (ERLI → Zamówienia ERLI)

W menu ERLI → Zamówienia ERLI widoczna jest lista zamówień pobrana z ERLI (z ostatnich 7 dni). Tabela zawiera m.in. identyfikator zamówienia ERLI, status w ERLI, datę utworzenia, informację czy zamówienie zostało zaimportowane oraz ID zamówienia w PrestaShop (jeżeli istnieje).

  • „Pobrane = TAK” oznacza, że zamówienie zostało już utworzone w PrestaShop i zapisane w tabeli modułu.
  • „prestalinker id” pozwala szybko znaleźć odpowiadające zamówienie w PrestaShop.

5.2. Zakładka „ERLI” w szczegółach zamówienia

W widoku zamówienia w PrestaShop pojawia się dodatkowa zakładka „ERLI”. Znajdziesz tam:

  • ID zamówienia w ERLI.
  • Rodzaj przewoźnika z ERLI (delivery.typeId).
  • Obsługę etykiety (w zależności od rodzaju dostawy).

Jeżeli rodzaj dostawy w ERLI zaczyna się od „erli…” (wysyłka obsługiwana przez ERLI), dostępne jest generowanie etykiety z poziomu zakładki:

  • Wprowadź wymiary paczki (szerokość, wysokość, długość) oraz wagę. W tym miejscu możesz ustawić własną wielkość paczki – te parametry zostaną użyte do utworzenia etykiety.
  • Kliknij „Generuj etykietę”.
  • Po wygenerowaniu pojawi się przycisk/link „Pobierz etykietę”.

Etykiety w module są dostępne wyłącznie dla dostaw ERLI, tj. gdy delivery.typeId zaczyna się od „erli…”. Dla pozostałych metod dostawy etykiety ERLI nie są generowane w module.

5.3. Generowanie etykiet masowo (lista zamówień → akcje masowe)

Jeżeli w Twoim panelu PrestaShop dostępna jest akcja masowa „Generuj Etykiety ERLI”, możesz wygenerować etykiety dla wielu zamówień jednocześnie.

  1. Zamówienia → zaznacz zamówienia na liście.
  2. Wybierz akcję masową „Generuj Etykiety ERLI”.
  3. Moduł wygeneruje etykiety w ERLI dla zamówień z obsługiwanymi metodami dostawy ERLI i przygotuje plik do pobrania.

Uwagi operacyjne:

  • Akcja masowa działa tylko dla metod dostawy ERLI obsługiwanych przez moduł (np. erliLocker, erliCourier, erliPickupPoint, erliCourierPalette, erliAllegroOne, erliOrlen).
  • Jeżeli dla zamówienia istnieje już aktywna etykieta w ERLI, moduł pobierze ją zamiast generować nową.
  • Dla wielu etykiet przygotowywany jest plik ZIP; dla pojedynczej etykiety – plik PDF.
  • Na liście zamówień podczas generowania etykiet wykorzystywany jest domyślny rozmiar paczki z ERLI.

6. Automatyzacja – CRON

Moduł wykorzystuje skrypt CRON uruchamiany cyklicznie na serwerze sklepu. Adres cron.php jest wyświetlany w konfiguracji każdej zakładki.

6.1. cron.php – import zamówień i synchronizacja statusów/trackingu

Skrypt wykonuje, per zakładka ERLI, następujące kroki:

  1. Pobiera listę zamówień z ERLI (ostatnie 7 dni, limit 200 rekordów).
  2. Importuje nowe zamówienia opłacone („purchased”), których nie ma jeszcze w bazie modułu – tworzy klienta (gość), adresy, koszyk i zamówienie w PrestaShop (limit 20 zamówień na jedno uruchomienie).
  • Mapowanie produktów odbywa się po EAN13 albo po indeks/SKU (reference). Jeżeli produkt nie zostanie znaleziony, moduł tworzy jednorazowo „pusty” produkt z przepisanym SKU i EAN z ERLI (do późniejszego uzupełnienia w PrestaShop).
  1. Dla wcześniej zaimportowanych zamówień monitoruje status w ERLI i aktualizuje status w PrestaShop zgodnie z mapowaniem kroków (np. „w drodze”, „dostarczono”).
  2. Uzupełnia w PrestaShop numer przesyłki, jeżeli jest dostępny w ERLI, a w PrestaShop brakuje trackingu.

Logika synchronizacji statusów (ERLI → PrestaShop) opiera się na wartościach sellerStatus w ERLI (m.in. sent, readyToPickup, received).

6.3. Przykładowe uruchomienia CRON (do ustawienia na serwerze)

Poniższe przykłady mają charakter poglądowy (dokładna forma zależy od środowiska serwera):

  • php (zamówienia): uruchamiaj np. co 5 minut: curl -s https://TWOJ-DOMEN/modules/as_erli/cron.php >/dev/null

Rekomendacja bezpieczeństwa: skrypty CRON są dostępne jako URL. W środowisku produkcyjnym zalecane jest ograniczenie dostępu (np. whitelist IP serwera CRON lub dodatkowe zabezpieczenie na poziomie serwera WWW).

7. Diagnostyka i typowe problemy

7.1. Brak połączenia (status „NIE POŁĄCZONO”)

  • Zweryfikuj Token autoryzacyjny i API URL w danej zakładce.
  • Upewnij się, że API URL jest poprawnym adresem bazowym i zawiera wymagany prefiks/ukośnik zgodnie z dokumentacją ERLI.
  • Sprawdź, czy serwer sklepu ma możliwość połączenia wychodzącego do API ERLI (firewall).

7.2. Zamówienia nie importują się

  • Sprawdź, czy zamówienia w ERLI mają status „purchased” (opłacone).
  • Upewnij się, że skonfigurowano mapowanie statusu początkowego oraz przewoźników dla metod dostawy występujących w zamówieniach.
  • Zweryfikuj zgodność produktów: moduł identyfikuje produkty po EAN (ean13) lub SKU (reference) w PrestaShop. Jeżeli brak dopasowania, moduł utworzy jednorazowo „pusty” produkt z przepisanym SKU i EAN z ERLI.

7.3. Problemy z etykietą

  • Etykiety są dostępne wyłącznie dla metod dostawy obsługiwanych przez ERLI (delivery.typeId zaczyna się od „erli…”).
  • Jeżeli etykieta nie generuje się, upewnij się, że wprowadzono poprawne wymiary i wagę paczki.
  • Jeżeli etykieta została już utworzona w ERLI, moduł powinien umożliwić jej pobranie bez generowania ponownie.

8. Najważniejsze adresy (dla administratora)

W konfiguracji modułu może pojawić się poniższa ścieżka (względem domeny sklepu):

  • CRON – zamówienia: /modules/as_erli/cron.php