GLS PickUP Hungary
Szállítási Modul

GLS csomagpont és csomagautomata választó szállítási modul OpenCart 3.0.5 webshopokhoz, Journal 3.28 és alap OC3 pénztárral egyaránt. Telepítés után azonnal működik – nincs szükség checkout módosításra.

✅

Önellátó modul – fájlok felmásolása és admin aktiválás után azonnal elérhető a pénztárban. Nem módosít checkout controllert, nem igényel footer injektálást.

✨ Funkciók

📦

Csomagpont & automata

GLS parcel shop és parcel locker helyek, szűrhető típusonként. Adatbázis az admin felületről egy gombbal frissíthető a GLS API-ról.

🗺️

Városonként csoportosítva

A dropdown lista városonként, azon belül irányítószám és név szerint rendezett. Budapesten kerületenként van csoportosítva.

🔄

Automatikus JS betöltés

A JavaScript automatikusan töltődik be, amikor a GLS szállítási mód elérhető. Semmilyen checkout fájl módosítása nem szükséges.

📋

Cím frissítés rendelés után

A rendelés leadása után, de az email kiküldése előtt az adatbázisban a szállítási cím automatikusan a kiválasztott csomagpont adataira cserélődik.

⚖️

Súly & méretkorlát

Beállítható maximum súly (kg) és oldalhossz (cm). Ha a kosár meghaladja a limitet, a GLS opció automatikusan eltűnik a szállítási módok közül.

🆓

Ingyenes szállítási küszöb

Egy összeghatár felett a szállítás automatikusan ingyenes lesz – nincs szükség külön kuponra.

🛒

Journal 3 & alap OC3

Egyaránt működik a Journal 3.28 QuickCheckout pénztárban és az OpenCart 3 beépített pénztárában.

🔒

Validáció

Journal3 pénztárban a rendelés nem adható le, amíg konkrét csomagpont nincs kiválasztva a listából. Standard OC3-ban ezt a szerver oldali validáció kezeli.

📋 Követelmények

🛍️

OpenCart 3.0.5 Más 3.x verziókon nem tesztelt

🎨

Journal 3.28 Opcionális – alap OC3 témával is működik

🐘

PHP 8.x Tesztelve: PHP 8.0, 8.1, 8.2

🗄️

MySQL / MariaDB MyISAM engine a csomagpont táblához

🌐

Internet hozzáférés GLS API eléréshez (csomagpont frissítés)

📂

FTP / SFTP Fájlok feltöltéséhez

ℹ️

A allow_url_fopen PHP beállításnak engedélyezettnek kell lennie a GLS API eléréséhez (csomagpont lista letöltése). Ez legtöbb tárhelyen alapértelmezetten be van kapcsolva.

⚙️ Hogyan működik

A modul két független mechanizmusból áll: az interaktív pénztár UI-ból és a cím frissítő event handler-ből.

Pénztár folyamata (vásárlói oldal)

🛍️ Vásárló a pénztár szállítási lépéséhez ér

↓

⚙️ OC3 meghívja getQuote()-t → GLS elérhető → document→addScript('glshu.js')

JS automatikusan bekerül az oldalba, nincs OCMod

↓

📜 glshu.js MutationObserver figyeli a DOM-ot → GLS radio megjelenik

↓

🔄 AJAX: extension/shipping/glshu/getPoints → HTML dropdown visszatöltve és JS memóriában cache-elve (csak egyszer töltődik le oldalanként)

↓

👆 Vásárló választ a listából → radio értéke: glshu.glshu{place_id} → session frissül

Journal3: _QuickCheckout.save() · Standard OC3: Continue gomb

↓

✅ Rendelés leadva – session tartalmazza a pontos csomagpont kódot

Cím frissítés folyamata (rendelés után)

📝 catalog/model/checkout/order::addOrder() lefut → rendelés létrejön

Szállítási cím még a vásárló saját lakcíme

↓

⚡ OC3 event rendszer: addOrder/after → event/glshu_order::afterAddOrder()

↓

🔍 Session-ből kiolvasva: glshu.glshu{place_id} → DB lekérdezés a csomagpont adataiért

↓

🔄 SQL UPDATE az oc_order táblán – cím mezők felülírva a csomagpont adataival

↓

📧 Megerősítő email kiküldve – már a csomagpont adataival

Adatbázis tábla

Telepítéskor automatikusan létrejön az oc_z_glshu tábla:

