Kvikk Pro térképes csomagpont és címkenyomtató modul – OpenCart 3-hoz

# ShopShine Kvikk Pro – telepítési és használati útmutató

## 1. Rendszerkövetelmények

- OpenCart 3.x
- PHP 7.2 vagy újabb
- PHP cURL, JSON és mbstring bővítmény ajánlott
- HTTPS
- aktív Kvikk-fiók és API-hozzáférés
- cron hozzáférés az automatikus státuszfrissítéshez

## 2. Fontos kompatibilitási tudnivaló

A ShopShine Kvikk Map legyen az áruház egyetlen aktív térképes csomagpontválasztó modulja. A korábbi, azonos futárszolgáltatókhoz tartozó GLS, MPL, FOXPOST, Packeta vagy DPD csomagpontmodulokat kapcsolja ki. A hagyományos házhozszállítási módok aktívak maradhatnak.

## 3. Telepítési sorrend

1. Készítsen teljes fájl- és adatbázismentést.
2. Az OpenCart adminban nyissa meg a **Bővítmények > Telepítő** oldalt.
3. Telepítse a `shopshine_kvikk_map_oc3_v1.0.0.ocmod.zip` fájlt.
4. Telepítse a `shopshine_kvikk_api_oc3_v1.0.0.ocmod.zip` fájlt.
5. Nyissa meg a **Bővítmények > Módosítások** oldalt, majd kattintson a frissítés ikonra.
6. Törölje az OpenCart, a sablon és – ha használja – a Journal gyorsítótárát.

Frissítéskor a korábbi verzió eltávolítása nem szükséges; az új telepítő rátelepíthető.

## 4. Kvikk Map beállítása

1. Nyissa meg a **Bővítmények > Bővítmények > Szállítás** menüt.
2. Telepítse és nyissa meg a **ShopShine Kvikk Map** modult.
3. Adja meg a 64 karakteres Kvikk Map API-kulcsot.
4. Válassza ki a használt pénztárt: OpenCart alapértelmezett, Journal vagy Xtensions Best Checkout.
5. Engedélyezze a kívánt futár- és ponttípusokat.
6. Állítsa be az alapárakat, az ingyenességi határt, valamint szükség szerint a kosárérték-, súly- és vásárlóicsoport-sávokat.
7. Mentse a modult, majd használja a kapcsolatellenőrzést.

A vásárló a térképen választja ki az átvételi helyet. A végleges szállítási díj a kiválasztott szolgáltató és ponttípus alapján, az átvételi hely kiválasztása után jelenik meg.

## 5. Kvikk API beállítása

1. A Kvikk felületén nyissa meg a beállításokat, keresse meg az API-hozzáférést, és hozzon létre új API-kulcsot.
2. Az OpenCart adminban nyissa meg a **ShopShine Kvikk API** modult.
3. Adja meg az API-kulcsot, és mentse el a modult.
4. Csak mentés után kattintson a **Kapcsolat ellenőrzése** gombra.
5. Válassza ki a Kvikk-fiókban rögzített feladót.
6. Állítsa be az alapértelmezett házhozszállító futárt és a tartalék csomagsúlyt.
7. Jelölje be azokat a webáruházi fizetési módokat, amelyek utánvétnek számítanak.

## 6. Címkekészítés

Az OpenCart **Értékesítés > Rendelések** listájában jelölje ki a kívánt rendelést vagy rendeléseket, majd kattintson a Kvikk címkekészítő gombra. A modul:

- felismeri a házhozszállításos és csomagpontos rendelést;
- csomagpontos rendelésnél átadja a futárt, ponttípust és pontazonosítót;
- a kiválasztott fizetési mód alapján hozzáadja az utánvétet;
- elmenti a Kvikk- és futárszolgálati követési számot;
- megnyitja vagy letölti a címkét.

Biztonsági okból csomagpontos rendelésből nem készül házhozszállítási címke, ha a strukturált pontazonosító hiányzik.

## 7. Státuszszinkron és cron

A modul beállításainál minden Kvikk eseményhez külön OpenCart rendelési státusz rendelhető. A támogatott események:

- `booked` – címke elkészült
- `sent` – átadva a futárnak
- `in_transit` – szállítás alatt
- `out_for_delivery` – kiszállítás alatt
- `ready_for_pickup` – átvehető a csomagponton
- `delivered` – kézbesítve vagy átvéve
- `failed` – sikertelen kézbesítés
- `returned` – visszaküldve a feladónak

Mentés után másolja ki a modul által megjelenített cron parancsot, és futtassa például 30 percenként. A kézbesített és visszaküldött küldeményeket a modul lezárja, ezért azokat később nem kérdezi le feleslegesen.

## 8. Multistore

Minden áruházhoz külön térképes és API-beállítások, API-kulcs, feladó, árképzés, utánvétes fizetési módok, státusz-hozzárendelések és cron URL menthető.

## 9. Rendelésmódosítás

A modul megőrzi a kiválasztott csomagpontot és az eredeti szállítási díjat, amikor az adminisztrátor például telefonszámot, e-mail-címet vagy más rendelési adatot módosít. A címke elkészítése előtt mindig ellenőrizze a módosított rendelést.

## 10. Hibaelhárítás

- Telepítés után mindig frissítse a Módosításokat és ürítse a gyorsítótárakat.
- Ellenőrizze, hogy csak a Kvikk Map biztosítja-e az érintett csomagpontos szállítási módokat.
- A kapcsolatellenőrzést csak az API-kulcs mentése után indítsa.
- `Invalid delivery point ID` esetén frissítse mindkét modult a legújabb verzióra.
- Cronhiba esetén nyissa meg a cron URL-t böngészőben, és ellenőrizze a JSON-választ.