Bevezetés

Jelen dokumentum célja a Shoprenter - SMARTFRONT ERP közötti interfész felhasználói folyamatainak leírása.

Szinkron folyamatok

A SMARTFRONT ERP rendszere a Shoprenter által kínált Shoprenter API-n keresztül biztosítja az online automatikus szinkronizációt, a Shoprenter Webshop és a SMARTFRONT rendszere között. Az interfész segítségével biztosítható hogy a két rendszer között folyamatos legyen az adatáramlás az adatok manuális "átemelése" nélkül. (Az adatáramlás természetesen a Shoprenter és SMARTFRONT szerverei között történik, a felhasználó a saját munkaállomásán ebből csak annyit érzékel, hogy a megadott adatok folyamatosan frissülnek a két rendszerében)
A Shoprenter API szolgáltatást csak a Gold és Platinum szolgáltatás nyújtja, ezért fontos hogy ha a két rendszert össze akarjuk kötni akkor a Shoprenterben ezekre a csomagokra kell előfizetni.
A két rendszer az alábbi adatokat szinkronizálja:

• Partnertörzs és címek szinkronja: 2 irányú szinkron: Bármelyik rendszerben történik változás ezt a másik rendszer automatikusan átveszi.
• Terméktörzs szinkron: 1 irányú csak SMARTFRONT → Shoprenter irány
• Készlet szinkron: 1 irányú csak SMARTFRONT → Shoprenter irány
• Rendelések kezelése: Shoprenter → SMARTFRONT irány: Új webshop rendelések automatikusan átveszi az "Elküldve" és "Függőben lévő" rendeléseket, és átállítja "Feldolgozás alatt"-raSMARTFRONT → Shoprenter irány: A lezárt rendelések státuszát átállítja a megfelelő státuszúra a Shoprenterben.

Beállítások

Beállítások a Shoprenter admin felületén

Az API eléréshez Gold, Platinum szintű előfizetés szükséges, ennek megléte esetén az admin felületen a Beállítások / Integrációk / API beállítások menüpontban engedélyezni kell az API státuszát, ugyanitt van megadva az API eléréséhez szükséges url, felhasználónév és jelszó.
Az interfész jelenleg csak a magyar nyelv használatát kezeli.
A szállítási és fizetési módokat engedélyezése a Beállítások / Bolt beállítások / Fizetési módok illetve Szállítási módok menüpontban lehetséges.
Az ÁFA kulcsokat a Beállítások / Bolt beállítások / Adó osztályok menüpontban kell megadni
Új rendelés állapotokatat a Beállítások / Bolt beállítások / Rendelés állapotok menüpontban lehetséges megadni.
A termékekhez tartozó kategóriákat (Bolt / Kategóriák), képeket (Bolt / Termékek / Termék / További képek), egyedi tulajdonságokat (Beállítások / Termék beállítások / Egyedi tulajdonságok) és típusokat (Beállítások / Termék beállítások / Termék típusok) csak a Shoprenter admin felületén lehet beállítani, azokat nem szinkronizáljuk.
A Bolt / Vevők menüpontban jelennek meg a regisztrált vásárlók, illetve a szinkron folyamat által felkerült vevők, a Termékek menüpontban a termékek, a Rendelések menüpontban a webshopon leadott rendelések.

Beállítások a SMARTFRONT admin felületen

Shoprenter webshop beállítások

Első lépésként fel kell venni az admin felületen a Webshop interfész / Shoprenter webshop beállítások menüpontban egy új webshop beállítást.

A beállítandó adatok:

• Webshop neve
• API URL - API elérés linke
• API felhasználónév
• API jelszó
• Vevőcsoport: Milyen vevő csoportba kerüljön az újonnan leszinkronizált vásárló a Shoprenter → SMARTFRONT szinkron során
• Partner kategória: Milyen kategóriában kerüljön az újonnan felszinkronizált vásárló a SMARTFRONT → Shoprenter szinkron során
• Dimenzió adatok: Rendelés szinkron során milyen dimenziók értékekkel töltsük fel a rendelést
• Webshop árlista azonosító: A webshopba feltöltött termékek árai, ha egy termék nem szerepel az árlistán akkor nem lesz rendelhető a termék
• Raktár: Rendelés és készletadatok szempontjából érdekes raktár

