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 (obecnie w wersji 4.2.5) 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.
Funkcje 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.
Mapa w starym API osadzana jest przez lokalny plik map.html, który – dzięki użyciu Uri::root() zamiast sztywnej ścieżki – działa poprawnie także w instalacjach Joomla umieszczonych w podkatalogu domeny.
| Cecha | Stare API | Nowe API v5 |
|---|---|---|
| Wymagany token | Nie | Tak |
| Działanie na localhost | Tak | Tak – ustaw wersję 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ą. W szczegółach 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 lub oferta nie jest jeszcze gotowa – kliknij „Opłać przesyłkę”, gdy będzie gotowe,
- po opłaceniu pojawi się przycisk „Pobierz etykietę”.
Zabezpieczenie przed duplikatami: raz utworzona przesyłka zapisywana jest przy zamówieniu (inpost_shipment_id), a wtyczka nie utworzy dla niego kolejnej – ponowne kliknięcie „Utwórz przesyłkę” nie generuje duplikatów w Menedżerze Paczek InPost. Jedynym miejscem świadomego anulowania i wygenerowania nowej przesyłki jest przycisk „Utwórz ponownie”.
Warto pamiętać, że InPost przygotowuje oferty przewozowe asynchronicznie – tuż po utworzeniu przesyłki oferta może być jeszcze niedostępna. Wtyczka odpytuje ShipX o ofertę kilkukrotnie, a jeśli nadal jej nie ma, zostawia przesyłkę nienaruszoną i pozwala dokończyć płatność przyciskiem „Opłać przesyłkę” po chwili – bez ryzyka, że dane przesyłki zostaną skasowane.
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 paczkomatu,inpost_shipment_id– identyfikator przesyłki ShipX.
Automatyczne aktualizacje w Joomla
Wtyczka ma wbudowany serwer aktualizacji Joomla, więc po pierwszej instalacji nie musisz już ręcznie pobierać kolejnych wersji z GitHuba. Nowe wydania (poprawki błędów i nowe funkcje) pojawiają się w standardowym mechanizmie Joomla:
- przejdź do Rozszerzenia → Zarządzaj → Aktualizacja,
- kliknij Znajdź aktualizacje – Joomla sprawdzi dostępność nowej wersji wtyczki,
- zaznacz wtyczkę InPost i kliknij Aktualizuj.
To ten sam sprawdzony mechanizm dystrybucji, którego używam w pozostałych swoich wtyczkach do HikaShop (PayU, Fakturownia) – dzięki niemu aktualizacje docierają do Ciebie bezpiecznie i bez ręcznej pracy.
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, changelog kolejnych wersji oraz możliwość zgłaszania błędów i sugestii pod adresem github.com/pablop76/plg_inpost_hikashop.
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, HikaShopem lub integracjami kurierskimi, ten projekt może okazać się dla Ciebie wartościowym źródłem wiedzy oraz oszczędzić wiele godzin pracy.
Pobierz wtyczkę InPost Paczkomaty dla HikaShop
Najnowszy pakiet instalacyjny (ZIP) znajdziesz w GitHub Releases. Zainstalujesz go w Joomla przez Rozszerzenia → Zarządzaj → Instaluj → Prześlij plik pakietu, a kolejne wersje pobiorą się już automatycznie.
Pobierz najnowszą wersję