Pracując od lat z systemem Joomla oraz komponentem HikaShop, wielokrotnie spotykałem się z potrzebą solidnej i technicznie poprawnej integracji wysyłek InPost Paczkomaty.
Gotowe rozwiązania dostępne na rynku często były ograniczone, nieaktualne lub trudne w rozbudowie. Z tego powodu zdecydowałem się stworzyć własną wtyczkę wysyłkową, którą udostępniam publicznie jako projekt open-source.
Ważna informacja:
Udostępniana wtyczka nie jest produktem komercyjnym. Nie została przetestowana we wszystkich możliwych konfiguracjach i scenariuszach sklepowych. Może zawierać błędy i niedoskonałości. Korzystasz z niej na własną odpowiedzialność.
Dlaczego powstała ta wtyczka?
Integracja systemów kurierskich z HikaShopem bywa problematyczna, szczególnie w przypadku nowszych wersji Joomla (4, 5, 6). W wielu projektach brakowało mi rozwiązania, które nie tylko umożliwia wybór paczkomatu po stronie klienta, ale również pozwala na wygodne zarządzanie przesyłkami bezpośrednio z poziomu panelu administracyjnego.
Celem było stworzenie wtyczki, która będzie możliwie jak najbardziej „czysta” architektonicznie, zgodna z aktualnymi standardami PHP oraz API InPost, a jednocześnie czytelna dla innych developerów chcących ją rozbudować lub dostosować do własnych potrzeb.
Czym jest InPost Paczkomaty – HikaShop Shipping Plugin?
Wtyczka InPost Paczkomaty – HikaShop Shipping Plugin jest rozszerzeniem wysyłkowym dla HikaShop, przeznaczonym do pracy z Joomla w wersjach 4, 5 oraz 6. Umożliwia ona pełną integrację z usługą InPost Paczkomaty – zarówno na etapie składania zamówienia przez klienta, jak i późniejszej obsługi logistycznej zamówienia w panelu administracyjnym.
Rozwiązanie obsługuje zarówno wybór paczkomatu na interaktywnej mapie, jak i komunikację z oficjalnym API ShipX, pozwalając na tworzenie, opłacanie oraz pobieranie etykiet przesyłek bez opuszczania Joomla.
Funkcjonalności dostępne po stronie klienta (Frontend)
Najważniejszym elementem integracji z punktu widzenia użytkownika sklepu jest intuicyjny wybór punktu odbioru. Wtyczka wykorzystuje oficjalny GeoWidget InPost, który wyświetlany jest w formie modala podczas składania zamówienia.
- możliwość wyboru paczkomatu lub punktu POP na mapie
- obsługa starej wersji API mapy (działającej na localhost)
- obsługa nowego API v5 wymagającego tokena i domeny
- walidacja zamówienia – brak wyboru punktu blokuje finalizację
- zapis wybranego paczkomatu bezpośrednio w zamówieniu
Dzięki walidacji klient nie jest w stanie złożyć zamówienia bez wcześniejszego wskazania punktu odbioru, co eliminuje częsty problem niekompletnych danych wysyłkowych.
Obsługa mapy i różnice między wersjami API
Wtyczka umożliwia wybór pomiędzy dwiema wersjami API mapy InPost. Starsza wersja mapy działa bez tokena i bez konieczności zakładania konta InPost, co pozwala na szybkie uruchomienie integracji. Nowa wersja API v5 wymaga posiadania konta InPost, zarejestrowanej domeny oraz tokena i stanowi obecnie oficjalnie wspierane rozwiązanie.
| Cecha | Stare API | Nowe API v5 |
|---|---|---|
| Wymagany token | Nie | Tak |
| Działanie na localhost | Tak | Tak - ustaw wersje Sandbox |
| Konfiguracja punktów | Checkboxy | parcelCollect, parcelCollectPayment, parcelCollect247 |
Funkcje administracyjne i integracja z ShipX API
Drugim, kluczowym filarem wtyczki jest integracja z ShipX API, która pozwala na pełną obsługę przesyłek bezpośrednio z poziomu zaplecza Joomla. Po wejściu w szczegóły zamówienia administrator ma dostęp do dedykowanej sekcji InPost.
Z tego poziomu możliwe jest utworzenie przesyłki, automatyczne pobranie danych odbiorcy z zamówienia, oraz wygenerowanie etykiety w formacie PDF.
Logika tworzenia i opłacania przesyłek
Mechanizm opłacania przesyłek został powiązany ze statusem zamówienia w HikaShop. Pozwala to zachować spójność pomiędzy procesem sprzedaży a logistyką.
Przejdź do szczegółów zamówienia w HikaShop
- Jeśli zamówienie ma wysyłkę InPost, zobaczysz sekcję "InPost ShipX (Admin)"
- Kliknij "Utwórz przesyłkę InPost"
- Jeśli zamówienie ma status "confirmed" - przesyłka zostanie automatycznie opłacona
- Jeśli zamówienie nie jest potwierdzone - kliknij "Opłać przesyłkę" gdy będzie gotowe
- Po opłaceniu pojawi się przycisk "Pobierz etykietę"
Tryb debugowania i logowanie zdarzeń
Na potrzeby testów oraz diagnostyki problemów wtyczka została wyposażona w tryb debugowania. Po jego aktywacji wszystkie kluczowe operacje zapisywane są do pliku logów.
/logs/inpost_hika_debug.log
Logowane są m.in. wybory paczkomatu, zapisy danych do bazy, zmiany statusów zamówień oraz komunikacja z API ShipX.
Zmiany w strukturze bazy danych
Wtyczka automatycznie rozszerza tabelę zamówień HikaShop o dodatkowe kolumny, w których przechowywane są informacje specyficzne dla integracji InPost.
inpost_locker– nazwa i identyfikator paczkomatuinpost_shipment_id– identyfikator przesyłki ShipX
Repozytorium GitHub i dostęp do kodu
Cały projekt jest dostępny publicznie w serwisie GitHub. Znajdziesz tam kod źródłowy wtyczki, instrukcję instalacji oraz możliwość zgłaszania błędów i sugestii.
Przejdź do repozytorium GitHub
Podsumowanie
Udostępniana wtyczka jest efektem praktycznej pracy nad realnymi projektami opartymi o Joomla i HikaShop. Choć nie jest to rozwiązanie komercyjne, może stanowić solidną bazę do dalszego rozwoju, nauki integracji z API InPost lub stworzenia własnej, dopasowanej implementacji.
Jeśli pracujesz z Joomla, Hikashop lub integracjami kurierskimi, ten projekt może okazać się dla Ciebie wartościowym źródłem wiedzy oraz oszczędzić wiele godzin pracy.