Ebben a menüpontban lehetőség van a szinkronok direkt indítására:

• A "Kapcsolat teszt" a API kapcsolatot ellenőrzi a megadott URL-en keresztül, és a beállított felhasználónévvel és jelszóval lekérdezi a Shoprenter webshop domainjeit, és siker illetve sikertelenség esetén is bejegyzést készít az interfész log táblába.
• A "Partner szinkron email alapján" a paraméterként megadott email cím alapján próbálja Shoprenterből a SMARTFRONTBA szinkronizálni a partnert.
• A "Rendelés szinkron külső azonosító alapján" a paraméterként kapott külső azonosító alapján szinkronizálja le a rendelést.

• A "Készlet szinkron" módosítja a termékek mennyiségét, ha a termékhez tartozik mozgás.

• A "Teljes készlet szinkron" gomb minden termék mennyiségét frissíti a shoprenterben, attól függetlenül, hogy volt-e mozgatva. Ezt főleg akkor kell használni, ha újonnan hoztuk létre a webshopot és már volt készletünk.

Interfész log képernyő

A szinkron elindulásáról és lefutásáról információkat az Interfész log képernyőn találhatunk. Ez elérhető az Adminisztráció / Interfész log menüpontból, vagy direkt a Webshop beállítás "Interfész log képernyő megnyitása" gombra kattintva.
Egy szinkron folyamatról az alábbi információkat tároljuk itt:

• a szinkron folyamat indulásának ideje
• a webshop neve
• a szinkron folyamat lefutásának ideje
• a webshop neve
• sikeresen szinkronizált elemek száma
• talált hibák száma

A talált hibákról részletesebb információkat a Szinkronizációs hibák képernyőn találunk.

Szinkron hibák képernyő

A szinkron folyamatok során talált hibák részletes logja. Ez elérhető az Webshop interfész / Szinkronizációs hibák menüpontból, vagy direkt a Webshop beállítás "Szinkron hibák képernyő megnyitása" gombra kattintva.
Egy hibáról az alábbi információkat tároljuk itt:

• Webshop neve
• Szinkron modul - Partner, Rendelés, Termék, Készlet, Általános lekérdezések (nyelv, ország stb)
• Szinkron típusa - lásd Hibaüzenetek
• Hibaszint
• Kapcsolódó azonosító - SMARTFRONT beli azonosító, partner azonosító, rendelés azonosító, termék azonosító
• Kapcsolódó leírás - SMARTFRONT beli azonosító, pl partner kód, vagy rendelés bizonylatszám, termékkód
• Külső azonosító - Shoprenter beli azonosító, pl vásárló azonosító
• email cím - ha meghatározható
• REST hívás URL-je
• Hibaüzenet - részletes hiba

Hibaüzenetek prioritása

Az előforduló hibákat lehetőség szerint próbáltuk kategóriákba szorítani. Lásd Függelék Hibaüzenetek. A Webshop interfész / Hibaüzenetek prioritása menüpontban lehetőségünk van az egyes típusokhoz hibaszintet rendelni.
Például lehet, hogy a "Technikai termék nem létezik" típusú hibák alacsony prioritásúak, mert nélkülük átjönnek a rendelések, csak nem vesszük fel például a Szállítási költséget Szolgáltatás típus rendelés tételként.
Ellenben a többszörös termék kód, más külső azonosítóval hiba kritikus, mert termékkód alapján nem tudjuk azonosítani a terméket.
A nem kategorizált szinkron hibák az összefoglaló "REQUEST_ERROR" - "Rest API hiba" kategóriába kerülnek. Ekkor, ha nincs más információ, az API hívás URL-je lehet támpont a hibakeresésben.
A lehetséges hibaszintek:

• Kritikus
• Magas
• Normál (alapértelmezett)
• Alacsony

Partner szinkron

Megkötések, előfeltételek