Mező	Típus	Leírás
`place_id`	INT(6) AUTO_INCREMENT PK	Belső azonosító
`name`	VARCHAR(50)	Csomagpont neve
`city`	VARCHAR(25)	Város (nagybetűs)
`pcode`	VARCHAR(4)	Irányítószám
`address`	VARCHAR(50)	Utca, házszám
`country`	VARCHAR(10)	Ország (pl. Hungary)
`type`	VARCHAR(20)	`parcel-shop` vagy `parcel-locker`
`id`	VARCHAR(25)	GLS belső azonosító (pl. H1234)
`sort`	VARCHAR(3)	Sorrend (jelenleg fix: 1)

Hogyan frissül a szállítási cím a rendelésben

Az event handler az alábbi mezőket írja felül az oc_order táblában:

Mező	Tartalom
`shipping_address_1`	Csomagpont utca + házszám
`shipping_address_2`	GLS azonosító \| Csomagpont neve (pl. `H1234 \| GLS CityPoint`)
`shipping_city`	Csomagpont városa
`shipping_postcode`	Csomagpont irányítószáma

A shipping_firstname, shipping_lastname, shipping_company mezők érintetlenek maradnak – a vevő neve megmarad.

📁 Fájlstruktúra & Kód

upload/ ├── admin/ │ ├── controller/extension/shipping/ │ │ └── glshu.php ← Admin: telepítés, beállítások, adatfrissítés │ ├── language/en-gb/extension/shipping/ │ │ └── glshu.php ← Angol nyelvfájl (admin) │ ├── language/hu-hu/extension/shipping/ │ │ └── glshu.php ← Magyar nyelvfájl (admin) │ └── view/template/extension/shipping/ │ └── glshu.twig ← Admin beállítások sablon │ └── catalog/ ├── controller/event/ │ └── glshu_order.php ← Event handler: cím frissítés rendelés után ├── controller/extension/shipping/ │ └── glshu.php ← AJAX: csomagpont lista és adatok ├── language/en-gb/extension/shipping/ │ └── glshu.php ← Angol nyelvfájl (frontend) ├── language/hu-hu/extension/shipping/ │ └── glshu.php ← Magyar nyelvfájl (frontend) ├── model/extension/shipping/ │ └── glshu.php ← Fő logika: getQuote(), getPoints(), JS betöltés └── view/javascript/ └── glshu.js ← Frontend: dropdown, szinkron, validáció install.xml ← OCMod (üres – nem módosít fájlokat)

Fájlonkénti leírás

Fájl	Szerepe
`admin/controller/.../glshu.php`	install(): tábla létrehozása, event regisztráció az `oc_event` táblában, GLS adatok letöltése uninstall(): tábla törlése, event törlése refresh_data(): GLS API lekérése és adatbázis feltöltése index(): beállítások oldal megjelenítése
`catalog/model/.../glshu.php`	getQuote($address): szállítási ajánlat visszaadása, `$this→document→addScript()` JS betöltés, geo-zone / súly / méret ellenőrzés, POST és session alapú place_id meghatározás getPoints(): HTML dropdown generálása az AJAX válaszhoz
`catalog/controller/.../glshu.php`	getPoints(): AJAX endpoint – a model `getPoints()`-át hívja és HTML-t ad vissza getPointData(): egy csomagpont JSON adatait adja vissza place_id alapján
`catalog/controller/event/glshu_order.php`	afterAddOrder(): az `addOrder/after` event hívja. Kiolvas a sessionből, DB-ből lekéri a csomagpont adatait, UPDATE-eli az `oc_order` táblát
`catalog/view/javascript/glshu.js`	1. blokk: MutationObserver – GLS radio megjelenésekor AJAX-szal betölti a dropdown HTML-t; a választ JS változóban cache-eli, így DOM-újrarajzoláskor (pl. Journal3 recalculation) nincs újabb szerver hívás 2. blokk: select ↔ radio szinkronizáció, Journal3 `_QuickCheckout.save()` hívás 3. blokk: Journal3 validáció – `_QuickCheckout.confirm()` hookja, placeholder esetén blokkolja a rendelést
`install.xml`	OCMod fájl – jelenleg üres (nem módosít semmit). Szükséges az OC3 extension rendszeréhez

Az event regisztráció működése

Az OC3 event rendszere az oc_event táblából tölti be a hookokat az oldal betöltésekor. A modul telepítésekor (install()) az alábbi rekord kerül be:

Mező	Érték
`code`	`glshu_order_address_fix`
`trigger`	`catalog/model/checkout/order/addOrder/after`
`action`	`event/glshu_order/afterAddOrder`
`status`	`1` (aktív)

⚠️

