# Dokumentacja wtyczki Alsendo dla OpenCart 4.0

## Spis treści

1. [Instalacja](#instalacja)
2. [Deinstalacja](#deinstalacja)
3. [Konfiguracja wtyczki](#konfiguracja-wtyczki)
4. [Widok zamówienia](#widok-zamówienia)
5. [Pełny formularz zlecenia wysyłki](#pełny-formularz-zlecenia-wysyłki)
6. [Masowe zlecanie wysyłek](#masowe-zlecanie-wysyłek)
7. [Wymagania systemowe](#wymagania-systemowe)
8. [Często zadawane pytania (FAQ)](#często-zadawane-pytania-faq)

---

## Instalacja

### Krok 1: Przesłanie pliku wtyczki

1. Zaloguj się do panelu administracyjnego OpenCart (domyślnie: `https://<adres sklepu>/admin`)
2. Przejdź do zakładki **Extensions** → **Installer**
3. W prawym górnym rogu kliknij niebieski przycisk do przesyłania plików
4. Wybierz plik instalacyjny wtyczki (format `.ocmod.zip`)
5. Po przesłaniu pliku, w tabeli pojawi się nowy wiersz z nazwą "Alsendo"
6. Kliknij zielony przycisk **Install** przy wierszu "Alsendo"
7. Powinien pojawić się komunikat: **"Success: You have modified extensions!"**

### Krok 2: Aktywacja modułu

1. Przejdź do zakładki **Extensions** → **Extensions**
2. W polu **Choose the extension type** wybierz opcję **Modules**
3. W tabeli znajdź wiersz z nazwą **"Alsendo"**
4. Kliknij zielony przycisk **Install** przy wierszu "Alsendo"
5. Po instalacji wiersz "Alsendo" powinien mieć status **"Enabled"**
6. Kliknij przycisk edycji (ikona ołówka) przy wierszu "Alsendo", aby przejść do konfiguracji

### Krok 3: Weryfikacja instalacji

Po poprawnym zainstalowaniu wtyczki:
- W lewym menu panelu administracyjnego powinna pojawić się nowa zakładka **"Alsendo"**
- W zakładce "Alsendo" dostępne są następujące opcje:
  - Konfiguracja wtyczki
  - Ustawienia wysyłek
  - Konfiguracja mapowania
  - Dev logs

---

## Deinstalacja

### Krok 1: Deinstalacja modułu

1. Przejdź do zakładki **Extensions** → **Extensions**
2. W polu **Choose the extension type** wybierz opcję **Modules**
3. Przy wierszu **"Alsendo"** kliknij przycisk **Uninstall**
4. Odśwież stronę ręcznie (klawisz F5)
5. Sprawdź, czy zakładka **"Alsendo"** zniknęła z lewego menu dashboardu

### Krok 2: Usunięcie z instalatora

1. Przejdź do zakładki **Extensions** → **Installer**
2. Przy wierszu **"Alsendo"** kliknij żółty przycisk **Uninstall**
3. Odśwież stronę ręcznie (klawisz F5)
4. Żółty przycisk powinien zmienić się na zielony przycisk **Install**
5. Usuń wiersz "Alsendo" z tabeli (jeśli jest taka możliwość)
6. Odśwież stronę ponownie i upewnij się, że wiersz nie pojawia się po odświeżeniu

### Uwaga

Po deinstalacji wtyczki, OpenCart nie powinien mieć żadnych pozostałości po wtyczce, z wyjątkiem danych, które zostały utworzone jako skutek uboczny funkcjonowania wtyczki (np. zlecone wysyłki w bazie danych, które mogą wymagać ręcznego usunięcia).

---

## Konfiguracja wtyczki

### Konfiguracja regionu i kluczy API

Konfiguracja regionu i kluczy API jest **pierwszym i najważniejszym krokiem**, który należy wykonać po zainstalowaniu wtyczki. Bez poprawnej konfiguracji integracji, wtyczka nie będzie mogła komunikować się z zewnętrznymi serwisami.

#### Procedura konfiguracji

1. Przejdź do zakładki **Alsendo** → **Konfiguracja wtyczki** → **Konfiguracja wtyczki**
2. W sekcji **"Konfiguracja regionu i kluczy API"** wybierz region, na którym ma działać wtyczka:
   - **Poland** - integracja z Apaczka
   - **Czech Republic** - integracja z Zaslat
   - **Romania** - integracja z Ecolet

#### Konfiguracja dla regionu Poland (Apaczka)

Po wybraniu regionu **Poland**, pojawią się następujące pola:

- **App ID** - identyfikator aplikacji w systemie Apaczka
- **App Secret** - klucz tajny aplikacji w systemie Apaczka
- **Sandbox** - checkbox umożliwiający przełączenie na środowisko testowe

Wypełnij wszystkie wymagane pola i kliknij przycisk **"Zapisz"**.

#### Konfiguracja dla regionu Czech Republic (Zaslat)

Po wybraniu regionu **Czech Republic**, pojawi się następujące pole:

- **API Key** - klucz API do komunikacji z systemem Zaslat

Wypełnij pole i kliknij przycisk **"Zapisz"**.

#### Konfiguracja dla regionu Romania (Ecolet)

Po wybraniu regionu **Romania**, pojawią się następujące pola:

- **Client ID** - identyfikator klienta OAuth w systemie Ecolet
- **Client Secret** - klucz tajny klienta OAuth w systemie Ecolet

**Ważne informacje dotyczące Ecolet:**

1. Aby uzyskać Client ID i Client Secret, należy zarejestrować aplikację OAuth na stronie: https://panel.ecolet.ro/en/account/oauth/clients
2. W polu **Redirect URI** podczas rejestracji aplikacji należy podać adres URL widoczny w sekcji konfiguracji (wyświetlany jako **"Ecolet Register Link"**)
3. Po zarejestrowaniu aplikacji, kliknij przycisk **"Click to OAuth Authorize"**, aby autoryzować dostęp do API
4. Rozwiązanie tymczasowe/testowe: W przypadku środowiska lokalnego (localhost), użyj `https://google.com` jako Redirect URI podczas rejestracji. Po przekierowaniu do Google, w adresie URL zamień `https://google.com` na link wyświetlany w konfiguracji, zamień `?code` na `&code` i naciśnij Enter

Wypełnij wszystkie wymagane pola i kliknij przycisk **"Zapisz"**.

### Dane nadawcy

Sekcja **"Dane nadawcy"** umożliwia definiowanie szablonów adresów nadawcy, które będą używane podczas zlecania wysyłek.

#### Tworzenie szablonu danych nadawcy

1. W sekcji **"Dane nadawcy"** wybierz opcję **"Nowy szablon"** z listy rozwijanej
2. Wypełnij wszystkie pola
3. Kliknij przycisk **"Zapisz jako nowy szablon"**
4. W oknie modalnym wprowadź nazwę szablonu (dla typu "Firma" nazwa firmy jest automatycznie używana jako nazwa szablonu)
5. Kliknij **"Zapisz"**

#### Ustawienie szablonu jako głównego

1. Wybierz szablon z listy rozwijanej
2. Kliknij przycisk **"Ustaw jako główny"**

**Ważne:** Musi istnieć przynajmniej jeden szablon oznaczony jako główny. Szablon główny jest automatycznie używany podczas tworzenia zlecenia wysyłki. Bez ustawienia głównego szablonu, zlecenie wysyłki nie będzie możliwe.

#### Edycja szablonu

1. Wybierz szablon z listy rozwijanej
2. Wprowadź zmiany w formularzu
3. Kliknij przycisk **"Aktualizuj"**
4. W oknie modalnym potwierdź aktualizację

#### Usuwanie szablonu

Szablon można usunąć poprzez wybranie go z listy i kliknięcie odpowiedniego przycisku (jeśli dostępny). **Uwaga:** Nie można usunąć szablonu, który jest oznaczony jako główny. Najpierw należy ustawić inny szablon jako główny.

### Ustawienia przesyłki

Sekcja **"Ustawienia przesyłki"** umożliwia definiowanie szablonów parametrów przesyłek, które będą używane jako domyślne wartości podczas zlecania wysyłek.

#### Tworzenie szablonu ustawień przesyłki

1. W sekcji **"Ustawienia przesyłki"** wybierz opcję **"Nowy szablon"** z listy rozwijanej
2. Wypełnij następujące pola:
   - **Typ paczki**: wybierz **"Standardowa"** lub **"Niestandardowa"**
   - **Długość** (cm): długość paczki w centymetrach (pole wymagane)
   - **Szerokość** (cm): szerokość paczki w centymetrach (pole wymagane)
   - **Wysokość** (cm): wysokość paczki w centymetrach (pole wymagane)
   - **Waga** (kg): waga paczki w kilogramach (pole wymagane)
   - **Płatność za pobraniem** (opcjonalne): kwota płatności za pobraniem w walucie sklepu
   - **Wartość zadeklarowana** (opcjonalne): wartość zadeklarowana przesyłki w walucie sklepu
   - **Zawartość przesyłki**: wybierz opcję z listy rozwijanej:
     - Dostępne są predefiniowane tagi, które automatycznie generują opis zawartości na podstawie danych zamówienia
     - Opcja **"Własny tekst"** umożliwia wprowadzenie własnego opisu
   - **Własny tekst zawartości** (tylko dla opcji "Własny tekst"): wprowadź własny opis zawartości przesyłki
   - **Typ odbioru**: wybierz typ odbioru przesyłki (dostępne opcje zależą od wybranego regionu)

3. Kliknij przycisk **"Zapisz jako nowy szablon"**
4. W oknie modalnym wprowadź nazwę szablonu
5. Kliknij **"Zapisz"**

#### Typy odbioru

Typy odbioru dostępne w wtyczce zależą od wybranego regionu:

**Dla regionu Poland (Apaczka):**
- **Bez odbioru** (NO_PICKUP): wysyłający samodzielnie zleca wysyłkę w wybrany przez siebie sposób
- **Kurier** (COURIER): kurier odbiera przesyłkę zgodnie z preferowanym wybranym czasem odbioru
- **Odbiór własny** (SELF): wysyłający nadaje paczkę w punkcie nadania

**Dla pozostałych regionów:**
Analogiczne typy odbioru istnieją, jednak ich nazewnictwo może różnić się w zależności od specyfiki danego regionu.

#### Ustawienie szablonu jako głównego

1. Wybierz szablon z listy rozwijanej
2. Kliknij przycisk **"Zapisz szablon jako główny"**

**Ważne:** Musi istnieć przynajmniej jeden szablon oznaczony jako główny. Szablon główny jest automatycznie używany jako domyślne ustawienia przesyłki podczas tworzenia zlecenia wysyłki.

#### Edycja szablonu

1. Wybierz szablon z listy rozwijanej
2. Wprowadź zmiany w formularzu
3. Kliknij przycisk **"Aktualizuj"**
4. W oknie modalnym potwierdź aktualizację

#### Zawartość przesyłki - tagi automatyczne

Wtyczka oferuje możliwość automatycznego generowania opisu zawartości przesyłki na podstawie danych zamówienia. Dostępne są następujące tagi:

- Tagi generujące opis na podstawie produktów w zamówieniu
- Tagi generujące opis na podstawie ID zamówienia

Podczas zlecania wysyłki istnieje możliwość nadpisania automatycznie wygenerowanego opisu i ręcznego podania dowolnej treści dla każdej wysyłki.

### Ustawienia dodatkowe

Sekcja **"Ustawienia dodatkowe"** umożliwia konfigurację domyślnych wartości dla różnych typów odbioru.

#### Domyślne punkty nadania (dla typu odbioru "Odbiór własny")

Dla paczek z typem odbioru **"Odbiór własny"** można wskazać domyślne punkty nadania dla wybranych przewoźników:

- **InPost**: domyślny punkt nadania dla przewoźnika InPost
- **DHL**: domyślny punkt nadania dla przewoźnika DHL
- **Poczta Polska**: domyślny punkt nadania dla Poczty Polskiej
- **DPD**: domyślny punkt nadania dla przewoźnika DPD
- **UPS**: domyślny punkt nadania dla przewoźnika UPS

Aby ustawić domyślny punkt nadania:

1. Kliknij przycisk **"Wybierz punkt"** przy odpowiednim przewoźniku
2. W oknie mapy wybierz punkt nadania
3. Punkt zostanie zapisany jako domyślny dla danego przewoźnika

#### Domyślne godziny odbioru (dla typu odbioru "Kurier")

Dla paczek z typem odbioru **"Kurier"** można wskazać domyślne preferowane godziny odbioru:

- **Godzina odbioru od**: wybierz godzinę początkową zakresu odbioru (dostępne godziny: 08:00 - 17:00)
- **Godzina odbioru do**: wybierz godzinę końcową zakresu odbioru (dostępne godziny: 08:00 - 17:00)

**Wymagania:**
- Godzina "od" musi być wcześniejsza niż godzina "do"
- Różnica między godzinami musi wynosić co najmniej 2 godziny

Po wprowadzeniu zmian kliknij przycisk **"Zapisz ustawienia dodatkowe"**.

### Ustawienia wysyłek

Sekcja **"Ustawienia wysyłek"** umożliwia konfigurację metod dostawy oraz dostępnych usług kurierskich, które będą wyświetlane klientom w koszyku zakupów.

#### Konfiguracja podstawowa

1. Przejdź do zakładki **Alsendo** → **Konfiguracja wtyczki** → **Ustawienia wysyłek**
2. W sekcji **"Ustawienia wysyłek"** wybierz **stawkę podatkową** dla wysyłek z listy rozwijanej
   - Jest to wymóg narzucony przez platformę OpenCart - każda usługa wysyłki musi mieć przypisaną stawkę podatkową
   - Wybrana stawka będzie obowiązywała dla wszystkich metod dostawy

#### Włączanie usług kurierskich

Przed rozpoczęciem konfigurowania metod dostawy należy włączyć dostępne usługi kurierskie:

1. Kliknij przycisk **"Włącz usługi kurierskie"**
2. Pojawi się lista obecnie zsynchronizowanych usług kurierskich z API
3. Jeśli lista jest pusta, kliknij przycisk **"Odśwież listę"**
4. System pobierze aktualną listę usług kurierskich z API Alsendo

**Rozwiązywanie problemów:**

- Jeśli lista w dalszym ciągu jest pusta lub pojawia się błąd:
  1. Sprawdź konfigurację integracji w zakładce **"Konfiguracja wtyczki"**, sekcja **"Konfiguracja regionu i kluczy API"**
  2. Upewnij się, że klucze API są poprawne i aktualne
  3. Sprawdź połączenie internetowe
  4. Może to oznaczać również błąd po stronie zewnętrznego API Alsendo - w takim przypadku skontaktuj się z supportem

#### Konfiguracja usług kurierskich

Dla każdej usługi w sekcji **"Włącz usługi kurierskie"** dostępne są następujące opcje:

- **Checkbox "Aktywna"**: zaznaczenie tego checkboxa sprawia, że:
  - Usługa będzie możliwa do przypisania w ręcznie definiowanych metodach dostawy
  - Usługa będzie zwracana podczas wyceny wysyłki zamówienia, jeśli zamówienie nie ma przypisanej żadnej usługi kurierskiej (metoda dostawy typu "Dowolna usługa")

- **Checkbox "Mapa"** (tylko informacyjny): oznacza, że usługa jest dostawą do punktu, a mapa jest pożądanym widgetem podczas tworzenia wysyłki w koszyku. Klient powinien użyć mapy do wskazania punktu odbioru przesyłki.

**Procedura:**

1. Zaznacz checkboxy **"Aktywna"** przy usługach kurierskich, które chcesz udostępnić klientom
2. Na dole widoku, w prawym dolnym rogu kliknij przycisk **"Zapisz i zamknij"**
3. Zapisane usługi będą dostępne do przypisania w metodach dostawy

#### Tworzenie metod dostawy

Metoda dostawy to sposób, w jaki klient wybiera formę dostawy w koszyku zakupów. Każda metoda dostawy może być powiązana z konkretną usługą kurierską lub umożliwiać wybór usługi przez klienta.

**Procedura tworzenia metody dostawy:**

1. Kliknij przycisk **"Dodaj metodę dostawy"** (lub podobny)
2. Wypełnij następujące pola:
   - **Nazwa metody dostawy**: nazwa, która będzie wyświetlana klientom w koszyku podczas wyboru formy dostawy (np. "Kurier DPD", "Paczkomat InPost")
   - **Usługa kurierska**: wybierz usługę kurierską powiązaną z tworzoną metodą dostawy z listy rozwijanej
     - **"Dowolna usługa"**: wybierz tę opcję, aby nie przypisywać do metody żadnej konkretnej usługi. W takim przypadku jako administrator będziesz mógł samodzielnie wybrać usługę kurierską na etapie zlecania wysyłki
   - **Cena dostawy**: wprowadź statyczną cenę dostawy dla danej metody (cena jest niezmienna i nie zależy od wagi czy wymiarów przesyłki)
   - **Mapa** (tylko dla "Dowolna usługa"): jeśli wybrano "Dowolna usługa" jako usługę metody dostawy, checkbox "Mapa" staje się aktywny. Można samodzielnie zdecydować, czy po wybraniu tej metody dostawy w koszyku będzie wyświetlana mapa z wyborem punktów dla użytkownika

3. Kliknij przycisk **"Zapisz"** lub **"Zapisz metody dostawy"**

**Uwaga:** Metoda dostawy bez przypisanej usługi kurierskiej (opcja "Dowolna usługa") będzie zwracać wszystkie aktywne usługi kurierskie podczas wyceny, umożliwiając administratorowi wybór preferowanej usługi.

#### Mapowanie płatności

**Mapowanie płatności** to funkcja, która określa, jakie metody płatności mają być dostępne dla poszczególnych metod dostawy.

**Dlaczego to ważne:**

- Jeśli dla danej metody dostawy nie zostanie zaznaczona żadna metoda płatności, metoda dostawy **nie będzie widoczna w koszyku** klienta
- Mapowanie płatności pozwala na elastyczne zarządzanie dostępnością metod dostawy w zależności od wybranej metody płatności

**Procedura mapowania płatności:**

1. W sekcji **"Ustawienia wysyłek"** kliknij przycisk **"Mapowanie płatności"**
2. W oknie modalnym zobaczysz tabelę z metodami dostawy w wierszach i metodami płatności w kolumnach
3. Zaznacz checkboxy przy metodach płatności, które mają być dostępne dla każdej metody dostawy
4. Kliknij przycisk **"OK"** lub **"Zapisz"**, aby zapisać mapowanie

**Uwaga:** Dostępne metody płatności pochodzą z konfiguracji OpenCart. Aby skonfigurować dodatkowe metody płatności, zapoznaj się z dokumentacją platformy OpenCart.

### Konfiguracja mapowania

Sekcja **"Konfiguracja mapowania"** umożliwia konfigurację automatycznego zlecania wysyłek oraz synchronizacji statusów zamówień.

#### Automatyczne zlecanie wysyłek

Wtyczka umożliwia automatyczne zlecanie wysyłki, gdy zamówienie osiągnie określony status.

**Procedura konfiguracji:**

1. Przejdź do zakładki **Alsendo** → **Konfiguracja wtyczki** → **Konfiguracja mapowania**
2. W sekcji **"Status wyzwalający zlecenie wysyłki"** wybierz status zamówienia OpenCart z listy rozwijanej
3. Kliknij przycisk **"Zapisz"**

**Jak to działa:**

- Gdy zamówienie osiągnie wybrany status, wtyczka automatycznie podejmie próbę zlecenia wysyłki
- Jeśli operacja nie powiedzie się z powodu np. brakujących danych odbiorcy, nieprawidłowych danych, błędu API lub innego powodu, informacja o błędzie pojawi się w zakładce **"Dev logs"**
- Automatyczne zlecanie wysyłek działa w tle i nie wymaga interwencji administratora

**Rozwiązywanie problemów:**

- Jeśli automatyczne zlecenie wysyłki nie działa, sprawdź zakładkę **"Dev logs"** pod kątem komunikatów błędów
- Upewnij się, że:
  - Zamówienie ma wszystkie wymagane dane (adres nadawcy, adres odbiorcy, dane przesyłki)
  - Konfiguracja API jest poprawna
  - Zamówienie nie zostało już zlecone

#### Automatyczne mapowanie statusów wysyłki

Wtyczka umożliwia automatyczną zmianę statusów zamówień OpenCart na podstawie aktualnego statusu wysyłki w systemie Apaczka/Zaslat/Ecolet.

**Procedura konfiguracji:**

1. W sekcji **"Mapowanie statusów wysyłki"** zobaczysz listę dostępnych statusów wysyłki dla wybranego regionu
2. Dla każdego statusu wysyłki wybierz odpowiadający mu status zamówienia OpenCart z listy rozwijanej
3. Kliknij przycisk **"Zapisz"**

**Jak to działa:**

- Status zamówienia zostanie zsynchronizowany wyłącznie w momencie konkretnego pobrania zamówienia z API
- Przykładowo: gdy wysyłka zostanie anulowana w systemie Apaczka/Zaslat/Ecolet, status zamówienia w OpenCart zostanie automatycznie zaktualizowany po pobraniu informacji o anulowaniu z API
- **Uwaga:** Funkcja ta nie działa w pełni efektywnie z powodu braku automatycznego synchronizowania zamówień Alsendo z zamówieniami OpenCart w czasie rzeczywistym. Status zostanie zsynchronizowany tylko w momencie, gdy system pobierze informacje o zamówieniu z API (np. podczas anulowania, pobierania listu przewozowego, itp.)

---

## Widok zamówienia

Wtyczka rozszerza domyślny widok szczegółów zamówienia w panelu administracyjnym OpenCart, dodając sekcję związaną ze zlecaniem i zarządzaniem wysyłkami.

### Dostęp do widoku zamówienia

1. Przejdź do zakładki **Sales** → **Orders**
2. Znajdź zamówienie, dla którego chcesz zlecić wysyłkę
3. Kliknij niebieski przycisk z symbolem oka (ikona "View") przy wybranym zamówieniu

### Sekcja wysyłki Alsendo

Na dole strony szczegółów zamówienia, wtyczka dodaje dodatkową sekcję związaną ze szczegółami zlecanej/zleconej wysyłki.

#### Dla zamówień oczekujących na zlecenie wysyłki

Jeśli zamówienie nie zostało jeszcze zlecone, w sekcji wysyłki zobaczysz:

- **Podsumowanie danych nadawcy**: krótkie podsumowanie danych nadawcy z głównego szablonu
- **Podsumowanie adresu dostawy**: krótkie podsumowanie adresu dostawy klienta
- **Podsumowanie paczki**: krótkie podsumowanie parametrów przesyłki z głównego szablonu
- **Przycisk "Pobierz wycenę"**: umożliwia pobranie wyceny wysyłki z API
- **Przycisk "Przejdź do pełnego formularza"**: umożliwia przejście do pełnego formularza zlecania wysyłki

**Procedura zlecania wysyłki z widoku zamówienia:**

1. Kliknij przycisk **"Pobierz wycenę"**
2. System pobierze dostępne usługi kurierskie i wycenę z API
3. Wybierz przewoźnika z listy dostępnych opcji
4. Jeśli wybrano typ odbioru **"Kurier"**, wybierz preferowaną datę odbioru oraz preferowany zakres godzin odbioru
5. Jeśli wybrano typ odbioru **"Odbiór własny"**, wybierz punkt nadania paczki (jeśli wymagane)
6. Kliknij przycisk **"Zamów przesyłkę"**
7. System zleci wysyłkę w systemie Apaczka/Zaslat/Ecolet
8. Po pomyślnym zleceniu, sekcja wysyłki zostanie zaktualizowana

#### Dla zamówień z zleconą wysyłką

Jeśli zamówienie zostało już zlecone, w sekcji wysyłki zobaczysz:

- **Status wysyłki**: aktualny status wysyłki w systemie Apaczka/Zaslat/Ecolet
- **Numer zlecenia**: numer zlecenia wysyłki
- **Szczegóły przesyłki**: szczegółowe informacje o zleconej przesyłce
- **Przycisk "Anuluj zlecenie wysyłki"**: umożliwia anulowanie zleconej wysyłki
- **Przycisk "Pobierz listy przewozowe"**: umożliwia pobranie listów przewozowych dla zleconej wysyłki

**Uwaga:** Dla zleconych wysyłek nie ma możliwości przejścia do pełnego formularza zlecania wysyłki ("Order Full Form"). Aby zmodyfikować dane wysyłki, należy najpierw anulować zlecenie.

### Pełny formularz zlecania wysyłki (Order Full Form)

Wtyczka dodaje widok pełnego formularza zlecania wysyłki, który umożliwia szczegółową konfigurację wszystkich parametrów przesyłki przed zleceniem.

**Dostęp do pełnego formularza:**

1. W widoku szczegółów zamówienia (dla zamówień oczekujących na zlecenie wysyłki)
2. Kliknij przycisk **"Przejdź do pełnego formularza"**

**Uwaga:** Przycisk "Przejdź do pełnego formularza" jest widoczny tylko dla zamówień oczekujących na zlecenie wysyłki.

---

## Pełny formularz zlecenia wysyłki

Pełny formularz zlecania wysyłki (Order Full Form) umożliwia szczegółową konfigurację wszystkich parametrów przesyłki przed zleceniem. Formularz jest podzielony na kilka sekcji.

### Dane nadawcy

W sekcji **"Dane nadawcy"** wyświetlane są dane automatycznie podstawione z głównego szablonu danych nadawcy z konfiguracji wtyczki.

**Możliwości:**

- Wszystkie pola są edytowalne i można je modyfikować przed zleceniem wysyłki
- Zmiany wprowadzone w formularzu dotyczą tylko bieżącego zlecenia wysyłki i nie wpływają na szablon w konfiguracji

### Adres dostawy

W sekcji **"Adres dostawy"** wyświetlane są dane klienta podstawione na bazie danych wskazanych przez klienta podczas składania zamówienia.

**Możliwości:**

- Wszystkie pola są edytowalne i można je modyfikować przed zleceniem wysyłki
- W przypadku wysyłek do punktu odbioru (typy usług z mapą), pole **"Punkt dostawy"** zostanie odblokowane i możliwe będzie ręczne wskazanie punktu dostawy za pomocą mapy

### Paczka

W sekcji **"Paczka"** wyświetlane są dane podstawione na bazie głównego szablonu ustawień przesyłek z konfiguracji wtyczki.

**Możliwości:**

- Z tego poziomu jest możliwość wybrania innego szablonu ustawień przesyłki z listy rozwijanej
- Możliwa jest swobodna modyfikacja wszystkich parametrów przesyłki przed zleceniem
- Przycisk **"Dodaj kolejną przesyłkę"** umożliwia podzielenie zamówienia na wiele paczek (funkcja multi-package)

**Funkcja multi-package:**

- Kliknij przycisk **"Dodaj kolejną przesyłkę"**, aby dodać kolejną paczkę do zamówienia
- Każda paczka może mieć indywidualne parametry (wymiary, waga, zawartość, itp.)
- Wszystkie paczki będą zlecane jako część jednego zlecenia wysyłki

### Zlecanie wysyłki

Zlecanie wysyłki z pełnego formularza przebiega analogicznie jak z poziomu szczegółów zamówienia.

**Procedura:**

1. Sprawdź i ewentualnie zmodyfikuj wszystkie dane w formularzu (dane nadawcy, adres dostawy, parametry paczki)
2. Kliknij przycisk **"Pobierz wycenę"**
3. System pobierze dostępne usługi kurierskie i wycenę z API
4. Wybierz przewoźnika z listy dostępnych opcji
5. W zależności od typu odbioru:
   - **Dla typu "Kurier"**: wybierz preferowaną datę odbioru oraz preferowany zakres godzin odbioru
   - **Dla typu "Odbiór własny"**: wybierz punkt nadania paczki za pomocą mapy (jeśli wymagane)
6. Kliknij przycisk **"Zamów przesyłkę"**
7. System zleci wysyłkę w systemie Apaczka/Zaslat/Ecolet
8. Po pomyślnym zleceniu, zostaniesz przekierowany do widoku szczegółów zamówienia z zaktualizowaną sekcją wysyłki

**Walidacja danych:**

- Przed zleceniem wysyłki, system przeprowadza walidację wszystkich wymaganych pól
- Jeśli któreś pole jest nieprawidłowe lub brakuje wymaganych danych, system wyświetli odpowiedni komunikat błędu
- Wszystkie błędy walidacji są wyświetlane w formularzu przy odpowiednich polach

---

## Masowe zlecanie wysyłek

Wtyczka umożliwia zlecanie wysyłek dla wielu zamówień jednocześnie, co znacznie przyspiesza proces obsługi zamówień.

### Dostęp do widoku masowych operacji

1. Przejdź do zakładki **Sales** → **Orders**
2. Zaznacz checkboxy przy zamówieniach, dla których chcesz wykonać masowe operacje
3. W prawym górnym rogu kliknij ikonkę **"Nadaj z Alsendo"** (lub przycisk z podobną nazwą)
4. Zostaniesz przeniesiony do widoku akcji masowych

### Dostępne operacje masowe

W widoku masowych operacji dostępne są następujące funkcje:

#### Masowe zlecanie wysyłek

1. W widoku masowych operacji zobaczysz tabelę z wybranymi zamówieniami
2. Kliknij przycisk **"Masowa wysyłka"** (lub podobny)
3. System automatycznie zleci wysyłki dla wszystkich wybranych zamówień
4. W kolumnie **"Status zlecenia"** zobaczysz status operacji dla każdego zamówienia:
   - **Sukces**: wysyłka została pomyślnie zlecona
   - **Błąd**: wystąpił błąd podczas zlecania wysyłki (szczegóły błędu są wyświetlane w kolumnie)

#### Masowe anulowanie wysyłek

1. W widoku masowych operacji zaznacz zamówienia z zleconymi wysyłkami
2. Kliknij przycisk **"Masowe anulowanie"** (lub podobny)
3. System automatycznie anuluje wysyłki dla wszystkich wybranych zamówień
4. W kolumnie **"Status zlecenia"** zobaczysz status operacji dla każdego zamówienia

#### Masowe pobieranie listów przewozowych

1. W widoku masowych operacji zaznacz zamówienia z zleconymi wysyłkami
2. Kliknij przycisk **"Pobierz listy przewozowe"** (lub podobny)
3. System pobierze listy przewozowe dla wszystkich wybranych zamówień i przygotuje je do pobrania jako plik ZIP
4. Po zakończeniu operacji, zostanie wyświetlony link do pobrania pliku ZIP z listami przewozowymi

### Obsługa błędów

W przypadku błędu wysyłki dla któregoś z zamówień:

1. W kolumnie **"Status zlecenia"** zobaczysz komunikat błędu z opisem problemu
2. W kolumnie **"Akcje"** kliknij przycisk z ikoną dokumentu, aby przejść do pełnego formularza zlecania wysyłki
3. W pełnym formularzu popraw błędy walidacji (np. uzupełnij brakujące dane, popraw nieprawidłowe wartości)
4. Wróć do widoku masowych operacji (możesz użyć przycisku "Wstecz" w przeglądarce)
5. Spróbuj ponownie zlecić wysyłkę dla poprawionego zamówienia

**Typowe błędy:**

- Brakujące dane nadawcy (np. nie ustawiono głównego szablonu danych nadawcy)
- Brakujące dane odbiorcy (np. nieprawidłowy adres dostawy)
- Nieprawidłowe parametry paczki (np. waga lub wymiary poza dozwolonym zakresem)
- Błąd komunikacji z API (np. nieprawidłowe klucze API, problemy z siecią)
- Błąd walidacji danych (np. nieprawidłowy format numeru telefonu, nieprawidłowy kod pocztowy)

### Informacje wyświetlane w tabeli

W tabeli masowych operacji wyświetlane są następujące informacje dla każdego zamówienia:

- **Numer zamówienia**: numer zamówienia OpenCart
- **Klient**: imię i nazwisko klienta
- **Status zamówienia**: aktualny status zamówienia w OpenCart
- **Status zlecenia**: status operacji zlecania/anulowania wysyłki
- **Akcje**: przyciski do przejścia do pełnego formularza lub szczegółów zamówienia

---

## Wymagania systemowe

### Języki

Wtyczka jest dostępna w 4 wersjach językowych:

- **Polski (pl-pl)**
- **Angielski (en-gb)**
- **Czeski (cs-cz)**
- **Rumuński (ro-ro)**

**Instalacja pakietów językowych:**

1. Wtyczka "podpina" swoje tłumaczenia pod istniejące tłumaczenia OpenCart
2. Aby wtyczka była dostępna w danym języku, należy zainstalować odpowiednią paczkę językową dla tego języka w OpenCart lub ręcznie stworzyć język w konfiguracji OpenCart.
3. W przypadku braku zainstalowanej paczki językowej, wtyczka będzie wyświetlana w języku angielskim (domyślnym)

### Wymaganie podania numeru telefonu przez klienta

Większość przewoźników wymaga podania numeru telefonu odbiorcy podczas zlecania wysyłki. Aby wymusić na klientach podanie numeru telefonu podczas rejestracji konta:

1. Przejdź do zakładki **System** → **Settings**
2. Wybierz zakładkę **Option**
3. Z listy wybierz **"Account"**
4. Upewnij się, że checkbox **"Telephone Required"** jest zaznaczony
5. Kliknij przycisk **"Save"**

**Dlaczego to ważne:**

- Brak numeru telefonu przy zamówieniu może uniemożliwić zlecenie wysyłki
- Większość przewoźników wymaga numeru telefonu
- Wymuszenie podania numeru telefonu podczas rejestracji zapewnia, że wszystkie zamówienia będą miały ten wymagany element

### Dev logs

Wtyczka oferuje funkcję logowania operacji i błędów, która jest dostępna w zakładce **"Dev logs"**.

**Dostęp do logów:**

1. Przejdź do zakładki **Alsendo** → **Dev logs**
2. Zobaczysz listę wszystkich logów z operacji wtyczki

**Informacje w logach:**

- **Data i godzina**: data i godzina wykonania operacji
- **Typ**: typ operacji (np. zlecenie wysyłki, anulowanie, błąd API)
- **Wiadomość**: szczegółowy opis operacji lub błędu
- **Dane zamówienia**: numer zamówienia i inne powiązane informacje

**Korzystanie z logów:**

- Logi są przydatne do diagnozowania problemów z integracją
- W przypadku błędów automatycznego zlecania wysyłek, szczegóły błędu są zapisywane w logach
- Logi mogą być używane do śledzenia historii operacji wtyczki

---

## Często zadawane pytania (FAQ)

### Instalacja i konfiguracja

**P: Dlaczego nie widzę zakładki "Alsendo" w menu po instalacji?**

O: Upewnij się, że:
1. Wtyczka została poprawnie zainstalowana w zakładce **Extensions** → **Installer**
2. Moduł został aktywowany w zakładce **Extensions** → **Extensions** (typ: Modules)
3. Masz odpowiednie uprawnienia do dostępu do wtyczki (sprawdź w **System** → **Users** → **User Groups**)

**P: Jak sprawdzić, czy wtyczka jest poprawnie zainstalowana?**

O: Po poprawnym zainstalowaniu:
- W lewym menu powinna pojawić się zakładka **"Alsendo"**
- W zakładce "Alsendo" powinny być dostępne opcje: Konfiguracja wtyczki, Ustawienia wysyłek, Konfiguracja mapowania, Dev logs

**P: Co zrobić, jeśli lista usług kurierskich jest pusta po kliknięciu "Odśwież listę"?**

O: Sprawdź:
1. Czy konfiguracja API jest poprawna (zakładka **Konfiguracja wtyczki** → **Konfiguracja regionu i kluczy API**)
2. Czy klucze API są aktualne i prawidłowe
3. Czy masz połączenie internetowe
4. Czy nie ma problemów po stronie API Alsendo (sprawdź logi w zakładce **Dev logs**)

### Konfiguracja metod dostawy

**P: Dlaczego w koszyku nie widzę żadnych metod dostawy?**

O: Sprawdź:
1. Czy utworzono przynajmniej jedną metodę dostawy w zakładce **Ustawienia wysyłek**
2. Czy dla metody dostawy zostało zmapowane przynajmniej jedno mapowanie płatności (zakładka **Ustawienia wysyłek** → przycisk **"Mapowanie płatności"**)
3. Czy metoda dostawy ma przypisaną aktywną usługę kurierską lub opcję "Dowolna usługa"
4. Czy stawka podatkowa została wybrana w sekcji **Ustawienia wysyłek**

**P: Co oznacza opcja "Dowolna usługa" w metodzie dostawy?**

O: Opcja "Dowolna usługa" oznacza, że metoda dostawy nie jest powiązana z konkretną usługą kurierską. W takim przypadku:
- Podczas wyceny zamówienia, administrator zobaczy wszystkie aktywne usługi kurierskie
- Administrator będzie mógł wybrać preferowaną usługę kurierską
- Jeśli usługa wymaga mapy (checkbox "Mapa" zaznaczony), klient zobaczy mapę do wyboru punktu odbioru

**P: Jak skonfigurować mapowanie płatności?**

O:
1. Przejdź do zakładki **Ustawienia wysyłek**
2. Kliknij przycisk **"Mapowanie płatności"**
3. W oknie modalnym zaznacz checkboxy przy metodach płatności, które mają być dostępne dla każdej metody dostawy
4. Kliknij **"OK"** lub **"Zapisz"**

**Uwaga:** Jeśli dla metody dostawy nie zostanie zaznaczona żadna metoda płatności, metoda dostawy nie będzie widoczna w koszyku.

### Zlecanie wysyłek

**P: Dlaczego nie mogę zlecić wysyłki dla zamówienia?**

O: Sprawdź:
1. Czy ustawiono główny szablon danych nadawcy (zakładka **Konfiguracja wtyczki** → **Dane nadawcy**)
2. Czy ustawiono główny szablon ustawień przesyłki (zakładka **Konfiguracja wtyczki** → **Ustawienia przesyłki**)
3. Czy zamówienie ma wszystkie wymagane dane (adres nadawcy, adres odbiorcy, parametry paczki)
4. Czy konfiguracja API jest poprawna
5. Sprawdź logi w zakładce **Dev logs** pod kątem komunikatów błędów

**P: Co zrobić, jeśli automatyczne zlecenie wysyłki nie działa?**

O:
1. Sprawdź zakładkę **Dev logs** pod kątem komunikatów błędów
2. Upewnij się, że status wyzwalający zlecenie wysyłki jest poprawnie skonfigurowany (zakładka **Konfiguracja mapowania**)
3. Sprawdź, czy zamówienie ma wszystkie wymagane dane
4. Sprawdź, czy konfiguracja API jest poprawna

**P: Jak anulować zleconą wysyłkę?**

O:
1. Przejdź do widoku szczegółów zamówienia
2. W sekcji wysyłki Alsendo kliknij przycisk **"Anuluj zlecenie wysyłki"**
3. Potwierdź anulowanie
4. Po pomyślnym anulowaniu, sekcja wysyłki zostanie zaktualizowana

**P: Jak pobrać listy przewozowe?**

O:
1. Przejdź do widoku szczegółów zamówienia z zleconą wysyłką
2. W sekcji wysyłki Alsendo kliknij przycisk **"Pobierz listy przewozowe"**
3. Listy przewozowe zostaną pobrane i przygotowane do pobrania

Dla wielu zamówień:
1. Przejdź do widoku masowych operacji
2. Zaznacz zamówienia z zleconymi wysyłkami
3. Kliknij przycisk **"Pobierz listy przewozowe"**
4. Po zakończeniu operacji, zostanie wyświetlony link do pobrania pliku ZIP z listami przewozowymi

### Szablony i ustawienia

**P: Czy mogę mieć wiele szablonów danych nadawcy?**

O: Tak, możesz utworzyć wiele szablonów danych nadawcy. Jednak tylko jeden szablon może być oznaczony jako główny. Szablon główny jest automatycznie używany podczas zlecania wysyłki.

**P: Czy mogę modyfikować dane w szablonach podczas zlecania wysyłki?**

O: Tak, w pełnym formularzu zlecania wysyłki wszystkie dane są edytowalne. Zmiany wprowadzone w formularzu dotyczą tylko bieżącego zlecenia wysyłki i nie wpływają na szablon w konfiguracji.

**P: Jak działa automatyczne generowanie zawartości przesyłki?**

O: Wtyczka oferuje możliwość automatycznego generowania opisu zawartości przesyłki na podstawie danych zamówienia. Dostępne są predefiniowane tagi, które automatycznie generują opis na podstawie produktów, id zamówienia. Możesz również wybrać opcję "Własny tekst" i wprowadzić własny opis.

### Inne pytania

**P: Czy wtyczka obsługuje wiele paczek dla jednego zamówienia?**

O: Tak, w pełnym formularzu zlecania wysyłki możesz kliknąć przycisk **"Dodaj kolejną przesyłkę"**, aby dodać kolejną paczkę do zamówienia. Każda paczka może mieć indywidualne parametry (wymiary, waga, zawartość, itp.).

**P: Jak działa synchronizacja statusów zamówień?**

O: Status zamówienia zostanie zsynchronizowany wyłącznie w momencie konkretnego pobrania zamówienia z API (np. podczas anulowania, pobierania listu przewozowego, itp.). Status nie jest synchronizowany w czasie rzeczywistym - wymaga to ręcznego pobrania informacji o zamówieniu z API.

**P: Czy mogę używać wtyczki w środowisku testowym (sandbox)?**

O: Tak, dla regionu Poland (Apaczka) dostępna jest opcja **"Sandbox"** w konfiguracji API. Zaznacz checkbox "Sandbox", aby przełączyć się na środowisko testowe. Dla pozostałych regionów, sprawdź dokumentację API odpowiedniego serwisu.
