A sERPa <-> Webshop Experts kapcsolat az alábbiak szerint működik:
Aurora webshophoz http://www.webshopexperts.hu/aurora_webaruhaz_motor
Leírás, algoritmus
Fájl kódolása: ANSI
Adatok átadása
A sERPából a szerviz segítségével a termékadatokkal átadunk 5 txt fájlt. (A Webáruház paraméter funkció FTP részén a „Termék útvonal” mezőben megadott helyre másoljuk a txt fájlokat.) Ezt figyeli a Webshop Experts webáruház és ha megjelenik ott a fájl, akkor beteszi a tartalmát a webáruház adatbázisának termékadataiba.
1. Termek.txt
Oszlopok: TermekKod, TermekNev, MennyisegiEgyseg, TermekLastModify, TermekKepLastModify, Kepnev, Vonalkod, VamtarifaKod, Hasznalhato, TermekFelvDatum, RovidLeiras, TermekFaID, Leiras)
Termék alapadatai adjuk át valamint a termékfa levél helyét, ha több helyre be van sorolva akkor vesszővel elválasztva.
Termékhez nem kötelező kép megléte, hogy átadásra kerüljön.
Termékleírás: magyar nyelvű, html tagekkel. (pl:. <body><p>Zold vonat!</p></body>)
A Hasznalhato mezőbe a Terméktörzsben lévő Használható eladáskor mező értéke kerül.
2. TermekFa.txt
Oszlopok: SzuloID, ID, LevelNev, LevelLeiras
sERPa termékfa kerül átadásra a webáruház menüszerkezet felépítéséhez (alapértelmezetten a rövid leírás, de ha van leírás akkor leírás).
3. TermekAr.txt
Oszlopok: TermekKod, Afakulcs, Ar, AkciosAr
Termékhez ára (paraméterben beállított ártábla) valamint a hozzá tartózó áfakulcs, és ha a termékhez van felvéve akciós ár ami érvényes és megfelel a paraméterben a További adatok fülön lévő akciós ár szűrésnek és paraméterben be van állítva akkor ez az ár is átadásra kerül.
4.TermekKeszlet.txt
Oszlopok: TermekKod, Keszlet
Termék aktuális készletadata. Azé a raktáré, amelyik a webáruház paraméter funkcióban meg van adva.
5. TermekKategoria.txt
Oszlopok: TermekKod, ...,...
a) Termék és a hozzá tartozó egyedi termékbesorolások, az oszlop fejélce a kategórianév és a sorokban a termék ebbe a kategóriában besorolt tétel neve, ha van leírás akkor az.
Fontos, hogy a termékbesorolás egyedisége be legyen állítva a termékkategória törzsben. Változó oszlophosszúságú! (új kategória beállítás esetén a webshop admin felületén is beállítás is szükséges.)
b) Egyedi ártáblák adatai, külön oszlopokba.
c) Kapcsolódó termék egy oszlop, ha több van, akkor felsorolva, azaz vesszővel elválasztva.
d) Ha a termékhez több kép van hozzárendelve, amelyre igaz a weben való megjelenítési feltétel (Honlap nagy=Igaz), akkor az is egy új oszlopba jelenik meg, ha több van, akkor veszővel elválasztva.
Adatok átvétele: VEVŐ RENDELÉS
A sERPa webáruház szolgáltatása a webáruház paraméter funkció „Rendelés letöltés URL” mezőjében megadott távoli helyről (Webshop Experts webáruházból) GET hívással lekérdezi a rendelést tartalmazó fájlt. (ez egy xml fálj, amit a kinti webáruházban lévő szamla.php generál. Név és jelszó szükséges az eléréshez, amit a paraméterben kell beállítani). Ebben az esetben az URL kiegészül a &last_orderhead_timestamp=[idő]
Vagy a távoli webáruház POST-olja a rendelést tartalmazó xml-t a sERPa webáruház címére és portjára.
A sERPa szolgáltatása ezt az adatrészt figyeli az URL címben:
?ordercontent=<ORDE...
A XML-ben nem szereplő mezők kezdő értéke, a paraméterből jön:
Fejléc: Fizetési mód típus, Ár típus, Érvényesség, Szállítás, Kötbér, Kötbérszázalék, Kötbérösszeg, Megjegyzés nyomtatás
Tétel: Raktár, Cél raktár, Foglalás rendelésből, Diszponálás beérkezéskor
Az xml-ben vannak a Webáruházban azonosított ügyfél adatai is.
Egy ilyen hívás esetén a URL: http://ceg.hu/cron/szamla.php
Több webáruház és egy adatbázis használata esetén az ?ordercontent elé és a port szám közé lehet írni a „paraméter” (azonosított) amit a Letöltés URL kell megadni:
http://localhost:17890/normalshop?ordercontent=<ORDERS>....</ORDERS>
http://localhost:17890/vipshop?ordercontent=<ORDERS>....</ORDERS>
Egyéb tudnivalók:
Ha az ügyfél megváltoztatta a címét két rendelés között akkor új ügyfélként kerül felvételre, hogy a régi címe ne vesszen el.
Ha a termék, „ship” kóddal kezdődik (productcode like 'ship%') [2017.05.24 előtt "ship_" volt de a WebshopExport már nem használja a "_" jelet ], akkor annak az összege a fuvar költség, és ha az nem 0, akkor Fuvar=Vevő, egyébként „szállító fix összegért”
Ha nincs megadva adószám akkor új ügyfél esetén a ügyfél típusa=Magánszemélyként kerül felvételre. (80-as verziótól)
A kontírszámok (költséghely, témaszám, pozíciószám), a foglalási, illetve a diszponálás beérkezéskor értékek a rendelés sorozatának paraméteréből kerülnek beállításra a fogadott rendelésen.
XML Minta
<ORDERS> |
|
<ORDER> |
|
<ORDERHEAD_CODE>1001</ORDERHEAD_CODE> |
;Rendelés azonosító, (Max. 21 számjegy kerülhet a HivSzámba a prefix után) |
<ORDERHEAD_TIMESTAMP>1187694817</ORDERHEAD_TIMESTAMP> |
|
<ORDERHEAD_PARTNER_CODE>69</ORDERHEAD_PARTNER_CODE> |
;Kötelező |
<ORDERHEAD_PARTNER_NAME>Teszt Géza</ORDERHEAD_PARTNER_NAME> |
|
<ORDERHEAD_PARTNER_VATNUMBER>12345678-1-12</ORDERHEAD_PARTNER_VATNUMBER> |
; (3) pont. Nem kötelező |
<ORDERHEAD_PARTNER_ZIP>2000</ORDERHEAD_PARTNER_ZIP> |
|
<ORDERHEAD_PARTNER_CITY>Szentendre</ORDERHEAD_PARTNER_CITY> |
|
<ORDERHEAD_PARTNER_ADDRESS>Kis Lajos utca 12.</ORDERHEAD_PARTNER_ADDRESS> |
|
<ORDERHEAD_PARTNER_COUNTRY>HUN</ORDERHEAD_PARTNER_COUNTRY> |
; (13) pont. |
<ORDERHEAD_PARTNER_GROUP_ITEM>Ügyfélkategória tétel</ORDERHEAD_PARTNER_GROUP_ITEM> |
; (15) pont. |
<ORDERHEAD_PAYMENTMETHOD_NAME>Átutalás</ORDERHEAD_PAYMENTMETHOD_NAME> |
;Fizetési mód név, ha nincs akkor megjegyzésbe kerül. |
<ORDERHEAD_DATE_SHIPPED>2016-12-24</ORDERHEAD_DATE_SHIPPED> |
;Kötelező, az itt megadott szállítási dátumot a vevő rendelés, kért szállítási határidő mezőben kerül. |
<ORDERHEAD_DATE_PAYMENT_DUE>2016-12-13</ORDERHEAD_DATE_PAYMENT_DUE> |
|
<ORDERHEAD_SUBJECT>Internetes vásárlás</ORDERHEAD_SUBJECT> |
|
<ORDERHEAD_EMAIL>teszt.geza@geza.com</ORDERHEAD_EMAIL> |
|
<ORDERHEAD_PHONE_1>+36-26-717-821</ORDERHEAD_PHONE_1> |
|
<ORDERHEAD_COMMENT /> |
;Fejléc megjegyzésbe kerül, max 2000 karakter. (nem létező fiz. mód elé.) |
<ORDERHEAD_STOCKCODE>KR</ORDERHEAD_STOCKCODE> |
;(1) pont. |
<ORDERHEAD_CURRENCY>HUF </ORDERHEAD_CURRENCY> |
;Nem kell megadni, csak ha el akarunk térni a forinttól (HUF) |
<ORDERITEM> |
;Több tétel esetén duplikálható tartalom |
<ORDERITEM_STAT_NO>W-OM01</ORDERITEM_STAT_NO> |
;Kötelező, ez a termékkód |
<ORDERITEM_NAME>termeknév 1</ORDERITEM_NAME> |
|
<ORDERITEM_UNIT>db</ORDERITEM_UNIT> |
|
<ORDERITEM_QTY>1</ORDERITEM_QTY> |
;Kötelező |
<ORDERITEM_PRICE>6248.00000</ORDERITEM_PRICE> |
;Kötelező |
<ORDERITEM_discountPercentage>5</ORDERITEM_discountPercentage> |
; (6) pont. |
<ORDERITEM_discountNet>120</ORDERITEM_discountNet> |
; (6) pont. |
<ORDERITEM_COMMENT /> |
|
</ORDERITEM> |
|
</ORDER> |
|
</ORDERS> |
Általunk nem használt egyéb mezők a fejlécben |
<ORDERHEAD_VERIFIED>1</ORDERHEAD_VERIFIED> |
<ORDERHEAD_PAYMENTMETHOD_CODE>18</ORDERHEAD_PAYMENTMETHOD_CODE> |
<ORDERITEM_PRODUCT_CODE>121</ORDERITEM_PRODUCT_CODE> |
<ORDERHEAD_PARTNER_OTHER_DATA /> |
<ORDERITEM_CODE>40</ORDERITEM_CODE> |
<ORDERHEAD_PHONE_2>+36-70-4056700</ORDERHEAD_PHONE_2> |
|
Általunk nem használt egyéb mezők a tételeknél |
<ORDERITEM_VAT_CODE>1</ORDERITEM_VAT_CODE> |
<ORDERITEM_VAT_PERCENT>20</ORDERITEM_VAT_PERCENT> |
<ORDERITEM_VAT_NAME>20 %</ORDERITEM_VAT_NAME> |
További fejlesztések az eredeti xml-hez
1. Az XML fejlécben megadható, hogy mely raktárra érkezzen be a rendelés, függetlenül a paraméterben rögzített értéktől.
<ORDER>
<ORDERHEAD_STOCKCODE>KR</ORDERHEAD_STOCKCODE>
</ORDER>
2. Szintén a fejlécben megadható, hogy ne új ügyfél legyen létrehozva, hanem új telephelyként(Telephely kódnak egy 10 karakteres random kódot generálunk) kerüljön beimportálásra egy új szállítási cím.
(telephelynév, irányítószám, helység, és utca házszám, ország adatok megadásával.)
<ORDER>
<ORDERHEAD_SHIPPING_PARTNER_NAME>Szegedi Telephely</ORDERHEAD_SHIPPING_PARTNER_NAME>
<ORDERHEAD_SHIPPING_PARTNER_ZIP>6700</ORDERHEAD_SHIPPING_PARTNER_ZIP>
<ORDERHEAD_SHIPPING_PARTNER_CITY>Szeged</ORDERHEAD_SHIPPING_PARTNER_CITY>
<ORDERHEAD_SHIPPING_PARTNER_ADDRESS>Kis Park körút.</ORDERHEAD_SHIPPING_PARTNER_ADDRESS>
<ORDERHEAD_SHIPPING_PARTNER_COUNTRY>HUN</ORDERHEAD_SHIPPING_PARTNER_COUNTRY>
</ORDER>
3. Ha adószám alapján megtalálható az ügyfél, tehát megadásra került egy érvényes <ORDERHEAD_PARTNER_VATNUMBER>, akkor nem figyeljük a címváltozást, és nem veszünk fel új ügyfelet.
Automatikusan az ügyféltörzsből beazonosított partner kerül a rendelésbe. Ha ennél az ügyfél nincs felvéve még webes idegenazonosító, akkor felvesszük.(ez általában olyankor fordulhat elő, ha eddig csak személyesen vásárolt, megvan az ügyféltörzsben idegenazonosító nélkül, majd leadja első rendelését a webáruházból.)
4. Webshopból jövő rendelés esetén is kitöltésre kerül a rendelés fejlécén található további adat táblázat, ha az kézi felvételnél egyébként kitöltésre kerülne.
5. Megadható az ügynök kódja és a szállítás módjának értéke (Egész=0 Teljes tétel=1 Tételrész=2). Ha nincs megadva ügynök a rendelés sorozatának paraméterből kerül litöltésre.
<ORDER>
<ORDERHEAD_Agent>007</ORDERHEAD_Agent> (akkor jut érvényre, ha az ügynöknél a sERPa-ban használható pipa igaz értékre van állítva)
<ORDERHEAD_ShippingMethod>0</ORDERHEAD_ShippingMethod>
</ORDER>
6. Az engedmény a teljes tétel nettó összegére vonatkozik egy terméken belül.
SZÁMÍTÁSÁNAK MÓDJA:
<ORDERITEM_PRICE> * <ORDERITEM_QTY>
= ENGEDMÉNY ALAPJA
* <ORDERITEM_discountPercentage>
- <ORDERITEM_discountNet>
= ENGEDMÉNY VÉGLEGES ÉRTÉKE
7. A fizetési határidőt az Ügyféltörzsben található fizetési feltételnél meghatározott értékekkel vesszük fel a vevőrendelésbe, akkor ha a beazonosított ügyfélnél név szerint azonos fizetési mód van rögzítve, mint ami a fogadott rendelésben szerepel.
8. Minden ügyfélnek megadható most már a hosszú neve. Továbbá a szállítási címhez telefonszámot lehet hozzárendelni . (Ügyféltörzs/Telephely/Elérhetőség -> Hivatali telefon)
<ORDER>
<ORDERHEAD_PARTNER_COMPANY>Hosszű nevéven szereplő Nyrt.</ORDERHEAD_PARTNER_COMPANY>
<ORDERHEAD_SHIPPING_PARTNER_PHONE>0</ORDERHEAD_SHIPPING_PARTNER_PHONE>
</ORDER>
9. Az XML-ben a fejlécben beállítható, hogy a beérkező rendelés mely vevőrendelés sorozatra kerüljön felvételre. (Ha olyan sorozat van megadva, ami a rendelés paraméterben nem létezik, akkor nem készül vevőrendelés).
<ORDER>
<ORDERHEAD_Series>VR0</ORDERHEAD_Series>
</ORDER>
10. A webáruház paraméterben beállítottak szerint történik a felvett rendelés diszponálása, ha a <ORDERHEAD_Reservation> értéke 0 vagy üres. Minden más érték esetén kényszeríthető az automatikus diszponálás, függetlenül a paraméter beállításától.
<ORDER>
<ORDERHEAD_Reservation>0</ORDERHEAD_Reservation>
</ORDER>
11. Ha az XML fejlécben található fuvar és fuvar díj, akkor azok rákerülnek a rendelésre:
Ha nem található a megadott fuvardíj a rendszerben, akkor új néven felvételre kerül. Fuvar díj elhagyása esetén annak alapértelmezett értéke = 0.
<ORDER>
<ORDERHEAD_delivery_method>Szállító fix összegért</ORDERHEAD_delivery_method>
<ORDERHEAD_gross_deliveryFee>0</ORDERHEAD_gross_deliveryFee>
</ORDER>
Amennyiben a webshopból kapott fuvardíjat felül akarjuk bírálni, akkor használjuk a pipát, de ha azt akarjuk, hogy a webshopból érkező adat legyen az erősebb akkor ennek a pipát, nemre kell állítani, hasonlóan a Ártípus = Rögzített esetén, amikor azt az árat akarjuk látni a rendelésen ami a webshopból érkezik.
12. A következő változások történtek, hogy a shopRenter rendelés XML is be lehessen importálni:
- Ha az <ORDERITEM_STAT_NO> nincs megadva, akkor a <ORDERITEM_PART_NO> tagbe figyeljük a termék kódját.
- Ha az adatok CDATA résszel kerülnek átadásra, ezt is átkonvertáljuk és kezeljük.
- A timestamp-t nem csak unixos formátumba fogadjuk el, hanem dátum típussal. (pl. 2016-05-25 21:16:31)
- <!DOCTYPE ORDERS> rész figyelmen kívül hagyása, mert ott nincs érdemi adat. Nem okoz hibát.
13.
<ORDERHEAD_PARTNER_COUNTRY>: Vevő ország kód (Orszag.KodAlpha3)
<ORDERHEAD_SHIPPING_PARTNER_COUNTRY> Vevő telephely ország kód (Orszag.KodAlpha3)
Ha a vevő országkód nem Magyarország, akkor:
- az <ORDERHEAD_PARTNER_VATNUMBER> -ben megadott adatok a vevő EUAdószám mezőbe kerülnek,
- új ügyfél felvételnél csak a Külföldi vevő mező kerül pipálásra.
Külföldi vevőrendelés esetén (NEM a telephely - azaz a szállítási cím - számít, hanem a vevő) Export relációjú vevőrendelést veszünk fel (a sorozathoz a paraméterben megadott Belföldi/Export beállítások figyelmen kívül hagyásával)
14.
A rendelés generálásakor az
- ügynök ***,
- foglalás rendelésből
- diszponálás beérkezéskor
- ajánlott költséghely, témaszám, pozíciószám (használható forgalomban, illetve használható pipák igaz értéken kell álljanak)
mezők kitöltésre kerülnek a rendelés paraméterben a sorozathoz beállított értékek szerint.
*** Ha az <ORDERHEAD_Agent> át van adva, akkor onnan kerül az ügynök a rendelésbe.
Ha nincs átadva és a paraméterben az
- ügynök ajánlás = Ügyféltörzs, akkor az ügyféltörzsben beállított
- ügynök ajánlás = Paraméter, akkor az ott megadott
- ügynök ajánlás = Felhasználó, akkor a webáruház által generált rendelés felvevő felhasználóban megadott személy, ha egyben ügynök is.(ilyen általában nincs megadva, ezért nem javasolt beállítani.)
Ha a felsorolt helyeken nem szerepel ügynök, akkor nem kerül kitöltésre a mező. Az ügynök kitöltésnél feltétel az is, hogy az ügynöknél a használható pipa igazra legyen állítva.
A webáruház paraméterben megadható egy ügyfél kategória. Ennek a kategóriának a tétel kódját várjuk a rendelés XML <ORDERHEAD_PARTNER_GROUP_ITEM> Tagben megadva.
Ha ez létezik(megegyezik) akkor az ügyfél besorolásra kerül.
Ha nem található, de van olyan kategória tétel amelyre igaz a kezdőérték akkor felvételre kerül az.
Ha a fenti két eset sem teljesül, akkor az Ügyfél nem kerül besorolásra.
Amennyiben sERPa-ban az adott ügyfél már be van sorolva, akkor azt felülírjuk, szabály, hogy a webről érkező mindig erősebb.