Az event csak az install() futtatásakor kerül be a DB-be – ez automatikusan lefut, amikor az admin felületen aktiválod a modult. Ha korábban telepítve volt, először kapcsold ki (Disable), majd kapcsold vissza (Enable), hogy az event újra regisztrálódjon.

1 Fájlok feltöltése

Töltsd fel az összes fájlt FTP / SFTP-vel a webshop gyökérkönyvtárába. A mappa struktúra megfelel a szerver struktúrájának – egyszerű 1:1 másolás.

1

Nyisd meg az FTP klienst (pl. FileZilla)
2

Navigálj a webshop gyökérkönyvtárába (ahol az index.php van)
3

Másold fel az upload/ mappa tartalmát – az admin/ és catalog/ mappákat a gyökérbe, az install.xml-t szintén a gyökérbe

ℹ️

Meglévő fájlok felülírása szándékos – frissítés esetén így kerülnek be az újabb verziók. Az adatbázis tartalmát ez nem érinti.

2 OCMod frissítés

1

Admin → Extensions → Modifications
2

Kattints a Refresh gombra (jobbra fent, kék ikon)
Az OC3 feldolgozza az install.xml-t és frissíti a módosítás gyorsítótárat.

✅

Az install.xml jelenleg üres módosítást tartalmaz – ez normális, nem kell aktív OCMod bejegyzést keresni. A Refresh mégis szükséges, hogy az OC3 regisztrálja az extension-t.

3 Aktiválás az admin felületen

1

Admin → Extensions → Extensions → Shipping
2

Keresd meg: GLS PickUP a listában
3

Kattints az Install gombra (zöld + ikon)
Ez lefuttatja az install() metódust:
  • Létrehozza az oc_z_glshu táblát
  • Beregisztrálja a cím frissítő eventet az oc_event táblában
  • Letölti a GLS csomagpont adatait az API-ról
4

Kattints az Edit gombra (ceruza ikon) a beállítások megadásához

⚠️

Az Install lépés során a szerver letölti a GLS csomagpont adatbázist a map.gls-hungary.com API-ról. Ez néhány másodpercig tarthat – ne navigálj el az oldalról, amíg a folyamat be nem fejeződik.

4 Beállítások megadása

Beállítás	Leírás	Alapértelmezett
Státusz *	Modul engedélyezése / letiltása	Letiltva
Szállítási költség	GLS csomagpont szállítási ára (az üzlet alap pénznemében)	0
Ingyenes fölött	Ennyi összeg felett a szállítás ingyenes. 0 = mindig fizetős	0
Maximum súly (kg)	Ha a kosár összsúlya meghaladja, a GLS opció nem jelenik meg	40
Maximum méret (cm)	Ha bármely termék leghosszabb oldala meghaladja, a GLS opció nem jelenik meg	200
Típus	Melyik csomagpont típust jelenítse meg: • Csak csomagpontok (parcel-shop) • Csak automaták (parcel-locker) • Automaták & Csomagpontok (mindkettő)	Csak csomagpontok
Adó	Adóosztály a szállítási díjhoz	Nincs
Terület	Geo-zone korlátozás. Ha üres, mindenütt elérhető	Minden terület
Sorrend	A szállítási módok listájában elfoglalt hely (kisebb = előrébb)	0

ℹ️

A szállítási költséget az OC3 alapvalutájában add meg. A pénztárban automatikusan a vásárló pénznemére lesz átváltva az árfolyam alapján.

5 Csomagpontok frissítése

A GLS rendszeresen frissíti a csomagpont listáját. A modul beépített frissítővel rendelkezik:

1

Admin → Extensions → Shipping → GLS PickUP → Edit
2

Kattints a sárga „Címlista frissítése" gombra (jobb felső sarok)
A rendszer letölti a legfrissebb adatokat a GLS API-ról (map.gls-hungary.com/data/deliveryPoints/hu.json), törli a régi adatokat és újratölti a teljes táblát.

⚠️

A frissítés az összes régi csomagpont adatot törli és újra feltölti. A place_id értékek megváltozhatnak – ha más rendszerek hivatkoznak ezekre (pl. korábbi rendelések), azok nem érintik a már lezárt rendeléseket, mert ott a csomagpont adata már az oc_order táblában van rögzítve.

Az admin beállítások oldal alján megjelenik az összes elérhető csomagpont táblázata a frissítés után.

🔄 Frissítés újabb verzióra

Töltsd fel az új fájlokat FTP-vel (felülírja a régieket)
Admin → Extensions → Modifications → Refresh
Admin → Extensions → Shipping → GLS PickUP → Disable, majd Enable
Ez újra futtatja az install()-t, ami frissíti az event regisztrációt és a tábla struktúrát
Ellenőrizd a beállításokat – az értékek megmaradnak

