myGLS API – címkenyomtatás és státuszszinkron OpenCart 3-hoz

ShopShine myGLS API 1.0.0 – OpenCart 3 dokumentáció

1. Rendeltetés

A modul OpenCart-rendelésekből myGLS-küldeményt és GLS-címkét készít, eltárolja a Parcel ID-t és a csomagszámot, továbbá időzítetten visszatölti a GLS csomagkövetési eseményeket. A napi használat az OpenCart natív Értékesítés → Rendelések oldalán történik.

2. Rendszerkövetelmények

• OpenCart 3.x
• PHP 7.0+
• PHP cURL és JSON bővítmény
• HTTPS használata ajánlott
• aktív GLS szerződés, myGLS felhasználónév, jelszó és Client Number
• az automatikus státuszszinkronhoz tárhelyi cron lehetőség

A modul nem biztosít GLS-szerződést vagy API-hozzáférést. Az engedélyezett szolgáltatásokat és korlátokat a kereskedő GLS-megállapodása határozza meg.

3. Telepítés és frissítés

1. Készítsen biztonsági mentést a fájlokról és az adatbázisról.
2. Nyissa meg a Bővítmények → Telepítő oldalt.
3. Töltse fel a shopshine_mygls_api_oc3_v1.0.0.ocmod.zip fájlt.
4. Nyissa meg a Bővítmények → Módosítások oldalt, majd frissítse az OCMOD gyorsítótárat.
5. A Bővítmények → Bővítmények → Modulok oldalon telepítse a ShopShine myGLS API modult.
6. Nyissa meg a modult a közvetlen bal oldali menüpontból vagy a modulok listájából.

Frissítéskor nem kell eltávolítani a modult vagy törölni az adatbázist. Telepítse rá az új csomagot, majd frissítse az OCMOD- és témagyorsítótárat.

4. API-kapcsolat

Az API kapcsolat fülön állítsa be:

• környezet: teszt vagy éles;
• ország;
• myGLS felhasználónév és jelszó;
• GLS Client Number;
• modul állapota.

Mentse el a beállításokat, majd használja a Kapcsolat ellenőrzése gombot. A teszt- és éles myGLS hozzáférés eltérhet; az éles hitelesítő adatok nem feltétlenül használhatók a tesztkörnyezetben.

5. Felvételi cím

A Felvételi cím fülön adja meg a feladó nevét, országát, irányítószámát, városát, utcáját, házszámát, kapcsolattartóját, telefonszámát és e-mail-címét. Ezek a címke feladói adatai.

6. Címke és szolgáltatások

Válassza ki:

• a nyomtatótípust és a kezdő címkepozíciót; a modul közvetlen kimenete PDF, ezért a választott myGLS-típusnak PDF-et kell visszaadnia;
• az automatikus csomagfeladást indító OpenCart rendelési státuszt;
• az utánvétes fizetési módokat;
• a GLS CsomagPontba vagy Automatába kézbesítő szállítási módokat;
• az FDS e-mail- és szükség esetén FSS SMS-szolgáltatást;
• a címkén megjelenő tartalmi szöveget.

Ha nincs kiválasztva automatikus csomagfeladási státusz, a címkekészítés kizárólag kézzel történik. Az automatikus címkekészítéshez nem kell cron: a beállított rendelési státuszra váltás indítja el.

7. Kézi és tömeges címkekészítés

1. Nyissa meg az Értékesítés → Rendelések oldalt.
2. Jelöljön ki egy vagy több rendelést.
3. Kattintson a felső myGLS címkék létrehozása / nyomtatása gombra.
4. A modul létrehozza a küldeményeket, majd megnyitja a közös PDF-et.

Az A4 2×2 beállítással négy kijelölt rendelés négy címkéje egy A4-es lapra kerülhet. Multistore rendszerben több üzlet rendelései akkor nyomtathatók közös PDF-be, ha az üzletekben azonos myGLS fiók-, ügyfélszám-, környezet- és nyomtatási beállítás szerepel.

8. Utánvét

Az utánvétes fizetési módokat név alapján lehet kijelölni. A modul ezeknél a rendelés OpenCartban tárolt végösszegét és pénznemét küldi a myGLS-nek, és COD szolgáltatást ad a küldeményhez. Hibásan kiválasztott fizetési mód téves utánvétet eredményezhet, ezért éles indulás előtt ellenőrizze egy tesztrendeléssel.

