A forgalmi adatok online megküldése



A FORGALMI ADATOK ONLINE MEGKÜLDÉSE

 

A Bercode rendszerben történő vásárlások alkalmával generálódó forgalmi adatok automatikus fogadásához, valamint tárolásához a következő technikai leírást követve kell az adatokat átadni.

 

A szolgáltatás megvalósítása Representational State Transfer (REST) architektúra (http://en.wikipedia.org/wiki/Representational_state_transfer)​,​ és JavaScript Object Notation (JSON) (http://json.org) adatátviteli protokollal történik. A REST és JSON segítségével a szolgáltatás könnyen használható a különböző fejlesztési platformok és nyelvek számára.

 

A vásárlásnál használt bercode megadásával lehetőség van a kód érvényességének, a biztosítható kedvezmények, és a jutalék mértékének lekérdezésére.

 

Ehhez http GET kéréssel meg kell hívni a https://www.bercode.com/api/checkcode/[store]/[bercode] oldalt, ahol a [store] helyén annak a https://www.bercode.com oldalon megadott elfogadóhelynek az Api Id-jét kell megadni, amelyikben a vásárlás történt, a [bercode] helyén pedig az ellenőrizni kívánt bercode értékét kell megadni. A bejelentkezéshez a HTTP Basic authentikációja használandó a https://www.bercode.com oldalon a Forgalmi adatok beállítása oldalon kapott Api Id és API kulcs adatokkal.

 

Példa a hívásra: https://www.bercode.com/api/checkcode/554732/348000419064329953

 

A kérésre adott válasz JSON formátumban tartalmazza a [bercode]-hoz tartozó adatokat.

A válasz a következő paramétereket tartalmazza:

 

 

A FORGALMI ADATOK ONLINE MEGKÜLDÉSE

 

A Bercode rendszerben történő vásárlások alkalmával generálódó forgalmi adatok automatikus fogadásához, valamint tárolásához a következő technikai leírást követve kell az adatokat átadni.

 

A szolgáltatás megvalósítása Representational State Transfer (REST) architektúra (http://en.wikipedia.org/wiki/Representational_state_transfer)​,​ és JavaScript Object Notation (JSON) (http://json.org) adatátviteli protokollal történik. A REST és JSON segítségével a szolgáltatás könnyen használható a különböző fejlesztési platformok és nyelvek számára.

 

A vásárlásnál használt bercode megadásával lehetőség van a kód érvényességének, a biztosítható kedvezmények, és a jutalék mértékének lekérdezésére.

 

Ehhez http GET kéréssel meg kell hívni a https://www.bercode.com/api/checkcode/[store]/[bercode] oldalt, ahol a [store] helyén annak a https://www.bercode.com oldalon megadott elfogadóhelynek az Api Id-jét kell megadni, amelyikben a vásárlás történt, a [bercode] helyén pedig az ellenőrizni kívánt bercode értékét kell megadni. A bejelentkezéshez a HTTP Basic authentikációja használandó a https://www.bercode.com oldalon a Forgalmi adatok beállítása oldalon kapott Api Id és API kulcs adatokkal.

 

Példa a hívásra: https://www.bercode.com/api/checkcode/554732/348000419064329953

 

A kérésre adott válasz JSON formátumban tartalmazza a [bercode]-hoz tartozó adatokat.

A válasz a következő paramétereket tartalmazza:

 

 

Paraméter

Magyarázat

error

hibakód

errortext          

hiba esetén a hiba leírása

fueldiscount

a bercode alapján adható kedvezmény értéke üzemanyag esetén normál áras termékekre

specialfueldiscount

a bercode alapján üzemanyagra adható kedvezmény értéke akciós termékek esetén

discountpercent

a bercode alapján adható kedvezmény értéke normál áras termékek esetén            

specialdiscountpercent

a bercode alapján adható kedvezmény értéke akciós termékek esetén

provisionpercent

a kedvezményes árból számítandó jutalék összegének értéke

fuelprovision

a kedvezményes árból számítandó jutalék összegének értéke üzemanyag esetén

discountunit   

Az üzemanyag kedvezmény mennyiségi egysége.

 

 

Az error értéke 0, ha a Bercode megfelelő, a kedvezmény biztosítható.

Hibás kód esetén az error értéke a következő értékeket veheti fel:

 

 

error

errortext

1

Ismeretlen bercode

2

Hibás bercode szint

3

A bercode lejárt

 

 

Példa a válaszra: {"response":{"discountunit":"HUF/l","discountpercent":10,"specialdiscountpercent":5,"fueldiscount":8,"specialfueldiscount":4,"fuelprovision":"3.00","provisionpercent":3,"error":0,"errortext":""},"statusCode":200}

 

 

A kérésekre adott standard HTTP válaszkódok:

 

HTTP Status Code

Magyarázat

200

Adatok lekérdezése rendben.

400

Az adatok nem megfelelőek.

401

Hitelesítési hiba.

405

A kérés módja nem GET.

500

Belső szerver hiba.

 

Az összesített vásárlási adatok átadása HTTP PUT hívások segítségével történik a https://bercode.com/api/provision címre. A bejelentkezéshez a HTTP Basic authentikációja használandó a https://www.bercode.com oldalon a Forgalmi adatok beállítása oldalon kapott Api Id és API kulcs adatokkal.  Egy PUT több objektumot is átadhat, azokat egyetlen JSON Array-ba formálva, a PUT hívás body elemeként. A PUT hívás MIME típusa application/json legyen.

 

Megnevezés

Típus

Magyarázat

bercode

String

A vásárláskor használt kártya vonalkódja.

time

String

A vásárlás dátuma és időpontja ISO8601 formában.

store

String

Elfogadóhely Api Id

cr

String

Az Elfogadó Partner rendszerében annak a pénztárának a kódja, amelyiknél a vásárlás történt.

currency

String

ISO 4217 deviza kód.

id

String

A vásárlás egyértelmű azonosítója az Elfogadó Partner rendszerében.

tally

Array

A vásárlás tételei.

 

A tally array tartalmazza a termékek rule paraméter szerint összesített adatait. Tehát ha egy vásárlás pl. csak normál áras, vagy csak akciós termékeket tartalmazott, akkor az árakat össze kell adni, és a tally array-ban egy sorban kell átadni. Ha egy vásárlás tartalmazott normál és akciós termékeket is, akkor lehet a tally array-nak két sora.

 

Megnevezés

Típus

Magyarázat

rule

Integer

Értéke csak 0 vagy 1 lehet.

0 = normál ár, 1 = akciós ár

price

Number

A termékek alapárának összege.

discountprice

Number

A termékek kedvezményes árának összege.

discountpercent

Number

A kedvezmény százalékos értéke.

provision

Number

A fizetendő jutalék összege.

quantity

Number

A termékek mennyisége

discountunit

Number

A kedvezmény mennyiségi egysége. Lehetséges értékek 1, és 2.

1 - %, 2 – checkcode függvény discountunit paraméterében kapott mértékegység.

2 esetén a quantity megadása kötelező.

 

 

Példa: {"bercode":"348123415093345678", "time":"2013-07-08T15:20:38Z", "store":"554732", "cr":"028", "currency":"HUF", "id":"79e242c0",

"tally":[{"rule":0, "price":2381, "discountprice":2000, "discountpercent":16, "discountunit":1, "provision":60}]}

 

Üzemanyag és shop termék vásárlása esetén:

{"bercode":"348123415093345678", "time":"2013-07-08T15:20:38Z", "store":"554732", "cr":"028", "id":"79e242c0", "currency":"HUF",

"tally":[{"rule":0, "price":1000, "discountprice":900, "discountpercent":10, "provision":27, "discountunit":1},{"quantity":"20", "rule":"0", "price":6000, "discountprice":5840, "discountpercent":8, "provision":60, "discountunit":2}]}

 

 

A kérések eredményét standard HTTP válaszkódokkal adjuk vissza:

 

 

 

 

HTTP Status Code

Magyarázat

201

Adatok rögzítése rendben.

400

Az adatok nem megfelelőek.

401

Hitelesítési hiba.

409

A megadott ID már létezik.

500

A szerver nem tudja rögzíteni az adatot.

 

Az elszámoláshoz elegendő a vásárlási adatok elküldése, a további két lehetőség opcionális:

 

Az átadott adatok ellenőrzése a https://bercode.com/api/provision/[id] címre indított HTTP GET kéréssel végezhető el egy vásárlásra. Az [id] helyén az ellenőrizni kívánt vásárlás azonosítóját kell megadni.

 

Példa: https://bercode.com/api/provision/79e242c0

 

A kérésre adott válasz az adatok átadásának megfelelő módon, JSON formátumban tartalmazza az [id]-hez tartozó adatokat.  

 

A kérések sikerességét standard HTTP válaszkódokkal adjuk vissza:

 

HTTP Status Code

Magyarázat

201

Adatok kérése rendben.

400

ID nem lett megadva.

401

Hitelesítési hiba.

404

A megadott ID nem létezik.

500

Hiba az adatok kérésekor.

 

Egy előzőleg átadott vásárlás a https://bercode.com/api/provision/[id] címre indított HTTP DELETE kéréssel törölhető. Az [id] helyén a törölni kívánt vásárlás azonosítóját kell megadni.

 

Példa: https://edc.hu/api/provision/79e242c0

 

HTTP Status Code

Magyarázat

201

Adatok törlése rendben.

400

ID nem lett megadva.

401

Hitelesítési hiba.

404

A megadott ID nem létezik.

500

Hiba az adatok kérésekor.

 

 
   
   
   
   
   
   
   
   
   

 

 

Az error értéke 0, ha a Bercode megfelelő, a kedvezmény biztosítható.

Hibás kód esetén az error értéke a következő értékeket veheti fel:

 

 

error

errortext

1

Ismeretlen bercode

2

Hibás bercode szint

3

A bercode lejárt

 

 

Példa a válaszra: {"response":{"discountunit":"HUF/l","discountpercent":10,"specialdiscountpercent":5,"fueldiscount":8,"specialfueldiscount":4,"fuelprovision":"3.00","provisionpercent":3,"error":0,"errortext":""},"statusCode":200}

 

 

A kérésekre adott standard HTTP válaszkódok:

 

HTTP Status Code

Magyarázat

200

Adatok lekérdezése rendben.

400

Az adatok nem megfelelőek.

401

Hitelesítési hiba.

405

A kérés módja nem GET.

500

Belső szerver hiba.

 

Az összesített vásárlási adatok átadása HTTP PUT hívások segítségével történik a https://bercode.com/api/provision címre. A bejelentkezéshez a HTTP Basic authentikációja használandó a https://www.bercode.com oldalon a Forgalmi adatok beállítása oldalon kapott Api Id és API kulcs adatokkal.  Egy PUT több objektumot is átadhat, azokat egyetlen JSON Array-ba formálva, a PUT hívás body elemeként. A PUT hívás MIME típusa application/json legyen.

 

Megnevezés

Típus

Magyarázat

bercode

String

A vásárláskor használt kártya vonalkódja.

time

String

A vásárlás dátuma és időpontja ISO8601 formában.

store

String

Elfogadóhely Api Id

cr

String

Az Elfogadó Partner rendszerében annak a pénztárának a kódja, amelyiknél a vásárlás történt.

currency

String

ISO 4217 deviza kód.

id

String

A vásárlás egyértelmű azonosítója az Elfogadó Partner rendszerében.

tally

Array

A vásárlás tételei.

 

A tally array tartalmazza a termékek rule paraméter szerint összesített adatait. Tehát ha egy vásárlás pl. csak normál áras, vagy csak akciós termékeket tartalmazott, akkor az árakat össze kell adni, és a tally array-ban egy sorban kell átadni. Ha egy vásárlás tartalmazott normál és akciós termékeket is, akkor lehet a tally array-nak két sora.

 

Megnevezés

Típus

Magyarázat

rule

Integer

Értéke csak 0 vagy 1 lehet.

0 = normál ár, 1 = akciós ár

price

Number

A termékek alapárának összege.

discountprice

Number

A termékek kedvezményes árának összege.

discountpercent

Number

A kedvezmény százalékos értéke.

provision

Number

A fizetendő jutalék összege.

quantity

Number

A termékek mennyisége

discountunit

Number

A kedvezmény mennyiségi egysége. Lehetséges értékek 1, és 2.

1 - %, 2 – checkcode függvény discountunit paraméterében kapott mértékegység.

2 esetén a quantity megadása kötelező.

 

 

Példa: {"bercode":"348123415093345678", "time":"2013-07-08T15:20:38Z", "store":"554732", "cr":"028", "currency":"HUF", "id":"79e242c0",

"tally":[{"rule":0, "price":2381, "discountprice":2000, "discountpercent":16, "discountunit":1, "provision":60}]}

 

Üzemanyag és shop termék vásárlása esetén:

{"bercode":"348123415093345678", "time":"2013-07-08T15:20:38Z", "store":"554732", "cr":"028", "id":"79e242c0", "currency":"HUF",

"tally":[{"rule":0, "price":1000, "discountprice":900, "discountpercent":10, "provision":27, "discountunit":1},{"quantity":"20", "rule":"0", "price":6000, "discountprice":5840, "discountpercent":8, "provision":60, "discountunit":2}]}

 

 

A kérések eredményét standard HTTP válaszkódokkal adjuk vissza:

 

 

 

 

HTTP Status Code

Magyarázat

201

Adatok rögzítése rendben.

400

Az adatok nem megfelelőek.

401

Hitelesítési hiba.

409

A megadott ID már létezik.

500

A szerver nem tudja rögzíteni az adatot.

 

Az elszámoláshoz elegendő a vásárlási adatok elküldése, a további két lehetőség opcionális:

 

Az átadott adatok ellenőrzése a https://bercode.com/api/provision/[id] címre indított HTTP GET kéréssel végezhető el egy vásárlásra. Az [id] helyén az ellenőrizni kívánt vásárlás azonosítóját kell megadni.

 

Példa: https://bercode.com/api/provision/79e242c0

 

A kérésre adott válasz az adatok átadásának megfelelő módon, JSON formátumban tartalmazza az [id]-hez tartozó adatokat.  

 

A kérések sikerességét standard HTTP válaszkódokkal adjuk vissza:

 

HTTP Status Code

Magyarázat

201

Adatok kérése rendben.

400

ID nem lett megadva.

401

Hitelesítési hiba.

404

A megadott ID nem létezik.

500

Hiba az adatok kérésekor.

 

Egy előzőleg átadott vásárlás a https://bercode.com/api/provision/[id] címre indított HTTP DELETE kéréssel törölhető. Az [id] helyén a törölni kívánt vásárlás azonosítóját kell megadni.

 

Példa: https://edc.hu/api/provision/79e242c0

 

HTTP Status Code

Magyarázat

201

Adatok törlése rendben.

400

ID nem lett megadva.

401

Hitelesítési hiba.

404

A megadott ID nem létezik.

500

Hiba az adatok kérésekor.