Termékimportálás a Kirakat.hu rendszerbe Készítette: Zsoldos Dániel
Bevezetés A technikai részletek megismerése előtt célszerű a Kirakat.hu alapvető működésével tisztában lenni. A Kirakatban találhatunk termékcsoportokat és termékkategóriákat. Az Ügyfeleink termékei mindig egy vagy több megfelelő termékkategóriában lesznek megtalálhatóak. Termékcsoport (például Fotó, videó ) \/ Termékkategória (például Memóriakártyák ) \/ Ügyfél termékei A termékcsoportokat és kategóriákat a szerkesztők kézzel rögzítik a rendszerben, majd ezután kezdődhet meg a termékek tényleges importálása. 1. Az Ügyfél termékadatbázisának átvétele Abban az esetben, amikor az egyes termékkategóriák és azok termékeinek létrehozása a termékek mennyisége miatt problémát jelent, úgy amennyiben lehetséges, átvesszük az Ügyfél teljes termékadatbázisát. Ez a pont azon Ügyfeleinkre nem vonatkozik, akik műszaki cikkeket forgalmaznak (ugrás a dokumentum 2. pontjára). A termékadatbázis átvételéhez első lépésként a szerkesztőségnek létre kell hozni a megfelelő termékcsoportot és termékkategóriát, amennyiben az még nem létezik. A termékcsoportot az adatbázisunk termekcsoport táblájában egy egyedi termekcsoportid mező jelöli (auto_increment tulajdonság), míg a termékkategóriát és a szükséges adatmezőket a termek_x táblában tároljuk, ahol x az új termékkategória egyedi azonosítója lesz (auto_increment tulajdonság). Szükséges adatmezők alatt, a termékkel kapcsolatos releváns adatokat* értjük. Természetesen a forgalmazott termékektől függően a releváns adatok mások és mások. A Kirakat.hu szempontjából a releváns adatokat az olyan adatok jelentik, amelyek egy termékkategórián belül általánosan adottak az egyes termékekre, lásd a következő példát. Könyv: ISBN szám, műfaj, oldalszám, nyelv Ruházat: szín, anyagösszetétel, kategória (pl. kabát, cipő, pulóver stb.) Játék: ajánlott életkor, méret, kategória (pl. társasjáték, plüss, stb.) DVD: műfaj, játékidő, rendező, szereplők, korhatár CD: műfaj, játékidő stb. A termékek importálásához szükség lesz egy az Ügyfél adatbázisáról készült export állományra, amelynek az Ügyfél döntésétől függően XML vagy CSV (Comma Separated Values) formátumúnak kell lennie. Ebbe az export fájlba kerülnek bele a termékek általános adatai, illetve a fent említett releváns adatokat tartalmazó mezők is.
Az export fájlban minden mező kitöltése kötelező, mivel a Kirakat.hu import modulja mindegyik mező esetében adatot vár az import folyamat során. A hiányzó adat a mezők értékeinek elcsúsztását, vagy az egész importfolyamat félbeszakadását eredményezheti! A CSV formátumú export fájl felépítése (a releváns adatokat tartalmazó mezők jelölése: rm1, rm2 stb.): egyeditermekid ; gyarto ; termeknev ; nettoar ; bruttoar ; bruttoarszallitassal ; raktaron ; cikkszam ; url ; kepurl ; leiras ; rm1 ; rm2 ; stb. ; kategoria; Az XML formátumú export fájl felépítése (a releváns adatokat tartalmazó mezők jelölése: rm1, rm2, stb.): <?xml version="1.0" encoding="iso-8859-2"?> <catalog> <product> <id></id> <manufacturer></manufacturer> <name></name> <netprice></netprice> <grossprice></grossprice> <grosspricecarriage></grosspricecarriage > <stock></stock> <itemid></itemid> <urlsite></urlsite> <urlpicture></urlpicture> <describe></describe> <rm1></rm1> <rm2></rm2>... <category></category> </product> </catalog> Az export fájlban előforduló mezők magyarázata (az egyes mezők magyarázata, funkciója, tartalma a két különböző formátumú export fájl esetén megegyezik. Az alábbi listában az egyes pontok mezőelnevezései közül az első a CSV, a második az XML fájlban előforduló elnevezéseket tartalmazza): egyeditermekid / id : az az egyedi azonosító, amelyet az Ügyfél a saját áruházában használ a termékek azonosításához. KIEMELTEN FONTOS, HOGY EGY ADOTT AZONOSÍTÓ MINDENKOR UGYANAZT A TERMÉKET AZONOSÍTSA! Ez azt jelenti, hogy pl.: az 12345 azonosító mindig az X terméket azonosítsa. Az X termék esetleges megszűnése, vagy a kínálatból történő törlése esetén sem szabad hozzárendelni az 12345 azonosítót egy Y termékhez, mivel a rendszerünk az egyedi azonosító alapján azonosítja egy adott áruház adott termékét. Ha ez mégis megtörténik (egy egyszer már felhasznált azonosító hozzárendelése egy új termékhez), akkor az adott áruház teljes kínálatát deaktiválni kell a hibajavítás idejére. gyarto / manufacturer: a termék gyártója/kiadója termeknev / name: a termék megnevezése
nettoar / netprice: a termék nettó ára. Amennyiben az Ügyfél nem tárolja adatbázisában ezt az adatot, úgy az adat számíttatása az export fájlt generáló script segítségével történjen meg. bruttoar / grossprice: a termék bruttó ára bruttoarszallitassal / grosspricecarriage : a termék bruttó ára megnövelve a szállítási költséggel. A szállítási költség amellyel a termék bruttó árát kell növelni, mindig az adott egyetlen termék, az Ügyfél székhelyének városába történő házhozszállításának költségét jelentse. Amennyiben ez a szállítási költség semmilyen módon nem határozható meg, úgy ez a mező egy gondolatjelet ( - ) tartalmazzon (így az oldalon a megfelelő mezőben a Nincs adat fog megjelenni. raktaron / stock : a true/false értékek valamelyike, annak függvényében, hogy a termék megtalálható-e az Ügyfél raktárában. Amennyiben az Ügyfél nem rendelkezik raktárral, vagy a raktárkészlet túlságosan dinamikusan változik, úgy ebbe a mezőbe egy gondolatjel ( - ) kerüljön (így az oldalon a megfelelő mezőben egy szürke kérdőjel fog megjelenni). cikkszam / itemid : adott termék dobozán található cikkszáma. Amennyiben az Ügyfél nem használja/tárolja ezt az adatot, úgy e mező tartalma egyezzen meg az egyeditermekid mező tartalmával. FONTOS: a cikkszám mezőre az egyeditermekid mezőnél leírtak érvényesek! url / urlsite : az oldal címe az Ügyfél saját webáruházán belül, ami közvetlenül az adott termékre mutat. kepurl / urlpicture: a termékhez tartozó kép elérési útvonala. leiras / describe: a termék rövid, 1-2 mondatos leírása, bemutatása (a leírás mező tartalma az adatbázisban egy 255 karakter hosszúságú tartalmat megengedő mezőbe kerül, hosszabb szöveg esetén a leírás a 256. karaktertől kezdődően eldobásra kerül). FONTOS: a leírás mező nem tartalmazhat idézőjeleket, mert ez egyes esetekben megzavarhatja a Kirakat napi frissítésének menetét, aminek következtében az árak frissítése félbeszakadhat. Az idézőjelek helyett aposztrófok használatát javasoljuk. kategoria / category: az export fájl formátumától függetlenül minden esetben az adott termék utolsó mezője. Ebbe a mezőbe kell feltűntetni, hogy az adott termék a partner webáruházában milyen kategóriában található. Többszintű kategória rendszer esetén a mező tartalma a következő minta szerint alakuljon: főkategória kategória alkategória (a létező szinteknek megfelelően). Az export fájlban a fájl formátumától függetlenül csak és kizárólag a felsorolt mezőknek az előbbiekben megadott sorrendben és tartalommal szabad szerepelniük, ellenkező esetben az export fájlt elfogadni nem tudjuk! Az elkészült fájlt az Ügyfélnek a saját weboldalán belül egy általa választott URL-en elérhetővé kell tennie, illetve el kell végeznie a megfelelő beállításokat annak érdekében, hogy az export fájl az Ügyfél adatbázisából minden nap automatikusan újragenerálódjon (erre az automatikus import miatt lesz szükség, amely a következő részben olvasható). Amennyiben az Ügyfél az export fájlt nem tudja elérhetővé tenni, úgy a technikai kapcsolattartó egy FTP hozzáférést oszt ki, amelynek segítségével az export fájl feltölthető egy erre kijelölt szerverre. Az export fájl alapján, a termékek a megfelelő termékcsoport táblába lesznek importálva, a képek a megfelelő elérési útvonalra lesznek feltöltve. Ezeket elvégezve a táblák szükséges összekötését elvégezzük, a termékeket aktiváljuk, majd a termékimport fázist lezárjuk.
Megjegyzés: Az export fájl elkészítésekor az XML formátum választása esetén javasolt a következő mezők CDATA típusú deklarálása: manufacturer, name, describe. Ezzel elkerülhetőek a dumpba automatikusan bekerülő speciális karakterek által okozott hibák. * A releváns adatok egyeztetésének céljából, keresse meg a technikai kapcsolattartót, a dokumentum végén található elérhetőségek valamelyikén. 2. Az Ügyfél termékeinek összekapcsolása a rendszerben található termékekkel Ez a pont csak azon Ügyfeleinkre vonatkozik, akik műszaki cikkek forgalmazásával foglalkoznak (ellenkező esetben ugrás a dokumentum 3. pontjára). A Kirakat.hu adatbázisában a megfelelő termékkategóriák, az ezekben található termékek és adatlapok már megtalálhatóak a rendszerben, így a feladatunk az Ügyfél ajánlatainak hozzákapcsolása a létező termék adatlapokhoz. Az importálás megkezdése előtt szükségünk van egy, az Ügyfél által készített XML vagy CSV formátumú export fájlra, amelyben a termékek importálásához szükséges adatok szerepelnek majd. A készítendő export fájl formátumának eldöntését az Ügyfélre bízzuk, mindkét esetben nagyon hasonlóan és egyformán biztonságosan zajlik az importálás folyamata. A CSV fájl felépítése: egyeditermekid ; gyarto ; termeknev ; nettoar ; bruttoar ; bruttoarszallitassal ; raktaron ; cikkszam ; url ; kepurl ; leiras; kategoria; Az XML fájl felépítése: <?xml version="1.0" encoding="iso-8859-2"?> <catalog> <product> <id></id> <manufacturer></manufacturer> <name></name> <netprice></netprice> <grossprice></grossprice> <grosspricecarriage></grosspricecarriage > <stock></stock> <itemid></itemid> <urlsite></urlsite> <urlpicture></urlpicture> <describe></describe> <category></category> </product> </catalog> Az export fájlban előforduló mezők magyarázata: egyeditermekid / id : az az egyedi azonosító, amelyet az Ügyfél a saját áruházában használ a termékek azonosításához. KIEMELTEN FONTOS, HOGY EGY ADOTT AZONOSÍTÓ MINDENKOR UGYANAZT A TERMÉKET AZONOSÍTSA! Ez
azt jelenti, hogy pl.: az 12345 azonosító mindig az X terméket azonosítsa. Az X termék esetleges megszűnése, vagy a kínálatból történő törlése esetén sem szabad hozzárendelni az 12345 azonosítót egy Y termékhez, mivel a rendszerünk az egyedi azonosító alapján azonosítja egy adott áruház adott termékét. Ha ez mégis megtörténik (egy egyszer már felhasznált azonosító hozzárendelése egy új termékhez), akkor az adott áruház teljes kínálatát deaktiválni kell a hibajavítás idejére. gyarto / manufacturer: a termék gyártója/kiadója termeknev / name: a termék megnevezése nettoar / netprice: a termék nettó ára. Amennyiben az Ügyfél nem tárolja adatbázisában ezt az adatot, úgy az adat számíttatása az export fájlt generáló script segítségével történjen meg. bruttoar / grossprice: a termék bruttó ára bruttoarszallitassal / grosspricecarriage : a termék bruttó ára megnövelve a szállítási költséggel. A szállítási költség amellyel a termék bruttó árát kell növelni, mindig az adott egyetlen termék, az Ügyfél székhelyének városába történő házhozszállításának költségét jelentse. Amennyiben ez a szállítási költség semmilyen módon nem határozható meg, úgy ez a mező egy gondolatjelet ( - ) tartalmazzon (így az oldalon a megfelelő mezőben a Nincs adat fog megjelenni. raktaron / stock : a true/false értékek valamelyike, annak függvényében, hogy a termék megtalálható-e az Ügyfél raktárában. Amennyiben az Ügyfél nem rendelkezik raktárral, vagy a raktárkészlet túlságosan dinamikusan változik, úgy ebbe a mezőbe egy gondolatjel ( - ) kerüljön (így az oldalon a megfelelő mezőben egy szürke kérdőjel fog megjelenni). cikkszam / itemid : adott termék dobozán található cikkszáma. Amennyiben az Ügyfél nem használja/tárolja ezt az adatot, úgy e mező tartalma egyezzen meg az egyeditermekid mező tartalmával. FONTOS: a cikkszám mezőre az egyeditermekid mezőnél leírtak érvényesek! url / urlsite : az oldal címe az Ügyfél saját webáruházán belül, ami közvetlenül az adott termékre mutat. kepurl / urlpicture: a termékhez tartozó kép elérési útvonala. leiras / describe: a termék rövid, 1-2 mondatos leírása, bemutatása (a leírás mező tartalma az adatbázisban egy 255 karakter hosszúságú tartalmat megengedő mezőbe kerül, hosszabb szöveg esetén a leírás a 256. karaktertől kezdődően eldobásra kerül). FONTOS: a leírás mező nem tartalmazhat idézőjeleket, mert ez egyes esetekben megzavarhatja a Kirakat napi frissítésének menetét, aminek következtében az árak frissítése félbeszakadhat. Az idézőjelek helyett aposztrófok használatát javasoljuk. kategoria / category: az export fájl formátumától függetlenül minden esetben az adott termék utolsó mezője. Ebbe a mezőbe kell feltűntetni, hogy az adott termék a partner webáruházában milyen kategóriában található. Többszintű kategória rendszer esetén a mező tartalma a következő minta szerint alakuljon: főkategória kategória alkategória (a létező szinteknek megfelelően). Az export fájlban a fájl formátumtól függetlenül csak és kizárólag a felsorolt mezőknek az előbbiekben megadott sorrendben és tartalommal szabad szerepelniük, ellenkező esetben az export fájlt elfogadni nem tudjuk! Az elkészült fájlt az Ügyfélnek a saját weboldalán belül egy általa választott URL-en elérhetővé kell tennie, illetve el kell végeznie a megfelelő beállításokat annak érdekében, hogy az export fájl az Ügyfél adatbázisából minden nap automatikusan újragenerálódjon (erre az automatikus import miatt lesz szükség, amely a következő részben olvasható).
Amennyiben az Ügyfél az export fájlt nem tudja elérhetővé tenni, úgy a technikai kapcsolattartó egy FTP hozzáférést oszt ki, amelynek segítségével az export fájl feltölthető egy erre kijelölt szerverre. Az importálás során a rendszer kiolvassa az adott URL-en található export fájlból az adatokat, majd rögzíti egy úgynevezett termekartemp nevű táblában. Ennek az adattáblának a tartalma a szerkesztők adminisztrációs felületén a Termék import hibák -ként feltüntetésre kerül. Innen a szerkesztők jóváhagyásával a termékek átkerülnek a termekar táblába és aktiválódnak. Megjegyzés: Az export fájl elkészítésekor az XML formátum választása esetén javasolt a következő mezők CDATA típusú deklarálása: manufacturer, name, describe. Ezzel elkerülhetőek a dumpba automatikusan bekerülő speciális karakterek által okozott hibák. 3. Automatikus importok Annak érdekében, hogy biztosítani tudjuk a rendszerben található termékek és árak aktualitását, az Ügyfél termékeinek első importja után, a rendszer automatikus importálást végez. Ez annyit jelent, hogy a rendszer minden hajnalban (~ 3 óra) lekéri az Ügyfél által megadott URL-en elérhető automatikusan generálódó export fájlt, annak tartalmát kiolvassa, majd egy keresést futtat a termekar táblán. Ebben a keresésben megvizsgálásra kerül, hogy van-e új termék az export fájlban, illetve a már ismert termékek közül változott e valamelyik terméknek az ára, leírása, stb.. Az első esetben az új termékek megjelennek a termék import hibák között, majd a szerkesztők jóváhagyása után bekerülnek a termekar táblába. Abban az esetben, ha a rendszer egy már importált termék esetén ár vagy egyéb változást talál, úgy annak a terméknek az adatait a legfrissebb export fájl szerint aktualizálja. Amennyiben az automatikus import során nem érkezik egy korábban bepárosított termékkel kapcsolatos adat, úgy a rendszer az adott termékek közül törli az Ügyfél ajánlatát, mivel ha egy termékről nem szerepel információ az export fájlban, az azt jelenti, hogy az Ügyfél megszüntette annak forgalmazását. Megjelenítés A termékek keresés eredményeként, vagy a kategóriák tallózásának eredményeként egy változtatható hosszúságú listában jelennek meg. Egy sorban egyetlen termék szerepel a következő adatokkal: a forgalmazó bolt logoja és értékelése, raktár információ, átvétel módja, bruttó ár, fizetési lehetőségek, a bruttó ár megnövelve a szállítás költségével, a leírás, valamint egy Megnézem a boltban feliratú gomb. Az utóbbi gombra kattintva a felhasználó az Ügyfél honlapjára/webáruházába jut, ahol megtekintheti ismételten a terméket, illetve igény szerint meg is rendelheti azt.
Technikai kapcsolattartó elérhetősége A jelen dokumentummal kapcsolatos, továbbá speciális kérések vagy egyéb technikai jellegű kérdésekkel, illetve bármilyen felmerülő hibával kapcsolatosan keresse a Kirakat.hu technikai kapcsolattartóját az alábbi sorrendben a megadott elérhetőségeken: Kirakat hibabejelentő E-mail: kirakathiba@sanomamedia.hu