9. GLS CsomagPont és Automata

A csomagponti szállítási módokat szintén név szerint kell kijelölni. Ezeknél a modul PSD szolgáltatást küld a rendelésben tárolt GLS pontazonosítóval. Minden más szállítási mód házhozszállításként kerül feldolgozásra.

A modul önmagában nem jelenít meg térképet a pénztárban. Térképes kiválasztáshoz külön GLS CsomagPont szállítási modul szükséges, például ShopShine GLS CsomagPont Pro.

10. GLS státuszszinkron és cron

1. Nyissa meg a GLS státuszok fület.
2. Engedélyezze a státuszszinkront.
3. Állítsa be a követési időszakot; az ajánlott alapérték 90 nap.
4. Mentse el a modult.
5. Másolja ki az üzlethez tartozó Cron URL-t.

Javasolt futtatás 15–30 percenként:

/usr/bin/curl -fsS -L --max-time 120 "AZ_ADMINBAN_MEGJELENŐCRONURL" > /dev/null 2>&1

Egy futás legfeljebb 50 küldeményt dolgoz fel, mindig a még sosem ellenőrzött, majd a legrégebben frissített rekordokkal kezdve. Napi néhány tíz rendelésnél a 15–30 perces futtatás elegendő. Multistore esetén minden üzlethez külön Cron URL tartozik.

Az első sikeres lekérés után a megismert GLS státuszok OpenCart rendelési státuszokhoz rendelhetők. A hozzárendelés nélküli esemény csak tájékoztatásként jelenik meg. A végleges státuszok „Lezárt” jelölést kaphatnak, így kikerülnek a további lekérdezésekből.

11. Duplikált címkék elleni védelem

A modul rendelésenkénti MySQL-zárat használ, és új címke előtt az OC-{order_id} ügyfélhivatkozással a myGLS-ben is keres. Ha már létezik küldemény, azt visszaszinkronizálja új címke létrehozása nélkül.

A myGLS-ben törölt, majd újra létrehozott címke új csomagszámát elsődlegesen ugyanezzel a hivatkozással keresi. Ha nincs hivatkozás, csak egyértelmű címzett-, dátum- és utánvétadat-egyezésnél végez automatikus cserét.

12. Manuálisan létrehozott csomag hozzárendelése

Ha egy sikertelen API-próba után a küldeményt kézzel hozták létre a myGLS-ben:

1. a rendelés műveleti menüjében válassza a Meglévő GLS csomagszám hozzárendelése pontot;
2. adja meg a numerikus GLS csomagszámot;
3. a modul ellenőrzi, hogy a csomag megtalálható-e a beállított fiókban;
4. eltérő ügyfélhivatkozás, e-mail vagy irányítószám esetén megtagadja a kapcsolást;
5. siker esetén eltárolja a Parcel ID-t, törli a régi hibát és elindítja a követést.

   13. Tesztközpont

Teszt API-módban egy meglévő rendelés adatai ellenőrizhetők, tesztküldemény készíthető, a PDF megnyitható, majd a küldemény törölhető. Teszt-hozzáférés hiányában az éles környezetben kontrollált próbacímke készíthető: a modul utánvét nélkül létrehozza, majd azonnal megpróbálja törölni. Az éles próba esetleges GLS elszámolási következményeiről a GLS ad hivatalos tájékoztatást.

14. Naplózás és hibakeresés

A napló helye:

storage/logs/shopshine_mygls.log

A napló nem tartalmaz API-jelszót vagy cron kulcsot. Hibánál ellenőrizze:

• a myGLS hitelesítő adatokat és Client Numbert;
• a rendelés szállítási címét és kétbetűs országkódját;
• az utánvétes fizetési módok kiválasztását;
• csomagpontnál a PSD pontazonosítót;
• az OCMOD- és témagyorsítótár frissítését;
• a cron megfelelő store_id értékét multistore környezetben.

  15. Korlátok

• Egy rendelésből egy GLS-küldemény készül.
• A súly és méretek nem kerülnek át; Magyarországon ezek opcionális myGLS-adatok, a tényleges súlyt a GLS a fizikai feldolgozás során rögzítheti.
• Napi használatban a címke törlése és a feladás visszavonása a myGLS felületén végezhető.
• Egyedi OpenCart-adminmódosításokkal való kompatibilitás külön ellenőrzést igényelhet.