eVIR tudásbázis

API

Az eVIR rendszer képes más rendszerekkel való kommunikációra. A kommunikáció http(s) csatornán keresztül történik.

Amire szükség van a beállításhoz:

• egy működő eVIR rendszer (a következőkben https://evir.hu/cegnev címen hivatkozunk rá)
• admin jogosultság a rendszeren belül a beállításokhoz

Felhasználó létrehozása

Létre kell hozni azt a felhasználót, akinek a nevében a kommunikáció történik. A Rendszer→Felhasználók menüpontban ugyan olyan módon kell hozzáadni, mint bármilyen más normál felhasználót. Biztonsági okokból csak azokhoz a műveletekhez kapjon jogosultságot, amelyekre szüksége van a kommunikációnál.
Amikor a felhasználó rögzítése megtörtént, a rendszer generál egy tokent a névből és a jelszóból. Fontos tudni, hogy a jogosultság utólagos módosítása nem befolyásolja a tokent, de a felhasználói név vagy jelszó változtatása igen.

Biztonsági okokból a tokent kizárólag létrehozáskor, vagy jelszócsere alkalmával írja ki a rendszer, ilyenkor kell kimásolni és biztonságba helyezni.

Tipp: a kommunikáció céljából létrehozott felhasználó nevével és jelszavával be lehet jelentkezni a rendszerbe, és ki lehet próbálni a felületen a funkciókat mielőtt azok automatizálásra kerülnek.

Alap URL létrehozása

Az összes kommunikációs folyamatban az URL egyformán kezdődik. Felépítése

• A rendszer címe (tipikusan https://evir.hu/cegnev jellegű URL)
• a program (tipikusan index.cgi)
• a token
• a funkció

Például:

https://evir.hu/cegnev/cgi-bin/index.cgi?token=jMuPFcKJdyKYqMZ7iGiLpxF/32k

A továbbiakban ezt az URL-t kell kiegészíteni a kívánt kommunikációs forma (JSON, XML, CSV, stb.) és a modulok paraméterezésének megfelelően. A funkció legegyszerűbben a menüpontok linkjeiben illetve az oldalak egyéb linkjeiben található „dok” kulcsok értékeiből lehet meghatározni.

Míg lekérdezések esetében az URL tartalmazza a kiválasztott a kommunikációs formát, adatok küldése esetén különböző programrészeket kell meghívni. Régebben XML alapon történt a kommunikáció, de az utóbbi időben a JSON már sokkal népszerűbb, kezelése egyszerűbb, ezért mi is azt preferáljuk.

Természetesen továbbra is támogatjuk az XML alapú megoldásokat is, de új rendszereknél javasoljuk a JSON alapú kommunikációt. Az általános XML interface leírása: XML Interface version 0.3. A partner és rendszer specifikus XML megoldások leírásai publikusan nem érhetőek el.

JSON kommunikációs forma esetén a kliens JSON formátumban küldi az adatokat a szervernek:

• a rendszer kezeli a Content-type: application/json illetve text/json érkező POST-olt adatot,
• valamin json névre hallgató form mező adatként is elfogadja,
  • akár GET
  • akár POST metódussal érkezik.
• Charset encoding: UTF-8
• a JSON adat egy hash, melynek kulcsai az adott programrésztől függenek, de van minimum 2 kötelező eleme:
  • token: a klienst azonosító eVIR felhasználó tokenje
  • dok: a művelet

Példa egy tartalmilag hiányos, de egyébként helyes json hívásra GET metódus esetén:

https://evir.hu/cegnev/cgi-bin/index.cgi?json={"token":"jMuPFcKJdyKYqMZ7iGiLpxF/32k","dok":"api_szamla"}

Részletesebb leírás például a számlázásról: Számla API

Az esetek túlnyomó többségében kizárólag listák lekérdezésére van szükség, ezért a továbbiakban ezek a leegyszerűsített verziók szerepelnek konkrét URL-ekkel, ahol csak a rendszer címét és a tokent kell kicserélni a működő állapot eléréséhez.

Legegyszerűbb kommunikációs forma: egy lista lekérdezése

Az alap URL-t kell kiegészíteni a dok kulccsal, melynek paramétereként a funkciót kell megadni, pl:

https://evir.hu/cegnev/cgi-bin/index.cgi?token=jMuPFcKJdyKYqMZ7iGiLpxF/32k&dok=lista_partnerek

Ennek hatására HTML listát kapunk vissza. Ugyan ezt a listát CSV formában úgy kaphatjuk meg, ha további paraméterként a dokop=csv,, is belekerül az URL-be:

https://evir.hu/cegnev/cgi-bin/index.cgi?token=jMuPFcKJdyKYqMZ7iGiLpxF/32k&dok=lista_partnerek&dokop=csv,,

Ennek analógiájára ugyan ez a lista JSON formátumban úgy érhető el, ha a dokop=json,, kerül az URL-be:

https://evir.hu/cegnev/cgi-bin/index.cgi?token=jMuPFcKJdyKYqMZ7iGiLpxF/32k&dok=lista_partnerek&dokop=csv,,

Az XML alapú kommunikáció teljesen más módon működik, arról teljesen külön dokumentáció szól, de az összehasonlíthatóság kedvéért álljon itt ugyan ennek a partnerlistának az XML alapú lekérése is:

https://evir.hu/cegnev/cgi-bin/index.cgi?xml=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%3Cesystem%3E%3Cclick%3E%3Cdata%3E%3Crecord%3E<field><name>dok</name><value>lista_partnerek</value></field><field><name>token</name><value>jMuPFcKJdyKYqMZ7iGiLpxF%2B32k</value></field><field><name>lang</name><value>HU</value></field>%3C%2Frecord%3E%3C%2Fdata%3E%3C%2Fclick%3E%3C%2Fesystem%3E

Szűrt listák

A fenti HTML / CSV / JSON listák esetében természetesen nem csak a teljes listákat lehet lekérni, hanem szűrt listákat is. A szűrések már teljesen modul/lista specifikusak, ezekhez tartozó egyedi paraméterek meghatározásában egyedileg segítünk.

Testre szabott listák

A rendszer lehetőséget biztosít a listák testre szabásához (oszlopok törlése, hozzáadása, szűrések beállítása, stb.). Az ilyen módon elmentett listákra is lehet hivatkozni az API-n keresztül. A szerkesztett lista azonosítóját a Rendszer→Felhasználói fiók→Testreszabott listák menüpontjában lehet megtalálni. Ha pl. a lista azonosítója 1, akkor a linkhez a param=nosave_list_stat_id,1-t kell hozzáfűzni. Pl:

https://evir.hu/cegnev/cgi-bin/index.cgi?token=jMuPFcKJdyKYqMZ7iGiLpxF/32k&dok=lista_partnerek&dokop=csv,,&param=nosave_list_stat_id,1

Természetesen ehhez szükséges, hogy a lista vagy publikus jogosultságú legyen, vagy a tokennel azonosított felhasználó legyen a tulajdonosa.

Egyéb kommunikációk

Természetesen nem csak lekérdezni lehet, hanem adatokat bevinni is. Leggyakoribb ilyen adatátvitel a webshopokkal való kapcsolattartás, amikor a webshopban leadott rendelések alapján az eVIR rendszer vevői rendelést készít, vagy akár azonnal számlát állít ki. Erről egy általánosabb leírás itt található: szamla_xml_felulet

Minta linkek webshophoz

• Cikktörzs, teljes, XML

https://evir.hu/cegnev/cgi-bin/index.cgi?xml=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%3Cesystem%3E%3Cclick%3E%3Cdata%3E%3Cre
cord%3E<field><name>dok</name><value>torzs_cikk_aktiv_termekek_lista</value></field><field><name>token</name><value>jMuPFcKJdyKYqMZ7iGiLpxF/32k</valu
e></field><field><name>lang</name><value>HU</value></field>%3C%2Frecord%3E%3C%2Fdata%3E%3C%2Fclick%3E%3C%2Fesystem%3E

• Cikktörzs, testreszabott listával, XML

https://evir.hu/cegnev/cgi-bin/index.cgi?xml=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%3Cesystem%3E%3Cclick%3E%3Cdata%3E%3Cre
cord%3E<field><name>dok</name><value>torzs_cikk_aktiv_termekek_lista</value></field><field><name>param</name><value>nosave_list_stat_id,1</value></fi
eld><field><name>token</name><value>jMuPFcKJdyKYqMZ7iGiLpxF/32k</value></field><field><name>lang</name><value>HU</value></field>%3C%2Frecord%3E%3C%2F
data%3E%3C%2Fclick%3E%3C%2Fesystem%3E

• Cikktörzs, teljes, CSV

https://evir.hu/cegnev/cgi-bin/index.cgi?dok=torzs_cikk_aktiv_termekek_lista&dokop=csv,3&token=jMuPFcKJdyKYqMZ7iGiLpxF/32k

• Cikktörzs, testreszabott listával, CSV

https://evir.hu/cegnev/cgi-bin/index.cgi?dok=torzs_cikk_aktiv_termekek_lista&param=nosave_list_stat_id,1&dokop=csv,3&token=jMuPFcKJdyKYqMZ7iGiLpxF/32k

• Cikktörzs, teljes, JSON

https://evir.hu/cegnev/cgi-bin/index.cgi?dok=torzs_cikk_aktiv_termekek_lista&dokop=json,1&token=jMuPFcKJdyKYqMZ7iGiLpxF/32k

• Cikktörzs, testreszabott lista, JSON

https://evir.hu/cegnev/cgi-bin/index.cgi?dok=torzs_cikk_aktiv_termekek_lista&param=nosave_list_stat_id,1&dokop=json,1&token=jMuPFcKJdyKYqMZ7iGiLpxF/32k

• Raktárkészlet, teljes XML

https://evir.hu/cegnev/cgi-bin/index.cgi?xml=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%3Cesystem%3E%3Cclick%3E%3Cdata%3E%3Cre
cord%3E<field><name>dok</name><value>raktar_lista_osszesitett</value></field><field><name>token</name><value>jMuPFcKJdyKYqMZ7iGiLpxF/32k</value></fie
ld><field><name>lang</name><value>HU</value></field>%3C%2Frecord%3E%3C%2Fdata%3E%3C%2Fclick%3E%3C%2Fesystem%3E

• Raktárkészlet, testreszabott listával, XML

https://evir.hu/cegnev/cgi-bin/index.cgi?xml=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%3Cesystem%3E%3Cclick%3E%3Cdata%3E%3Cre
cord%3E<field><name>dok</name><value>raktar_lista_osszesitett</value></field><field><name>param</name><value>nosave_list_stat_id,2</value></field><fi
eld><name>token</name><value>jMuPFcKJdyKYqMZ7iGiLpxF/32k</value></field><field><name>lang</name><value>HU</value></field>%3C%2Frecord%3E%3C%2Fdata%3E
%3C%2Fclick%3E%3C%2Fesystem%3E

• Raktárkészlet, teljes CSV

https://evir.hu/cegnev/cgi-bin/index.cgi?dok=raktar_lista_osszesitett&dokop=csv,3&token=jMuPFcKJdyKYqMZ7iGiLpxF/32k

• Raktárkészlet, testreszabott listával, CSV

https://evir.hu/cegnev/cgi-bin/index.cgi?dok=raktar_lista_osszesitett&param=nosave_list_stat_id,2&dokop=csv,3&token=jMuPFcKJdyKYqMZ7iGiLpxF/32k

• Raktárkészlet, teljes JSON

https://evir.hu/cegnev/cgi-bin/index.cgi?dok=raktar_lista_osszesitett&dokop=json,1&token=jMuPFcKJdyKYqMZ7iGiLpxF/32k

• Raktárkészlet, testreszabott listával, JSON

https://evir.hu/cegnev/cgi-bin/index.cgi?dok=raktar_lista_osszesitett&param=nosave_list_stat_id,2&dokop=json,1&token=jMuPFcKJdyKYqMZ7iGiLpxF/32k

Egyedi rendszerek és/vagy a fentiektől eltérő igények esetében szívesen segítünk a konkrét rendszer-, és ügyfélspecifikus URL-ek létrehozásában.

Kapcsolódó oldalak:

• Cikktörzs és készlet API lekérdezések
• Számla API