Az azonos nevű partnerek ellenőrzése folyamati paramétert ki kell kapcsolni.
Mivel a SMARTFRONT rendszere csak a partner szintjén jelöli a partner típusát (jogi- / magánszemély), és az adószámát, ezért, ha a Shoprenter vevő több különböző céghez tartozó címet ad meg, különböző adószámokkal, azt nem tudjuk kezelni.
Az első olyan Shoprenter címnél, ami jogi személyt jelöl, a partner típusát átállítjuk jogi személyre, és kitöltjük az adószám mezőt is. A többi jogi személy adószámát figyelmen kívül hagyjuk.
A partner mentésekor lefut az adószám validáció, és ha van már felvéve partner ezzel az adószámmal, akkor szinkronizáció "Partner mentés hiba" hibát jelez, a vásárlót nem menti el a SMARTFRONT rendszerébe.

Leírás

A partnerek szinkronja kétirányú.
Az első körben a Shoprenterből szinkronizáljuk le a SMARTFRONT rendszerébe az újonnan regisztrált, vagy az utolsó szinkron óta módosított vásárlókat. A szinkron szempontjából az egyedi azonosító Shoprenter vásárló azonosító, melyet a SMARTFRONT rendszerében is eltárolunk a "Külső rendszerbeli egyedi azonosító" mezőben. Másodlagos azonosító a vásárló email címe. Bár a Shoprenter webshopban a email cím egyedi, a SMARTFRONTBAN több partnernek is lehet ugyanaz az alapértelmezett email címe. Ekkor nem tudjuk egyértelműen meghatározni a partnert, megkíséreljük a találtak közül az elsőhöz hozzákötni a partnert. A szinkron folyamatának pontos leírása a Függelék Partner szinkron folyamatábra pontjában található.

Mező megfeleltetés

Partner mező megfeleltetés: (Shoprenter mezőnév: leírás - SMARTFRONT mezőnév: leírás)

• firstname: Vezetéknév - name: teljes név
• lastname: Keresztnév - name: teljes név
• email: Email cím - email: Email cím
• telephone: Telefonszám - phone: Telefonszám
• fax: Fax - fax: Fax
• password: bcrypt jelszó - nem tároljuk: időbélyeg
• newsletter: hírlevél feliratkozás - sendNewsletter: hírlevél
• status: státusz - inactive: fordított flag - nem inaktív
• approved: engedélyezett-e - webshopLogin: webshopon beléphet
• freeShipping: ingyenes szállítás - nem tároljuk: nem
• customerGroup: vásárlói csoport linkje - customerGroupName: vevőcsoport név alapján létrehozzuk, vagy lekérdezzük

Módosítható mezők:

• email: Email cím
• telephone: Telefonszám
• newsletter: hírlevél feliratkozás
• status: státusz
• approved: engedélyezett-e
• customerGroup: vásárlói csoport linkje

Vevő létrehozásakor nem töltjük:

• defaultAddress: alapértelmezett cím linkje
• addresses: címek linkje
• loyaltyPoints: hűségpontok linkje

Partner cím mező megfeleltetés: (Shoprenter mezőnév: leírás - SMARTFRONT mezőnév: leírás)

• firstname: Vezetéknév - name: teljes név
• lastname: Keresztnév - name: teljes név
• type: Vásárló típusa - partner isCorporation mezője, alapértelmezetten "Magánszemély", ld. megjegyzés
• taxnumber: Adószám - partner taxnumber mezője, alapértelmezetten üres, ld. megjegyzés
• company: Cégnév - description: leírás
• address1 és address1: Utca, házszám, Kiegészítő címadatok - publicLand: Közterület neve
• postcode: Irányítószám - zipCode: Irányítószám
• city: Város - placeName: Város
• telephone: telefon - új elérhetőség
• customer: vásárló linkje
• country: ország linkje - kód alapján lekérdezzük és töltjük

Módosítható mezők: minden mező módosítható, a fentieknek megfelelően.

Termék és készlet szinkron

Megkötések, előfeltételek

Termék

Szükséges adókulcs és ország beállítása a Shoprenteren. Ha a termékhez még nem tartozik Shoprenter termék, akkor létrehozunk egyet. Ehhez egyedül a termékkód (Shoprenteren Sku) mező töltöttsége szükséges.
Ha az adott termékkóddal már létezik termék a Shoprenterben, megpróbáljuk összekötni a két entitást. Ha több termék is létezik ezzel a termékkóddal, akkor SKU_EXISTS_WITH_FOREIGN_ID hibát veszünk fel a logba.

Készlet:

A szinkron csak normál státuszú, termék típusú termékeket szinkronizál. A "teljes készlet szinkron", mozgásoktól és módosításoktól függetlenül szinkronizálja az összes termék készletét. Ez több mint 10 000 termék esetén akár 20 percig is eltarthat. A "készlet szinkron" összegyűjti azokat a termékeket, amelyekhez tartozik mozgás a legutolsó készlet szinkron óta és csak azokat módosítja.

Leírás

Termék

Azokat a termékeket küldjük fel, amelyek módosítva lettek a legutolsó termék szinkron óta, illetve azokat amelyekhez tartozik ár a webshop beállításokban választott árlistában és az módosult. Ha a terméklapon ki van töltve a beszállítói ár, akkor a megadott adókulccsal kalkuláljuk belőle a költség mezőt, különben a termék egységárát használjuk, melyet szintén az adókulcson keresztül bruttósítunk. A bruttó ár kalkulációjához, a nettó ár és az árszorzó mezőket töltjük fel a SMARTFRONT termékből.
A Shoprenter termékhez tartozik linkelve egy nyelv és egy termékleírás is. A termékleírás tárolja, a megnevezéshez tartozó mezőket. Ezeket a termék szinkron alatt töltjük.

Készlet

Mivel a "teljes készlet szinkron" az összes termék készletét frissíti, így ez a funkció arra való, hogy az induló készletet feltöltsük a Shoprenterre. A későbbiekben elég a "készlet szinkron" funkció használata amely csak a mozgatott termékeket küldi fel. Ütemezett feladatként is csak ez a szinkron fut le.

Mező megfeleltetés

Shoprenter SMARTFRONT ERP
mezőnév: leírás - mezőnév: leírás
Product

• id: Termék azonosító. Az OuterID módosítására. - foreignId: idegen kulcs
• sku: Cikkszám. - productCode: termékkód
• gtin: Vonalkód/GTIN Azonosító - barCode: vonalkód
• price: Nettó ár.- Price.price: ár
• cost: Költség.- acquisition: bázis ár vagy unitPrice: egységár
• multiplier: Árszorzó - Price.priceMultiplier: szorzó
• taxClass: Áfa kulcs linkje. - vatRate:Adó mértéke

• stock1: Raktár 1 készlet.- Inventory objektumból kalkulálva (quantity)

Product Description

• name:Név.- name:név
• metaDescription:Meta leírás.- description:leírás
• shortDescription:Rövid leírás.- description:leírás
• description:Hosszú Leírás.- longDescription:hosszú leírás

Rendelés szinkron

Megkötések, előfeltételek

A Shoprenter admin felületén a Beállítások / Bolt beállítások / Rendelés állapotok menüpontban a "Függőben lévő", az "Elküldve", a "Feldolgozás alatt" és a "Teljesítve" állapotoknak kötelezően szerepelniük kell.
A bankkártyás fizetés (azonnali fizetés) kezelésére a Shoprenterben egy új állapotot kell bevezetni - pl.: Bankkártyás fizetés.
Az összes fizetési mód, amely nem bankkártyás fizetési tranzakció, "Rendelés állapota" mezője legyen "Függőben lévő", vagy "Elküldve".
A bankkártyás fizetési módoknál, pl.: "OTP bankkártyás fizetés", "CIB bankkártyás fizetés", stb., a "Rendelés állapota" mezője legyen az új státusz, a "Befizetett rendelés állapota" mező pedig legyen "Függőben lévő", vagy "Elküldve".
A szállítási és fizetési feltételek nem kerülnek szinkronizálásra. A Shoprenter admin felületén engedélyezett Fizetési módoknak szerepelnie kell a SMARTFRONT ERP rendszerben is.
Ennek szerkesztésére a Webshop interfész / Szállítási és fizetési feltételek menüpontban a Fizetések fülön van lehetőség.

Leírás

A rendelés folyamata

