Str. 1/5 Geis Point Plugin Map Rozhraní pro vložení výdejního místa do objednávky na e-shopu
Str. 2/5 Obsah 1. Co je Geis Point Plugin Map?... 3 2. Jak to funguje?... 3 3. Obecný postup nasazení... 3 4. Seznam GET parametrů... 4 5. Chybové stavy... 5 Verze dokumentu: 2014-09 (1. 9. 2014)
Str. 3/5 1. Co je Geis Point Plugin Map? Geis Point Plugin Map (dále jen GPPM) je rozhraní, na které je přesměrován zákazník vašeho e-shopu a slouží pro výběr výdejního místa Geis Point (dále jen VM). Zákazník e-shopu může s pomocí vyhledávacího formuláře nebo interaktivní mapy vyhledat a zvolit VM pro doručení zásilky. Na základě adresy pro doručení (načtené z objednávky e-shopu) jsou uživateli zobrazeny nejbližší VM, následně si může vybrat nejlépe vyhovující VM. 2. Jak to funguje? Uživatel je ve fázi výběru doručení/dopravce z vašeho e-shopu přesměrován na GPPM i s jeho adresou pro doručení. Na mapě je označena jeho adresa pro doručení, kolem které je vyznačen 10 km poloměr, zbarvený červeně. V interaktivní mapě či ze seznamu si vybere VM, o kterém lze zobrazit více informací. V posledním kroku je potvrzení volby daného VM, jako místa pro doručení. V případě, že si uživatel nezvolí VM z daného předvýběru, je možné použít filtr v horní části GPPM, který má tyto funkce: Vyhledávání podle PSČ Vyhledávání podle kraje či města Vyhledávání podle kódu výdejního místa GPPM rozhraní (aplikace) se nachází na adrese http://plugin.geispoint.cz/map.php. Tato aplikace přijímá GET parametry 3. Obecný postup nasazení 1. Přidání dalšího doručovacího způsobu do vašeho e-shopu. Např.: Geis Point výdejní místo 2. Implementace GPPM s GET vstupními parametry z e-shopu. a. Příprava povinných parametrů CustAdress a ReturnURL včetně vlastních proměnných (viz níže). Tyto parametry se budou odesílat s pomocí odkazu na GPPM z vašeho e-shopu. b. Příprava nepovinných parametrů GPID. V případě, že umožníte zákazníkovi vybrat na vašem e- shopu z číselníku Geis Point Výdejních Míst, takto jej předpřipravíte pro použití na GPPM. VM je možné následně změnit. c. Zaslání všech parametrů do GPPM pro otestování a případná oprava chyb při implementaci vstupních parametrů viz chybové stavy GPPM. 3. Seznámení se s GPPM rozhraním
Str. 4/5 a. Operace s filtry, interaktivní mapou a seznamy. b. Testování uživatelských chybových stavů. c. Zobrazení detailu VM. 4. Implementace GPPM návratových hodnot do vašeho e-shopu. a. Při kliknutí na tlačítko potvrdit výběr je uživatel vrácen zpět do e-shopu podle vámi definované návratové ReturnURL (příklad realizace návratové URL viz níže). b. Implementace příjmu návratových hodnot GPName, GPAddress a GPID do Vašeho e-shopu. c. Testování návratové implementace a ukládání s dokončením nákupu na Vašem e-shopu. 5. Potvrzení správnosti implementace nového způsobu doručení. Jde především o bezproblémové dokončení a uložení objednávky. 4. Seznam GET parametrů GPID (nepovinný) - do tohoto parametru je vložen kód VM, který má odběratel ve vašem objednávkovém formuláři zvolen (pokud tuto možnost objednávkový formulář nabízí (viz výše). Pokud je nastaven, bude na mapě po zobrazení vybrán tento konkrétní Geis Point. CustAddress (povinný) - do tohoto parametru je vložena adresa odběratele. Mapa je vycentrována podle zadané adresy a je kolem ní zobrazen kruh o průměru 10 km. Doporučený formát tohoto parametru je: Ulice č.p./č.o.;město;psč. ReturnURL (povinný) - tento parametr obsahuje URL, na kterou bude odběratel po vybrání VM přesměrován. V URL lze použít i vlastní GET proměnné. Je nutné použít URL ENCODE formát pro CELÝ tento parametr a tedy i na zřetězené vlastní proměnné v rámci tohoto parametru. V opačném případě by GPPM nevrátil zpět všechny proměnné. V případě, že nezadáte povinné parametry, aplikace vrátí chybu a nebude možné pokračovat. Příklad vlastních ReturnURL proměnných: ReturnID a ReturnSSID jedná se o vlastní proměnné, obsažené v parametru ReturnURL. Nejsou vráceny, pokud je nedefinujete v ReturnURL. Můžete tedy použít jakýkoliv název vlastních proměnných a jejich libovolný počet. Modelový příklad URL obsahující GET parametry pro GPPM: Výchozí situace dle e-shopové objednávky: Uživatel má v objednávkovém formuláři e-shopu jako adresu pro doručení vyplněno: Jungmannova 17. Praha 1, 110 00. Předběžně u Vás na e-shopu vybral pro doručení Geis Point s kódem VM-9901. Vámi definovaná, návratová URL (ReturnURL) je: http//www.urleshopu.cz/něco.php?returnid=102&returnssid=session Odkaz na GPPM z e-shopu bude vypadat takto:
Str. 5/5 http://plugin.geispoint.cz/map.php?gpid=vm-9901&custaddress=jungmannova 17,Praha 1,11000&ReturnURL=http%3A%2F%2Fwww.urleshopu.cz%2Fneco.php%3FReturnID%3D102%26ReturnSSID%3Ds ession Výsledek Vyhledá se adresa Jungmannova 17, Praha 1, 110 00 a mapa se na ni přesune. V případě že nebyla adresa nalezena, pak GPPM vypíše chybu, že daná adresa nebyla nalezena. Nebude vykreslen patřičný červený kruh se žlutým okrajem, nicméně je možné pokračovat ručním výběrem VM. Dále je vypsána informace o Geis Pointu VM-9901, který byl do GPPM odeslán jako vstupní parametr z e- shopové objednávky. V případě, že nebyl zadán vstupní parametr GPID pak nedochází k předvýběru VM pro výchozí stav GPPM. Návratová URL pak bude vypadat nějak takto: http://www.urleshopu.cz/neco.php?returnid=102&returnssid=session&gpname=trafika+u+tr%c5%bdnice &GPAddress=Bude%C4%8Dsk%C3%A1+33%3BPraha+2%3B12000&GPID=VM-9901 Význam proměnných: GPName název Geis Pointu GPAddress adresa Geis pointu, nejdříve je potřeba provést URL ENCODE, jednotlivé údaje jsou odděleny středníkem: Ulice čp/čo;město;psč GPID ID vybraného Geis Pointu Závažné chybové stavy 5. Chybové stavy Systém vrací 2 závažné chyby, s těmito chybami nelze pokračovat, aplikace se nespustí. Pokud je implementace provedena korektně uživatel se s nimi nesetká. Jsou to tyto stavy: 1. Chyba: nebyl zadán vstupní parametr CustAdress 2. Chyba: nebyl zadán vstupní parametr ReturnURL Přeskočitelné chybové stavy Dále mohou nastat 3 přeskočitelné chybové stavy, s kterými se setká uživatel: 1. Vámi zadaná adresa nebyla nalezena. - V případě, že adresa z parametru CustAdress nebyla nalezena. 2. Geis Point, který byl zvolen u partnera nebyl nalezen. - V případě, že GPID nebylo aplikací nalezeno. 3. Je nám líto, ale daným parametrům neodpovídá žádný záznam. Nejbližší Geis Point naleznete na mapě. - V případě použití filtrů v aplikaci, kdy nebyl nalezen žádný záznam.