✅

Az install() CREATE TABLE IF NOT EXISTS-t használ, tehát a meglévő csomagpont adatokat nem törli frissítéskor.

🗑️ Eltávolítás

Admin → Extensions → Shipping → GLS PickUP → Uninstall (piros – gomb)
Törli az oc_z_glshu táblát és a glshu_order_address_fix event bejegyzést
Fájlok manuális törlése a szerverről (az összes feltöltött fájl)
Admin → Extensions → Modifications → Refresh

⚠️

Az Uninstall az oc_z_glshu táblát és az összes csomagpont adatot visszavonhatatlanul törli. A korábban már lezárt rendelések szállítási adatait ez nem érinti – azok az oc_order táblában vannak.

🔧 Hibaelhárítás

⛔ A csomagpont dropdown nem jelenik meg a pénztárban

1. Ellenőrizd, hogy a modul státusza Engedélyezve.
2. Böngésző konzolban keresd a [GLSHU] üzeneteket – ha nincs, a glshu.js nem töltődött be.
3. Ellenőrizd, hogy az oc_z_glshu táblában vannak-e sorok (Admin → Edit → csomagpont lista látható-e az oldal alján).
4. A getQuote() csak akkor tölti be a JS-t, ha a GLS szállítási mód elérhető – ellenőrizd a súly/méret limiteket és a geo-zone beállítást.

⛔ A rendelés szállítási cím nem frissül a csomagpont adataira

1. Ellenőrizd az oc_event táblában, hogy létezik-e a glshu_order_address_fix sor.
2. Ha nem létezik: Admin → GLS PickUP → Disable, majd Enable (újra futtatja az install()-t).
3. Ellenőrizd a PHP error_log-ban, hogy van-e [GLSHU] bejegyzés rendelés leadásakor.
4. Valószínű ok: a vásárló GLS-t választott, de nem választott konkrét csomagpontot a listából (a session csak glshu.glshu-t tartalmaz place_id nélkül).

⛔ Telepítéskor SQL hiba / tábla nem jön létre

Ellenőrizd, hogy az adatbázis felhasználónak van-e CREATE TABLE jogosultsága. MySQL szigorú módban (strict mode) is előfordulhat hiba – ellenőrizd a PHP error_log-ot a pontos hibaüzenetért.

⛔ „Címlista frissítése" gomb nem csinál semmit / fehér oldalt dob

1. A allow_url_fopen PHP beállítás ki van kapcsolva – engedélyezd a php.ini-ben vagy a tárhely vezérlőpultban.
2. Tűzfal blokkolja a map.gls-hungary.com API-t a szerver oldalon – ellenőrizd cURL-lel: curl https://map.gls-hungary.com/data/deliveryPoints/hu.json
3. PHP max_execution_time lejár – az API válasz lassú lehet, növeld az időkorlátot.

⛔ Journal3 pénztárban a rendelés leadható csomagpont kiválasztása nélkül

A glshu.js 3. blokkja hookol a _QuickCheckout.confirm()-ba. Ha ez mégsem blokkolja, ellenőrizd böngésző konzolban, hogy a [GLSHU] Event listener-ek hozzáadva üzenet megjelenik-e. Ha nem, a Journal3 API megváltozott – frissíteni kell a modult.

⛔ Standard OC3 pénztárban GLS nem fogadja el a csomagpont kódot

A getQuote() POST-ellenőrzéssel dolgozik – a Continue gomb POSTjából olvassa ki a place_id-t. Ha a validáció mégis hibát dob, ellenőrizd a PHP verziót (8.0+ szükséges) és hogy a $this→request→post elérhető-e a modell kontextusban.

⛔ Nincs jogosultságod hiba az admin mentésnél

Admin → System → Users → User Groups → adjunk hozzá extension/shipping/glshu jogosultságot (view + modify).

Debug: event ellenőrzése adatbázisban

SELECT * FROM oc_event WHERE code = 'glshu_order_address_fix';

Ha üres az eredmény, az event nincs regisztrálva. Megoldás: Disable + Enable a modul admin felületén.

Debug: utolsó rendelés cím adatainak ellenőrzése

SELECT order_id, shipping_address_1, shipping_address_2, shipping_city, shipping_postcode
FROM oc_order
ORDER BY order_id DESC
LIMIT 5;

Ha a shipping_address_2 tartalmaz H1234 | GLS CityPoint formátumú adatot, az event sikeresen futott.

GLS PickUP HungarySzállítási Modul