A beérkezett rendelések státusza "Függőben lévő", vagy "Elküldve", kivéve a bankkártyás fizetési módoknál, ahol a státusz az újonnan bevezetett státusz. Az ilyen új státuszú rendeléseket nem hozzuk át egészen addig, amíg azok "Függőben lévő", vagy "Elküldve" státuszba nem kerülnek, mivel ekkor történt sikeres fizetési tranzakció.
A "Függőben lévő", vagy "Elküldve" státuszú rendeléseket szinkronizáljuk le a SMARTFRONTBA. Ezek "Új" státuszba kerülnek, illetve a Shoprenterben "Feldolgozás alatt" jelenik meg
Ezek után megkezdjük az SMARTFRONT ERP-ben a rendelés feldolgozását, sorrendben a következő státuszokkal:

• Visszaigazolt - opcionális
• Kiszedés alatt
• Kiszedve
• Részlegesen kiszállítva - opcionális
• Lezárt

A lezárt, sikeresen feldolgozott rendeléseket vissza szinkronizáljuk a Shoprenterbe "Teljesítve" státusszal.
Ha a rendelést az ERP-ben valamilyen okból zártuk le, akkor ezek is vissza szinkronizáljuk a Shoprenterbe. A rendelés státusza ekkor a lezárás oka lesz. A lezárás okait az ERP-ben az Adminisztráció / Alapadatok / Értékesítési adatok / Rendelés lezárásának okai pontban vehetjük fel.
A lezárás okainak megfelelő státuszokat a Shoprenter admin felületén a Rendelés állapotok menüpontban kell felvenni.
Ilyenek lehetnek például a "Visszaküldve", "Elutasítva", "Törölve", stb státuszok.

Partner adatok

Névtelen rendelésnél: létrehozunk egy partnert adott névvel, a webshop beállításokban megadott vevő kategóriával, az email címmel, ami nem léphet be a webshopba. Felvesszük a szállítási és számlázási címet a partner címei közé.
Nem névtelen rendelésnél: Lefuttatunk egy partner szinkront Shoprenterből SMARTFRONTBA a vásárlóra.

Mező megfeleltetés

Shoprenter mezőnév: leírás - SMARTFRONT mezőnév: leírás

Rendelés

• id: Rendelés azonosító - foreignId: idegen kulcs
• innerId: Rendelés belső azonosító - foreignCode: idegen kód
• status: "Függőben lévő", vagy "Elküldve" státusz - status: "Új"
• currency: Pénznem linkje - currencyCode, currencyRate: deviza, árfolyam - a linkből meghatározzuk a pénznemet és az árfolyamot
• csak SMARTFRONTBAN beállított mezők:
  • channel: csatorna - Webshop
  • companyId: cég - admin user cége
  • orderDate: rendelés dátuma - szinkronizálás időpontja
  • storageId: raktár - beállításokban megadott
  • shoprenterWebshopId: webshop beállítás azonosító
  • shoprenterWebshopName: webshop beállítás webshop név
  • dimenzió adatok a webshop beállításban megadottak

Rendelés tételek

• sku: termékkód - ebből meghatározzuk a SMARTFRONT terméket és feltöltjük annak adataival:
  • productId: termék azonosító
  • productCode: termékkód
  • productName: termék név
  • productTypeCode: termék típusa
  • dimenzió adatok
  • inventoryType: készlet típus
  • unit - mennyiségi egység
  • displayUnit - mennyiségi egység
  • vatRate - Áfa kulcs
  • vatId - Áfa azonosító
  • vatCode - Áfa kód
  • vatRemark - ÁFA komment
  • storageId: raktár - beállításokban megadott

Árak

• price: nettó egységár - unitPrice: nettó egységár + ÁFA kód alapján a grossUnitPrice: bruttó egységár
• total: nettó ár - netPrice: nettó ár + ÁFA kód alapján a grossPrice: bruttó ár
• originalPrice: eredeti ár - displayOriginalPrice: eredeti egységár nettó (kedvezmény nélkül) + ÁFA kód alapján a originalPrice: eredeti bruttó ár
• unitPrice: nettó egységár - displayUnitPrice: kedvezményes egységár

További tételek

• szállítási költség technikai termék - csak akkor adjuk hozzá a tételekhez ha a szállítás költsége nagyobb mint nulla
• fizetési költség technikai termék - csak akkor adjuk hozzá a tételekhez ha a fizetés költsége nagyobb mint nulla

Függelék

Hibaüzenetek

• Nem létező email cím - EMAIL_NOT_EXISTSA Webshop interfész / Shoprenter webshop beállítások menüpontból indított "Partner szinkron email cím alapján" művelet során megadott email cím nem létezik a Shoprenterben.

