API dokumentáció

Főoldal

API dokumentáció


Bevezetés

Köszöntelek az onlinePénztárca API dokumentációs oldalán!
A leírás folyamatosan bővülni fog a jövőben, az api frissítések során a kapcsolattartónak beállított emailen fogunk értesíteni, hogy melyek az új funkciók és milyen új lehetőségekkel bővültünk. A dokumentáció részeit blokkokba szegmentáltuk, kérlek olvasd el a teljes leírást, hogy tiszta képet kapj az onlinePénztárca beépítéséről.

Kapcsolat

Technikai jellegű kérdések esetén szívesen fogadjuk kérdéseidet a support@onlinepenztarca.hu email címen, vagy ha be vagy jelentkezve adminként, akkor az oldal jobb alsó sarkában található chaten.

Telefonos kapcsolat esetén:

  • Support:
    • support@onlinepenztarca.hu

Tranzakció állapotváltozás

Az onlinePénztárca elfogadást és kibocsájtást tranzakciókként kezeljük. Az egyes tranzakciók különböző típusokat vehetnek fel:
  • Elfogadó
  • Kibocsájtó
  • Toborzó
Minden tranzakció felvesz egy kezdeti állapotot, amely a rendelés életciklusával együtt változik! A Tranzakciók állapotváltozása különböző módon történik attól függően, hogy milyen típusa van.
  • onlinePénztárca elfogadás
    1. Egy vásárló lead egy rendelést és felhasznál(fizet) az onlinePénztárcájából, akkor az onlinePénztárcából fizetett összeg Elfogadó típuson keresztül létrejött tranzakció lesz. Ennek a tranzakciónak az állapota azonnal fizetett állapotba kerül, tehát le van vonva az ügyfél onlinePénztárcájából, függetlenül attól, hogy a rendelés milyen állapotban van.
  • onlinePénztárca kibocsájtás
    1. Amikor egy vásárló lead egy rendelést és az adott áruház kibocsájtó, akkor a kibocsájtott onlinePénztárca összeg szintén tranzakcióként lesz tárolva. A rendelés kezdeti állapotban egy új, feldolgozatlan rendelés. Ez a tranzakció egy un. visszaigazolásra vár állapotba kerül. Ez azért fontos, mert ebben az állapotban a vásárló még nem élhet a kapott onlinePénztárca kibocsájtással!
    2. A rendelés következő szakaszában, amikor a rendelést visszaigazolt státuszba kerül. Ekkor a rendeléshez köthető kibocsájtó tranzakciók un. visszaigazolt állapotba kerülnek. Ekkor lesz a vásárló egyenlege a kapott kibocsájtás értékének megfelelően inkrementálva.
  • Rendelés visszamondása
    • Egy rendelés visszamondása esetén minden hozzá köthető tranzakció un. visszamondott állapotba kerül. Ekkor a vásárló onlinePénztárcájának egyenlege is rendeződik. Tehát ha volt a rendeléshez elfogadás, akkor az elfogadás értékét visszakapja a vásárló, ha volt hozzá kibocsájtás, akkor levonásra kerül.

    • *Az állapotok változatására a /order/status/update és /order/status/storno hívás lesz a megfelelő!*

Hibakezelés

Minden* response JSON-ben jön vissza, mindig tartalmaz egy success kulcsot, amelynek az értéke true vagy false attól függően, hogy a kérés sikeres vagy nem!

*Vannak egyedi hívások, amelyeknek eltérő válasza lehet, ezeknek egyedi rendeltetésük van. Ezeket jelezzük a hívás leírásánál.

Adatok áttöltése

Az onlinePénztárcának van egy globális termék keresője, amiben a felhasználók tudnak a korrekt webáruházak termékei között böngészni. Amennyiben szeretnéd, hogy a termékeid elérhetőek legyenek benne, úgy kérlek add át nekünk xml-ben. A formátuma a következő képpen néz ki:

<productFeed> <product> <id><![CDATA[54105182]]></id> <number><![CDATA[suzukigs500f]]></number> <name><![CDATA[Suzuki GS 500F]]></name> <category> <category1><![CDATA[Motorok]]></category1> <category2><![CDATA[Nagymotorok]]></category2> </category> <price><![CDATA[2000]]></price> <url><![CDATA[http://onlinepenztarca.hu/Suzuki-GS-500F]]></url> <image><![CDATA[http://onlinepenztarca.hu/shop_ordered/40712/shop_pic/suzuki.jpg]]></image> <description><![CDATA[]]></description> <stock><![CDATA[off]]></stock> <status><![CDATA[1]]></status> <customFields> <property name="Márka"><![CDATA[Suzuki]]></property> </customFields> </product> </productFeed> Itt megtalálható egy demo xml fájl.

Beépítés menete

Az onlinePénztárca beépítéséhez a következő sorrendet kell betartani:

A beépítés megkönnyítése érdekében két részre osztottunk a feladatokat, az egyék fele az a felhasználó számára is látható kosár folyamat, a másik a munkatársak által kezelt CMS vagy Admin felület.

A kommunikációs hívások teljes leírása lejjebb találhatóak, ahol minden pontos adat le van írva, mik a bemeneti paraméterek és mivel tér vissza.

  • Legelőször a kommunikáció pontos kiépítése szükséges, ehhez a partner/testcom a legoptimálisabb, ha ez sikeresen tér vissza, akkor a pontokon egymás után folyamatosan követve érdemes haladni.
  1. order/payblock A felhasználó számára is látható payblock egy olyan elem mellyel az ügyfél a kosár oldalon (fizetés és szállítás menüpontban) találkozik, ezt bepipálva veheti igénybe az onlinePénztárcát. A hívás egy teljes beformázott html blokkot (responsive) ad vissza, ennek személyre szabására van lehetőség. Itt nincs visszaadva success, csak maga a html blokk. A payblock-ban található egy checkbox ami alapján lehet, vizsgálni a felhasználó szeretne fizetni onlinePénénztárcával vagy sem.
  2. Az order/calc egy olyan hívás mely visszaadja, hogy a felhasználó mennyit tud fizetni az onlinePénztárcájából. Azért érdemes lefuttatni, mert a vevők szeretik látni mennyit spórolhatnak már a vásárlás előtt. Érdemes a vásárlás összegző oldalon meghívni. A felhasználandó egyenlegként a legegyszerűbb a rendelés teljes árát beadni, mert így nem kell semmilyen számolással vagy további hívással bajlódni.
  3. trans/create/lite ezt a hívást már a rendelés generálása közben szükséges lefuttatni. A feladata annyi hogy, az onlinePénztárca is le tudja generálni és visszaadni mennyit tudott ténylegesen spórolni az ügyfél. Ez a hívás a tényleges létrehozása az onlinePénztárca elfogadás és kibocsájtásnak, ezért ez a legfontosabb. Amenyiben a felhasználó nem található az onlinePénztárcában, úgy egy link kerül csak összeállításra mely 1 napig él utánna törlődik.
  4. user/button egy linkesített gomb mely egy iframbe van visszaadva, ez informálja a felhasználót arról mekkora összeg került onlinePénztárcájába. Ezt a hívást minden esetben a „köszönő oldalon” kell meghívni! Nem létező felhasználó esetén erre a gombra az átvételhez szükséges link kerül.

Az admin felületen 2 gomb elhelyezése szükséges pluszba azon az oldalon, ahol új rendelést lehet létrehozni vagy szerkeszteni. A két gomb egyike az onlinePénztárca elfogadást, még a másik a kibocsájtást tudja szabályozni, ez azért is fontos mert pl: viszonteladóknak nem érdemes kibocsájtást adni, vagy egy készülékcsere esetén nem kell sem elfogadás sem kibocsájtás.

  1. A két gomb módosításakor (ki vagy bekapcsolás) ugyan annak a hívásnak kell lefutnia mindig, ez pedig a trans/create/lite (A hívás leírásánál megtalálod, hogy miként kell paraméterezni). Egy képpel illusztráljuk, hogy milyen formára gondolunk:
    rendelés szerkesztése
  2. Bármilyen termék vagy ár módosításakor szükséges lefuttatni a trans/create/lite ellenkező esetben előforulhat, hogy bennragad érték az onlinePénztárcán ha nem teljes a szinkron például: egy termék módosításnál lehetséges, hogy az előző termék árához felhasználható összeg marad bent a rendszerben, ha folyamatos a kommunikáció, akkor ez a probléma nem létezik.
  3. Amint egy rendelésről letörlik a kedvezmény tételt (onlinePénztárca tétel) akkor is szükséges lefuttatni a trans/create/lite hívást, mert ezzel lesz teljes a szinkron, bár ez az opció csak akkor szükséges, ha az Admin felületen a rendelés módosítása nem többlépcsős, hanem mindent azonnal jóváhagy a rendszer.
  4. order/status/update Mikor egy rendelést visszaigazolnak, akkor kell ezt a hívást lefuttatni, itt az adott rendeléshez tartozó onlinePénztárca tranzakciók megkapják végleges állapotukat (kivéve, ha az 5. pontban leírt stornóra kerül sor).
  5. order/status/storno ha egy rendelést visszamondanak, vagy törölnek, ezt a hívást szükséges meghívni.

API

Típus URL Szükséges Jogosultság

Leírás

Ez az API hívás több oldalról használható, első fontos tulajdonsága, hogy képes ellátni elfogadó és kibocsájtó szerepet is. A másik, hogy mind a két jogosultságnak megfelelően lehet használni, tehát kibocsájtóként is beépíthetjük, de mindössze csak az elfogadó tulajdonságát tudjuk kihasználni. Kibocsájtóként pedig teljesértékűen.


Paraméter Típus Kötelező Megjegyzés
user array igen Vásárló adatai, ezekből az email és a firstName a kötelező.
order array igen A megrendelés alap adatai.
cart array/bool nem Ennek a paraméternek 3 típusa van:
array: Termékek felsorolása a szűrővel ellátott kampányok miatt.
false: Ha nem szereténk hogy kibocsájtás történjen. Fontos: nem termékenként, hanem a cart paraméternek kell beállítani("cart:false,")!
true vagy üres vagy kihagyás: A rendszer kiszámolja és felgenerálja a felhasználónak(átmeneti állpotba) a tranzakciókat. Ebben az esetben csak a szűrővel nem rendelkezőket!
valueOfOpCoins int opcionális A vásárló onlinePénztárcájából felhasználni kívánt összeg. Ha fel akarunk használni a vásárló onlinePénztárcájából, akkor kötelező paraméter! Ha nem akarsz bajlódni a számolással egyszerűen add be a megrendelés összegét, mi úgy is újra átszámoljuk.

Tömb paraméterek

Paraméter Típus Kötelező Megjegyzés
user.email string igen A vásárló email címe.
user.data.gender int nem A vásárló neme
user.data.lastName string nem A vásárló vezetékneve
user.data.firstName string igen A vásárló keresztneve
user.data.birthday string nem A vásárló születésnapja
user.data.zipCode string nem A vásárló irányítószáma
order.id int igen A rendelés egyedi azonosítója.
order.amount int igen A rendelés összege
order.time string igen A rendelés leadásának pontos időpontja. Format: yyyy-mm-dd hh:mm:ss
order.colleagueEmail string nem A munkatárs email címe. Kosárfolyamatban nem szükséges megadni, ugyanakkor a rendelés szerkesztése esetén javasolt!
cart.0.price int igen Itt be kell adnunk a termék árát, mert ha a kampány, a termék árához viszonyítva bocsájt ki (tehát százalékos), akkor csak így tudjuk kiszámolni, hogy mennyi OP. jár érte.
cart.0.productId string igen A termék azonosítója, hogy a szűrővel ellátott kampányok is hozzá generálódjanak a rendeléshez. Fontos, nem termékkódot hanem termék azonosítót kell megadni melyet a feed fájlban is elküldésre kerül.

Request

{
 "body":
 {
  "user":
  {
   "email":"colleague@email.com",
   "data":
   {
    "gender":1,
    "lastName":"Gipsz",
    "firstName":"Jakab",
    "birthday":"1993-1-06",
    "zipCode":7624
   }
  },
  "order":
  {
   "id":999,
   "amount":100000,
   "time":"2017-08-01 15:00:00",
   "colleagueEmail":"colleague@email.com"
  },
  "cart":
  {
   "0":
   {
    "productId":7748,
    "price":50000
   },
   "1":
   {
    "productId":7749,
    "price":50000
   }
  },
  "valueOfOpCoins":5000
 }
}

Response

{
	"succes":true,
	"returninfo":
	{
		"balance":304500,
		"email":"email@example.com"
	},
	"applied":-5000
}

Response adatok

Paraméter Típus Megjegyzés
success bool Siker esetén true, ellenkező esetben false
returninfo.balance int A vásárló onlinePénztárcájának összege
returninfo.email string A vásárló email címe
applied int onlinePénztárcából beváltott összeg

Leírás

Adott felhasználó egyenlege alapján legenerált html blokk. Funkciója az, hogy a kosár folyamatba a felhasználó be tudja pipálni és ezzel használhatja az onlinePénztárcát.
Paraméter Típus Kötelező Megjegyzés
userEmail email igen Felhasználó email címe
cartAmount int igen A kosár aktuális értéke

Request

{
	"body":
	{
		"userEmail":"test@test.com",
		"cartAmount":15000,
	}
}

Response

Response adatok

Sikeres
Siker esetén egy teljes html blokk, hiba esetén pedig egy üres string tér vissza.

Leírás

A köszönőoldalon biztosítani kell egy gomb megjelenítését! 3 gomb típus létezik, mindig a megadott helyzet függvénye, hogy melyik lesz megjelenítve.
  • A felhasználó nem létezik az online pénztárcában (regisztrációs link)
    • Rendelés alatt összeállított egyediv link
    • Regisztrációs kampány
  • Létező felhasználó fiók (belépési oldalra vezető link)

Paraméter Típus Kötelező Megjegyzés
userEmail string igen Vásárló email címe
orderId String igen A rendelés azonosítója

Request

{
	"userEmail":"email@example.com",
	"orderId":4563
}

Response

	
{
	{
    "success": true,
    "returnelements": {
        "buttonType": 1,
        "buttonIframe": 
    }
}

Response adatok

Paraméter Típus Megjegyzés
success bool Siker esetén true, ellenkező esetben false.
buttonType int A button típusa.
buttonIframe string A gomb Iframe megjelenítése, itt nem szükséges verziókat kezelni, mert a megfelelő button fog megjelenni.

Leírás

Lehetőségünk van egy rendeléshez tartozó tranzakciók állapotát updatelni. Például, ha egy rendeléshez tartozó tranzakciók állapota visszaigazolásra vár állapotban van, akkor jóvá tudjuk írni a felhasználónak, amikor a rendelést visszaigazolják. Itt egy trankzació állapotát tehetjük inaktív állapotba, ha éppen aktív. Állapotok:
  • 1: visszaigazolásra vár
  • 2: visszaigazolt
  • 4: visszamondott

Fontos: ha egy rendelést már visszamondtak akkor az már nem kerülhet újból semmilyen más állapotba.

Paraméter Típus Kötelező Megjegyzés
orderId int igen Rendelés egyedi azonosítója
status int igen Új állapot azonosítója
colleagueEmail string igen Munkatárs email címe

Request

{
	"body":
	{
		"orderId":"4563",
		"status":"2",
		"colleagueEmail":"colleague@email.com"
	}
}

Response

{
    "succes":true
}

Response adatok

Paraméter Típus Megjegyzés
success bool Siker esetén true, ellenkező esetben false.

Leírás

Adott rendeléshez tartozó tranzakciók visszamondása. Alapvetően ha egy rendelés visszamondott állapotba kerül, akkor ezzel a hozzá kapcsolódó tranzakciókat visszamondott állapotba lehet állítani!

Fontos: ha egy rendelést már visszamondtak akkor az már nem kerülhet újból semmilyen más állapotba.

Paraméter Típus Kötelező Megjegyzés
orderId int igen Rendelés egyedi azonosítója
colleagueEmail string igen Munkatárs email címe

Request

{
	"body":
	{
		"orderId":"4563",
		"colleagueEmail":"colleague@email.com"
	}
}

Response

{
    "succes":true
}

Response adatok

Paraméter Típus Megjegyzés
success bool Siker esetén true, ellenkező esetben false.

Leírás

Segítségével egy általános számítást kapunk egy megadott összegre. Megkapjuk, hogy a felhasználótól függően és függetlenül is a számított értékeket! Minden visszakapott adat pontosan leírásra kerül a response adatokban.
Paraméter Típus Kötelező Megjegyzés
userEmail string igen Vásárló email címe
valueOfOpCoins int opcionális A vásárló onlinePénztárcájából fizetni kívánt összeg
orderAmount int igen A rendelés végösszege

Request

{
	"body":
	{
		"userEmail":"email@example.com",
		"valueOfOpCoins":"5000",
		"orderAmount":"100000"
	}
}

Response

{
	"success":true,
	"calculatedData":
	{
		"maxRedeemValueWithoutUser":5000,
		"priceWithDiscount":"95000",
		"valueOfOpCoins":5000,
		"numberOfOpCoins":10,
		"userBalance":15000,
		"maximumNumberOfOpCoin":10,
		"maximumValueOfPaymentCampaign":10000,
		"getOpCoin":500
	}
}

Response adatok

Paraméter Típus Megjegyzés
success bool Siker esetén true, ellenkező esetben false.
calculatedData.maxRedeemValueWithoutUser int A megadott összeghez maximum elfogadható onlinePénztárca érték, függetlenül a megadott felhasználótól.
calculatedData.priceWithDiscount int Az összeg, ha levonjuk a paraméterként megadott onlinePénztárca értéket (valueOfOpCoins).
calculatedData.valueOfOpCoins int A maximális elfogadható onlinePénztárca érték a felhazsnálóhoz (valueOfOpCoins).
calculatedData.numberOfOpCoins int A megadott onlinePénztárca érték 500 Ft-os kuponok formájában átszámítva.
calculatedData.userBalance int A vásárló aktuális onlinePénztárca egyenlege.
calculatedData.maximumNumberOfOpCoin int A maximum elfogadható onlinePénztárca érték 500 Ft-os kuponok formájában átszámítva.
calculatedData.maximumValueOfPaymentCampaign int Az elfogadás értékhatára. Ez határozza meg, hogy mekkora összegenként fogadunk el 500 Ft-ot.
calculatedData.getOpCoin int Az elfogadás értékhatára. Megkapjuk, hogy mekkora összeget fogadunk el kuponok formájában. Ez fix adat, mindenkinek egységesen 500 és nem lehet módosítani!