===== 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->[[evir:rendszer:felhasznalok:felhasznalok|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 [[evir:rendszer:felhasznalok:jogosultsagi_rendszer|jogosultság]]ot, 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. {{ :evir:rendszer:api:api_token.png |}} Biztonsági okokból a tokent kizárólag létrehozáskor, vagy [[evir:rendszer:felhasznaloi_fiok:jelszo_csere|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: [[spec:xml_interface|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: [[evir:rendszer:api:api_szamla|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%3Edoklista_partnerektokenjMuPFcKJdyKYqMZ7iGiLpxF%2B32klangHU%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,,¶m=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ó: [[evir:rendszer:api:szamla_xml_felulet|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%3Edoktorzs_cikk_aktiv_termekek_listatokenjMuPFcKJdyKYqMZ7iGiLpxF/32klangHU%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%3Edoktorzs_cikk_aktiv_termekek_listaparamnosave_list_stat_id,1tokenjMuPFcKJdyKYqMZ7iGiLpxF/32klangHU%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¶m=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¶m=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%3Edokraktar_lista_osszesitetttokenjMuPFcKJdyKYqMZ7iGiLpxF/32klangHU%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%3Edokraktar_lista_osszesitettparamnosave_list_stat_id,2tokenjMuPFcKJdyKYqMZ7iGiLpxF/32klangHU%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¶m=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¶m=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: * [[evir:rendszer:api:api_cikk_raktar|Cikktörzs és készlet API lekérdezések]] * [[evir:rendszer:api:api_szamla|Számla API]]