• Partnerek azonos email címmel, de más külső azonosítóval - EMAIL_EXISTS_WITH_FOREIGN_IDShoprenter → SMARTFRONT: Az email cím már szerepel a SMARTFRONT rendszerében, de a külső azonosító egy másik vásárlóra mutat (adathiba).SMARTFRONT → Shoprenter: A Shoprenterben szerepel az email cím, de a külső azonosítója partnernek egy másik vásárlóra mutat (adathiba).
• Hiányos partner adatok - PARTNER_VALIDATE_ERROR Hiányos partner adatok - jellemzően hiányzó telefonszám
• Vevő létrehozás / módosítás hiba - POST_PARTNER_ERRORA Vásárló létrehozása API hívás hibával tért vissza
• Partner mentés hiba - SAVE_PARTNER_ERRORA partner mentése a SMARTFRONT rendszerben hibát jelzett. Például: már létező adószám
• Nem létező külső azonosító - FOREIGN_ID_NOT_EXISTSA SMARTFONTBAN tárolt idegen kulccsal nem található vásárló a Shoprenterben (adathiba)
• Többszörös partner adószám - PARTNER_MULTIPLE_TAXNUMBERA vásárló cím típusa Jogi személy, de már van a partnerhez mentett adószám, és az nem egyezik meg a kapott adószámmal, ezt jelezzük hibaként, de a szinkronban tovább megyünk
• Partner cím mentés hiba - SAVE_PARTNER_ADRESS_ERROR Partner címének mentése a SMARTFRONT rendszerben hibát jelzett. Például: cím duplikáció hiba
• Hiányos cím adatok - PARTNER_ADDRESS_VALIDATE_ERROR Hiányos cím adatok, legalább egy kötelező mező nincs kitöltve
• Cím létrehozás / módosítás hiba - POST_ADDRESS_ERRORA Vásárló címének létrehozása API hívás hibával tért vissza.
• Termékek azonos termék kóddal, de más külső azonosítóval - SKU_EXISTS_WITH_FOREIGN_IDA Shoprenterben szerepel az termékkód, de a külső azonosítója terméknek egy másik shoprenter termékre mutat (adathiba).
• Hiányos termék adatok - PRODUCT_VALIDATE_ERROR Hiányos termék adatok, legalább egy kötelező mező nincs kitöltve
• Termék létrehozás / módosítás hiba - POST_PRODUCT_ERRORA termék létrehozása API hívás hibával tért vissza.
• Termék mentés hiba - SAVE_PRODUCT_ERROR Termék mentése a SMARTFRONT rendszerben hibát jelzett.
• Termékleírás validálás hiba - PRODUCT_DESCRIPTION_VALIDATE_ERROR Hiányos termék leírás adatok, legalább egy kötelező mező nincs kitöltve
• Termékleírás létrehozás / módosítás hiba - POST_PRODUCT_DESCRIPTION_ERRORA termék leírás létrehozása API hívás hibával tért vissza.
• Készlet szinkron hiba - POST_INVENTORY_ERROR
• Rendeléshez üres tétellista - ORDER_PRODUCT_LIST_EMPTYA Shoprentertől kapott rendelésnek nincsenek tételei
• Termékkód nem létezik - PRODUCT_CODE_NOT_EXISTSA Shoprentertől kapott rendelésnek egyik tételének termékkódja nem taláható meg a SMARTFRONT rendszerében.
• Fizetési mód nem meghatározható - PAYMENT_METHOD_ERROR
• Szállítási mód nem meghatározható - SHIPMENT_METHOD_ERROR
• Technikai termék nem létezik - TECHNICAL_PRODUCT_NOT_EXISTSA szállítási költség, illetve a fizetési költség számlán való szerepeltetéséhez szükséges technikai "Szolgáltatás" típusú termékek.
• Rendelés mentés hiba - SAVE_ORDER_ERRORA rendelés mentése a SMARTFRONT rendszerben hibát jelzett.
• Rest API hiba - REQUEST_ERROR MInden egyéb, a fenti kategóriákban nem besorolt hiba

Partner szinkron folyamatábra

Shoprenter → SMARTFRONT

SMARTFRONT → Shoprenter