Leírás
Új webshop rendelés adatok információit tartalmazza az XML.
Algoritmus
Az XML-ben beérkező értékek alapján a Webáruház paraméter és vevőrendelés sorozat szerint veszünk fel vevőrendelést.
Alapvető szabályok
•A sERPában felvett rendelésről akkor megy felvétel (insert) üzenet a webáruház felé, ha a rendelést felvevő felhasználó különbözik a Webáruház paraméter / További adatok fülén található Felvevő felhasználó mezőben megadottól (tehát nem a webáruháztól érkezett).
•A felvett rendelésekben az Összevonható vevőszámla mező értéke fixen 0.
•A felvett rendelésbe a saját ügyintéző a paraméter alapján kerül kitöltésre.
•A webáruház paraméterben megadott további adaton kívül felvételre kerül a rendelésre a sorozathoz a rendelésnyilvántartás paraméterben megadott összes további adat is.
•A sorozatban beállított szabályok teljesülnek az importált rendelésre is, azaz: Szállítás, Visszaigazolás, Diszpontás, Ártípus, Érvényesség, Kötbér, Kötbér összege, Aláírok, Fizetési mód típus, Összevonható vevő számla bevitel, Összevonható komissió utasítás bevitel.
Ügyfél kezelése, rögzítése
Beállítási lehetőség a Webáruház paraméterben: Ügynök generálása regisztrált vásárló esetén
Nem esetén a rendelés rögzítésekor nem veszünk fel új ügyfelet ügynökként és nem kapcsoljuk azt a rendelés ügyfeléhez.
Ha megtaláljuk az ügyfelet, azt használjuk, ha nem, akkor normál szabályok szerint veszünk fel ügyfelet. A "bill" szakasz adatai az ügyfél székhely adatai (fejléc) lesznek, a "postal" szakasz pedig telephely lesz.
Igen esetén:
A webáruház a regisztrációhoz csak név, e-mail és telefonszám adatot tárol, amiket a <customer> szakaszban ad át a sERPa-nak. Az áruházban lehetőség van regisztráció nélküli vásárlásra is (vendég vásárló) ekkor a <customer_webshop_code> nem kerül be az xml-be, de a rendelés leadásakor megadott e-mail és telefonszám szintén ebben a szakaszban kerül átadásra. A számlázási és szállítási adatok mindig a <bill> szakaszba kerülnek.
A <customer> szakaszban soha nincs cím adat, a <bill> szakaszban soha nincs elérhetőség adat.
A webáruház a regisztrációs adatokhoz és regisztrált felhasználók által megadott számlázási adatokhoz egyedi azonosítókat rendel (<customer_webshop_code> , <bill_webshop_code>) melyeket a sERPa a webáruház paraméterben megadott idegenazonosító típus szerint az ügyféltörzsben rögzít. (Regisztrált ügyfél idegenazonosító, Számla ügyfél idegenazonosító)
A customer szakaszban lévő ügyfél mindig magánszemélyként kerül felvételre, míg a bill szakaszban a company mező értéke határozza meg, hogy magánszemély, vagy cégként vesszük fel.
Amennyiben a customer és a bill szakasz vevője megegyezik és ezért egy ügyfelet vennénk fel, akkor a bill szakasz határozza meghogy cég, vagy magánszemély lesz-e.
sERPa ügyfél kezelésének szabályai:
Vendég vásárló esetén (azaz, ha <customer_webshop_code> nincs megadva) a <bill> / <name>, <zip>, <city>, <street> mezők alapján megnézzük, hogy az ügyfél megtalálható-e a sERPa-ban.
- Ha nem találjuk az ügyfelet, akkor idegenazonosító nélkül felvételre kerül a <customer> és <bill> szakaszokban megadott adatokkal. Ha a <bill> szakaszban szállítási cím is van megadva (<bill> / <postal_ xxx>) akkor felvételre kerül az ügyfélhez ezzel a címmel egy telephely (Telephely kódnak egy 10 karakteres random kódot generálunk) is és ez a telephely bekerül a rendelésbe is. Az ügyfél név a <bill> / <name> értéke lesz.
- Ha minden mező értéke karakterre azonosan megvan, akkor az így megtalált ügyfélre vesszük fel a rendelést, az ügyfélben pedig vizsgálat nélkül felülírásra kerülnek az elérhetőség adatok a <customer> / <phone> , <e-mail> mezők tartalma szerint. (ezt akkor is megtesszük, ha esetleg az így megtalált ügyfélnek van regisztrációs azonosítója, azaz úgy adott le rendelést a vevő, hogy elfelejtett bejelentkezni és ezért nem érkezik hozzá regisztrációs azonosító)
Ha a <bill> szakaszban szállítási cím is van megadva (<bill> / <postal_ xxx>) akkor megvizsgáljuk, hogy ezek karakterre azonosan megvannak-e.
Ha megtaláljuk, akkor a meglévő telephely bekerül a rendelésbe
Ha nem találjuk, akkor új telephely kerül felvételre az ügyfélhez ezzel a címmel és ez a telephely kerül a rendelésbe.
Vendég vásárlótól származó rendelésbe nem kerül kitöltésre az ügynök mező.
Ha <customer_webshop_code> nincs megadva, akkor <bill_webshop_code> sem érkezhet. (nem regisztrált vásárolóhoz a weben nem kerülnek mentésre a számlázási adatok)
Regisztrált vásárló esetén (azaz, ha <customer_webshop_code> meg van adva) akkor Regisztrált ügyfél idegenazonosító alapján keressük az ügyfelet a sERPa-ban.
- Ha nem találjuk meg, akkor felvesszük az ügyfelet a<customer_webshop_code> -ban megadott Regisztrált ügyfél idegenazonosítóval, majd ebből az ügyfélből generálunk egy ügyfél típusú ügynököt is és ez az ügynök kerül a rendelésbe. Ebből tudjuk a jövőben, hogy mely vevőrendelést mely regisztrált ügyfélnek köszönhetjük.
Ha történik regisztrációs azonosítóval új ügyfél felvétel (azaz ha új regisztrációval érkezik rendelés) akkor
Ha a <bill> / <name> mező karakterre egyezik a <customer> / <name> mezővel, úgy nem veszünk fel új ügyfelet, hanem az előzőekben felvett ügyfélre kerül felvételre a rendelés és ebbe az ügyfélbe bekerülnek a <bill> tagban megadott számlázási cím és adószám* adatok is. (<zip> , <city> , <street> , <taxnumber>) valamint a <bill_webshop_code> -ban megadott számlázási idegenazonosító is. Ennek az ügyfélnek tehát két idegenazonosítója is lesz, egy regisztrációs és egy számlázási. Ebből az a következtetés vonható le, hogy az adott ügyfél vásárolt már a saját nevére is. Egyéb jelentősége nincs, de a weben meglévő azonosítók mindegyikét célszerű látni a sERPa-ban is.
Ha a <bill> / <name> mező karakterre NEM egyezik a <customer> / <name> mezővel, akkor új ügyfelet veszünk fel a <bill> -ben megadott adatokkal. Ebben az ügyfélben elérhetőség adatok nem fognak szerepelni.
(a cím adatok pedig csak ebben az ügyfélben szerepelnek, a regisztráció alapján létrehozott ügyfélbe nem kerülnek bele a számlázási ügyfél cím adatok, hiszen a két név eltér)
Ha szállítási cím is van megadva, akkor telephelyként felvételre kerül ehhez a számlázási ügyfélhez és ez a telephely bekerül a rendelésbe.
Ha NEM!! történik regisztrációs azonosítóval új ügyfél felvétel (azaz egy már korábban regisztrált és rendelést leadott felhasználó ad le új rendelést), akkor név egyezés vizsgálat helyett megnézzük a bill webshop kódot és
ha létezik, akkor erre az ügyfélre vesszük fel a rendelést, valamint felülírjuk az ebben az ügyfélben tárolt adatokat (név, cím, adószám és ha a regisztrációs és számlázási azonosító is egy ügyfélben van, akkor az elérhetőség adatokat is) a most érkezett adatokkal,
ha nem létezik még a számlázási azonosító, akkor új ügyfelet veszünk fel a most érkezett név és cím adatokkal és ez az ügyfél kerül a rendelésbe.
*taxnumber: Ha nem magyar adószáma (a hossza eltér a 11 karakterszámtól), ebben az esetben a KulfoldiAdoszam mezőbe kerül az adat.
Olyan eset nem fordulhat elő, hogy a Regisztrált idegenazonosító alapján nem találjuk az ügyfelet (új regisztráció, új ügyfél) de a számlázási idegenazonosító létezik a sERPa-ban. A web nem rendelhet létező számlázási idegenazonosítót új regisztrációhoz. Ebben az esetben a rendelésfelvételt a sERPa elutasítja.
- Ha megtaláljuk a <customer_webshop_code> alapján az ügyfelet a sERPa-ban, akkor a rendelés ügynöke a már korábban ebből az ügyfélből legenerált ügynök lesz. Az ügyfél név, e-mail, telefonszám frissítésre kerül a sERPa-ban.
Ha a <bill_webshop_code> alapján megtaláljuk az ügyfelet, akkor ezzel az ügyféllel kerül felvételre a rendelés.
Ha szállítási cím is van megadva és ezt a szállítási címet karakterre pontosan megtaláljuk a sERPa-ban a számlázási ügyfélnél, akkor ez a telephely kerül be a rendelésbe.
Ha szállítási cím is van megadva és ezt a szállítási címet NEM találjuk meg, akkor felveszünk a megadott adatokkal egy telephelyet és ez az új telephely kerül a rendelésbe.
Ha a <bill_webshop_code> alapján NEM találjuk az ügyfelet, akkor ezzel az idegenazonosítóval új ügyfelet veszünk fel és ezzel az ügyféllel kerül felvételre a rendelés.
Ha szállítási cím is van megadva, akkor felveszünk a megadott adatokkal egy telephelyet is ehhez az ügyfélhez és ez a telephely kerül a rendelésbe.
Minden felvett ügyfél besorolásra kerül a paraméterben megadott ügyfélkategóriába, azon belül abba a tételbe, ami a <customer_groups> / <customer_group> -ban meg van adva.
Ha számlázási ügyfél kerül felvételre, akkor abba bekerül ügynöknek az a regisztrált felhasználóhoz felvett ügynök, akitől a rendelés érkezett.
<bill>/<company> Ha értéke 0, akkor magánszemélyként lesz felvéve az ügyfél, ha 1, akkor cégként. Amennyiben nem adják át, a taxnumber mező megléte dönt.
Ha a bill részbe megadunk email, telefonszám adatokat akkor azt is felvesszük a számla ügyfélhez az elérhetőségnek.
..
<phone>123</phone>
<email>zoli_ugyfel@gmail.com</email>
</bill>
Prefix és ügyfélkód kiosztás változás:
Két fajta ügyfél kód tekinthető érvényesnek.
A.) Prefix + hat számjegy.
B.) Prefix + hatnál több számjegy, ahol az első számjegy nem lehet 0.
Ha találunk ilyen ügyfél kódokat, akkor ügyfél felvételnél az új kódok ezen számok alapján fognak sorban növekedni.
1. eset nincs még érvényes kóddal rendelkező ügyfél a rendszerben. Ilyenkor az új ügyfél kódja = Prefix + Sorszám előnullázva 6 karakterre. pl TEST000001
2. eset már van érvényes kóddal rendelkező ügyfél és a számjegyek 6 karakteret foglalnak pl. TEST000020 -> Ilyenkor az új ügyfél folytatólagosan TEST000021 lesz és így tovább.
3. eset már van érvényes kóddal rendelkező ügyfél és a számjegyek 6 karakternél nagyobbak. Itt fontos, hogy a számsor nem kezdődhet 0-val.
Tehát ez érvényes: TEST1000000001 és így folytatódik: TEST1000000002.
Ez nem érvényes: TEST0000000001, nem vesszük figyelembe. Ez sem érvényes: TEST0000010000
Csoportos fizetési feltétel frissítése az ügyfélnél
Csoportos fizetési feltétel is érkezhet az xmlben, ekkor a név alapján felülírjuk a kérdéses Ügyfélnél ezt az adatot.
a sERPa-ban név ellenőrzés történik, annak kell megegyeznie a Webshopban és a sERPa-ban, ezt a két rendszerben kézzel kell fenntartani!! Amennyiben olyan fizetési feltétellel érkezik rendelés, amely nem szerepel a sERPa-ban hibára fut és a rendelés nem kerül felvételre
pl:
<serpa>
<head>
<type>order</type>
<time>2020-09-21T16:07:24.177</time>
</head>
<response>
<type>order</type>
<order_code>555556</order_code>
<ok>0</ok>
<errors>
<error>Érvénytelen csoportos fizetési feltétel!</error>
</errors>
</response>
</serpa>
Amennyiben a Rendeles.xml-ben van <agent>...</agent>, akkor az xml feldolgozása után megvizsgáljuk, hogy létezik-e ilyen kódú Ügynök (az agentben Ügynök kódot kell átadni), ha igen, akkor a rendelésbe az kerül bele, nem pedig a customer_webshop_code alapján létrejött ügyfél ügynök.
Az agent-ben átadott Ügynök ha nem találjuk meg, akkor a mező üresen marad, Ezt kézzel kell korrigálni.
A country_code, postal_country_code mezők átadása nem kötelező, ha nem tartalmazza az xml, vagy üres, akkor HU-ként értelmezzük és az ügyfél magyarországi, belföldi vevő lesz.
A rendelés megjegyzésbe került rendelés felvételkor: customer_comment + delivery_id + payment_id
EU adószám kezelése:
Az érintett rendelés xml-be bekerült egy új eu-adoszám tag (eu_vat_number / bill_eu_vat_number ), amelyet akkor tudunk használni, hogy ha nem magyar adószámot szeretnénk fogadni a weboldaltól.
A felvett rendelésen a tételekben a kért és az ajánlott szállítási határidő paraméterezhető. Ha a webáruházunkhoz nem állítunk be szabályt, akkor az alábbi alapértelmezett értékeket használjuk:
•Kért szállítási határidő: rendelés felvétel napja.
•Ajánlott szállítási határidő: rendelés felvétel napja
Ha ezt szeretnénk megváltoztatni, az alábbi lépéseket kell megtennünk.
A szállítási határidők kiinduló értékei legtöbbször attól függnek, hogy a rendelést milyen módon fogjuk kiszolgálni. Ha a vásárló bejön érte a boltba személyesen átvenni, akár már aznap szeretnénk kiszolgálni, ha van raktáron a termék. Ha saját magunk szállítjuk, 2 nap lehet, ha futárszolgálattal szállítjuk majd, akár 3 nappal is kalkulálhatunk. Épp ezért a határidő eltolás értékét fuvardíj kategória tételenként lehet testre szabni.
1.Például készítünk egy Fuvardíj kategóriát "Szállítási határidő eltolás" néven. Állítsuk egyedi típusúra, hogy egy tételt csak egyszer lehessen majd használni.
2.Felveszünk három fuvardíj kategória tételt hozzá: bolti átvét, saját szállítás, futárszolgálat.
3.A Webáruház paraméterben az adott webáruháznál a További adatok fülön a Szállítási határidő eltolás fuvardíj kategória mezőben megadjuk a "Szállítási határidő eltolás" fuvardíj kategóriát.
4.Az alatta megjelenő Szállítási határidő eltolás táblázatban pedig felvesszük az előbb létrehozott 3 fuvardíj kategória tételt és megadjuk hozzájuk a nap eltolásokat. A bolti átvét tételhez 0 napot mindkét határidő típushoz, a saját szállítás tételhez 2-2 napot, a futárszolgálat tétel mellé pedig 3-3 napot írunk.
5.Végül a Fuvardíj paraméterben az általunk használt fuvardíjakat besoroljuk az új kategória három tételével. Például a személyes átvételhez felvesszük a "bolti átvét" tételt, a saját házhoz szállítás paraméterhez a "saját szállítás", az összes futárszolgálat paraméterhez (GLS, MPL, PPP stb.) pedig a "futárszolgálat" kategória tételt.
6.Így ha a webáruházból beérkezik egy rendelés, amelyhez a GLS futárszolgálat paraméter fog tartozni, annál a rendelésnél a kért és az ajánlott szállítási határidő 3 nappal a rendelés rögzítése utáni lesz. Viszont ha a vevő személyes átvételt kért, akkor a rendelés tételein a kért és az ajánlott szállítási határidő a rendelés rögzítésével azonos nap lesz.
Áfa ajánlás
A termék áfáját nem az XML-ből vesszük át, hanem feldolgozás során lefut a sERPában levő besorolási szám szerinti ajánlás a termékre a bruttó ár szerint.(BesorolasiSzamAfaAjanlas)
1. A webáruház paraméter További adatok lapfülén található egy Utánvét szolgáltatás táblázat, itt a fizetési módot és egy utánvétel szolgáltatást kell kiválasztani.
a.) Ha még nem szerepel ehhez külön fizetési mód a programban, akkor a Fizetési módok funkcióban kell létrehozni egyet. (Pl. Utánvétel néven.)
b.) A Termék funkcióban fel kell venni egy szolgáltatást, bruttó lista árral és pl. Utánvétel elnevezéssel.
Ha a leírtak alapján töltjük az Utánvétel szolgáltatás nevű táblázatot, akkor rendelés rögzítésekor az utánvétel költség (payment_cost_gross) külön szolgáltatásként jelenik meg és nem számolódik be a fuvardíjba. Tehát ha a táblázatban nincs termék felvéve, akkor a payment_cost_gross értékét a fuvardíjhoz (delivery_cost_gross) hozzáadjuk és a felvett vevőrendelés FuvarOsszeg nevű mezőjébe kerülnek nettó összegként (az alapértelmezett áfa kulccsal visszaosztva).
XML-ből az azonosítás payment_id-vel történik:
<payment>
<payment_id>0</payment_id>
<payment_name>Utánvét</payment_name>
<payment_cost_net>0</payment_cost_net> ; nem használjuk
<payment_cost_gross>0</payment_cost_gross>
Fizetési mód és szállítási cím módosíthatósága:
A sERPa vevő rendelésen a Fizetési mód, szállítási cím, Hivatali telefonszám, Hivatali e-mail cím utólagos módosítási lehetősége weboldalról indítva. Új xml tag került bevezetésre <order_update>1</order_update>. A módosításhoz az order_code-ot és a bill_webshop_code-ot is meg kell adni az xml-ben.
Szállítási cím módosításakor egy új telephely kerül felvételre az ügyfélhez a sERPa-ban.
Példa módosító xml-re.:
<serpa>
<head>
<token>x</token>
<type>order</type>
<time>2022-01-05-12-05-08</time>
</head>
<content>
<order>
<order_update>1</order_update>
<order_code>8000000</order_code>
<bill>
<bill_webshop_code>BB99</bill_webshop_code>
<postal_name>Tóth Barnabás</postal_name>
<postal_zip>1181</postal_zip>
<postal_city>Budapest</postal_city>
<postal_street>Valami utca</postal_street>
<postal_country_code>hu</postal_country_code>
</bill>
<payment>
<payment_id>14</payment_id>
<payment_cost_gross>12.7</payment_cost_gross>
</payment>
</order>
</content>
</serpa>
Minta XML
<serpa>
<head>
<token>x</token>
<type>order</type>
<time>2018-02-13-08-00-59</time>
</head>
<content>
<order>
<order_code>555555</order_code>
<order_series>MOW</order_series> ; vevőrendelés sorozat, nem kötelező megadni, de ha megadjuk és nincs akkor az hiba.
<store_code>MO</store_code> ;raktárkód, ha nincs megadva akkor a pataméterben megadott, nem kötelező megadni.
<currency>HUF</currency>
<customer>
<customer_webshop_code>regidegen1</customer_webshop_code>
<agent>Ügynök kód</agent>
<customer_payment_condition>csoportos fizetési feltétel neve</customer_payment_condition>
<name>Tóth Ottó</name>
<phone>06708090100</phone>
<email>tothotto kukac emil.hu</email>
<customer_groups>
<customer_group>vip</customer_group>
</customer_groups>
</customer>
<bill>
<bill_webshop_code>szlaidegen1</bill_webshop_code>
<name>Tóth Ottó</name>
<zip>1234</zip>
<city>Nyíregyháza</city>
<street>Nagy Sándor u. 1.</street>
<country_code>HU</country_code>
<taxnumber>12345678910</taxnumber>
<eu_vat_number>HU31338595</eu_vat_number>
<postal_name>Szállítási cím</postal_name>
<postal_zip>5555</postal_zip>
<postal_city>Budapest</postal_city>
<postal_street>Raktár u. 301.</postal_street>
<postal_country_code>HU</postal_country_code>
<company>0</company>
</bill>
<items>
<item>
<item_id>555555</item_id>
<product_code>DDF482Z</product_code>
<pc>2</pc>
<net_unit_price>10000</net_unit_price>
<gross_unit_price>12700</gross_unit_price>
<net_price>10000</net_price>
<gross_price>12700</gross_price>
<vat>27</vat>
<discount_percent>0</discount_percent>
</item>
</items>
<delivery>
<delivery_id>2</delivery_id> ; Fuvardíj ID
<delivery_point_id>106804</delivery_point_id> ; Csomagpont Azonosító mezővel történő egyezés esetén bekerül a rendelésbe az így megtalált Csomagpont
<delivery_name>Pick Pack Pont</delivery_name>
<delivery_cost_net>1000</delivery_cost_net> ; a mező nincs használva
<delivery_cost_gross>1270</delivery_cost_gross> ; bruttó fuvardíj, a rendelés FuvarOsszeg mezőjébe kerül nettó összegként, az alapértelmezett áfakulccsal visszaosztva
</delivery>
<payment>
<payment_id>8</payment_id>
<payment_name>Utánvét</payment_name>
<payment_cost_net>0</payment_cost_net> ; a mező nincs használva
<payment_cost_gross>0</payment_cost_gross> ; bruttó utánvételi díj, kezeléséről a Utánvétel kezelése részben olvashatunk
<paid>0</paid>
<bank_status>0</bank_status>
<bank_answer_code />
<trans_code />
<auth_code />
</payment>
<coupon>
<coupon_code>C1</coupon_code>
<coupon_name>Coupon1</coupon_name>
<coupon_gross>1000</coupon_gross>
<coupon_items>
<coupon_item_id>1</coupon_item_id>
<coupon_item_id>2</coupon_item_id>
</coupon_items>
</coupon>
<customer_comment>létező regisztárció, új számlázás</customer_comment>
</order>
</content>
</serpa>
Válasz XML
<response
type Fixen 'order' vagy 'offer'
order_code webes rendelés azonosító
erp_order_code sERPa rendelés azonosító
ok 0 vagy 1
<errors
error hibaleírás
errors>
response>
Lehetséges hibaüzenetek
Érvénytelen felhasználó! %1
Nincs használható Gépdepo webáruház paraméter felvéve.
Több mint 1 használható Gépdepo webáruház paraméter van felvéve.
Regisztrált ügyfél idegenazonosító típus mező nincs kitöltve a paraméterben!
A Számla ügyfél idegenazonosító típus mező nincs kitöltve a paraméterben!
A rendelés ajánlat sorozat mező nincs kitöltve a paraméterben!
A rendelés sorozat mező nincs kitöltve a paraméterben!
A kód prefix mező nincs kitöltve a paraméterben!
A tétel tulajdonság mező nincs kitöltve a paraméterben!
A Kifizetés státusz mező nincs kitöltve a paraméterben!
Nincs importálandó adat!
Az order_series-ben átadott sorozat a sERPában nem létezik!
Az adott order_code-val már van rendelés felvéve!
Érvénytelen csoportos fizetési feltétel!
Foglalt a regisztrált ügyfél idegen azonosító típus %1
Foglalt a számla ügyfél idegen azonosító típus (bill_webshop_code)
A számla ügyfél kitöltése kötelező!
