Az eVIR rendszer lehetőséget biztosít külső rendszer számára számla készítésére.
Az általános API leírásban szerepelnek az alapok, ezért itt már csak a specifikus részek szerepelnek.
A kommunikáció JSON alapkon zajlik, a követező módon:
https://evir.hu/cegnev/cgi-bin/index.cgi?json={"token":"jMuPFcKJdyKYqMZ7iGiLpxF/32k","dok":"szamla_api_felvesz",...........}
A json form mező egy hash, melynek felépítése:
{
token: a klienst azonosító eVIR felhasználó tokenje
dok: "szamla_api_felvesz" stringet tartalmazó kötelező elem.
button: "b_felvesz" stringet tartalmazó kötelező elem.
muvelet: "0","M1","P1","M1P2","P1M2","P1M0" hogyan jöjjön létre a számla (lásd lentebb)
partner_id: partner_id
partner_tipus: "cég" vagy "személy" értékeket tartalmazó string
partner_nev: partner neve
partner_cim_orszag: ország kétbetűs kódja, (pontosan 2 karakter)
partner_cim_orszag_nev: ország megnevezése. Megegyezik az eVIR törzsadatai szerinti névvel
partner_cim_varos: település neve (maximum 40 karakter)
partner_cim_cim: közterület, házszám stb. (maximum 60 karakter)
partner_cim_irszam: irányítószám (maximum 10 karakter)
partner_adoszam: adószám (maximum 30 karakter)
email_cim: email cím (maximum 100 karakter), "valami@example.com" formátumban.
arkat: árkategória (ha nincs megadva, akkor a partnerhez rendelt, vagy alapértelmezett árkategória lesz)
fizmod: fizetési mód, (beállítás szerinti hatással a teljdat, fizhat mezőkre) ha nincs megadva, akkor a rendszer alapértelmezett fizetési módja lesz)
teljdat: teljesítési dátum (ha nincs megadva, fizetési mód szerint lesz)
fizhat: fizetési határidő (ha nincs megadva, fizetési mód szerint lesz)
megjegyzes: Opcionális megjegyzés a számlára
nyelv: a bizonylat nyelve (ha nincs megadva, HU)
tetel_mezok: [ ... ] egy tomb, ami a tételsorokat tartalmazza. egy tételsor egy hash
}
egy tétel adatai: {
tetel_tipusa: "termék" vagy "szolgáltatás" (kötelezŐ)
tetel_forrasraktar: annak a raktárnak a kódja, ahonnan a terméket eladja. szolgáltatás esetén ignorálva.
tetel_cikkszam: a termék vagy szolgáltatás cikkszáma (kötelező)
tetel_menny: numerikus mező, az eladott mennyiség (pozitív szám)
tetel_netto: nettó eladási egységár numerikus mező.
tetel_megj: tételhez kapcsolódó megjegyzés szöveg (opcionális)
}
token, dok, button, muvelet: mindig kötelező megadni
tetel_mezok: legalább egy tételt meg kell adni.
email_cim: Akkor és csak akkor kell megadni, ha ki kell küldeni számlát/másolatot/értesítést emailben. azaz a muvelet tartalmaz egy 'M' betűt is.
muvelet: lehetséges értékei
Ezen értékek NEM MINDEN ESETBEN adhatóak meg. A megadható értékek a beállítások függvényében változnak, az alábbi táblázat szerint. Rosszul megadott esetben vagy hibaüzenet, vagy a beállítások szerinti működés történik.
| muvelet | email_ertesito modul installálva van | Első példány emailben | PDF csatolmány |
|---|---|---|---|
| 0 | mindegy | mindegy | mindegy |
| P1 | mindegy | mindegy | mindegy |
| M1,M1P2 | igen | igen | igen |
| P1M2 | igen | nem | igen |
| P1M0 | igen | mindegy | nem |
nyelv: opcionális. A bizonylat ezen a nyelven fog létrejönni (ha ez engedélyezve van a konfigurációban)
arkat: opcionális. A „Törzsadatok→Cikkszámok→Árkategóriák→Árkategória-lista” menüből elérhető lista „Kategória” oszlopából választható érték, ahol a típus „értékesítési”. A kiválasztott árkategória pénznemében készül el a számla. Az árkategóriának pénznemen felüli jelentősége akkor van, ha a tételeknél nincs megadva „tetel_netto” egységár, mert ilyenkor az árképzés szabályai szerint az árkategóriához tartozó áron fog szerepelni a tétel a bizonylaton.
fizmod: opcionális. A „Törzsadatok→Pénzügyi→Fizetési módok” menüben elérhető fizetési módok közül, a „Fizetési mód neve” oszlop értékei közül választhat azon feltételekkel, hogy: „Számlázáskor használható”. Az esetleges „Készpénzes” jelölésű fizetési módhoz ha kapcsolódik pénztárbizonylat készítés, az ezen az interface-en keresztül nem érhető el, ezért ilyen fizetési módok használata kerülendő.
fizhat, teljdat: dátum mező formátuma „YYYY-MM-DD” (aka ÉÉÉV-HÓ-NP) értéküket befolyásolhatja a fizetési módnál lévő beállítások, de használható vagy létrehozható olyan fizetési mód ami nem befolyásolja.
pelda JSON adat
{
"token":"gnfdkjgjnkjnfdshjfdk",
"dok":"szamla_api_felvesz",
"button":"b_felvesz",
"nyelv":"HU",
"muvelet":"0",
"tetel_mezok":[
{
"tetel_netto":2430,
"tetel_megj":"XXL kék",
"tetel_tipusa":"termék",
"tetel_cikkszam":"c2",
"tetel_menny":3,
"tetel_forrasraktar":"r1"
}
],
"partner_id":4,
"megjegyzes":"Példa számla",
"arkat":"ar1",
"fizmod":"átutalás",
}
Visszatérési értékek:
A rendszer a beállításoktól és a művelettől függően vagy PDF, vagy JSON választ készít. Sikeres számla rögzítés esetén, nyomtatás nélkül a lentihez hasonló.
Ha a visszatérési érték tartalmazza a 'status':'OK' formában a status kulcshoz az OK értéket, akkor a „szamlaszam” kulcsban található a kiállított számla száma.
Más üzenetekkel együtt ezek megtalálhatóak a „message” listában is, ha az uzenethez tartozó „level” értéke „SysInfo” akkor ott a „message” üzenet „szamlaszam=SZ2015000110” formában az egyelőség jel után a létrehozott bizonylat (számla) számát fogja tartalmazni. Ha ilyen üzenet nincs, akkor feltételezhető, hogy nem jött létre a bizonylat.
[
{
"status":"OK",
"szamlaszam":"SZ2015000110",
"choice":{
// nem dokumentált feature adatai
},
"framename":"main",
"message":[
{
"level":"Info",
"time":"2015.10.30 21:59:38.67",
"message":"Számla rögzítve"
},
{
"level":"SysInfo",
"time":"2015.10.30 21:59:38.67",
"message":"szamlaszam=SZ2015000110"
},
"level":"SysInfo",
"time":"2015.10.30 21:59:38.67",
"message":"status=OK"
},
],
"result":null
}
]
Egy példa hibaüzenet formátuma:
A „message” struktúrája megegyezik a sikeres esettel. Azonban a „level” kulcs értékei sokfélék lehetnek.
Hibás esetekben:
[
{
"choice":{
// nem dokumentált
},
"framename":"main",
"message":[
{
"level":"Fatal",
"time":"2015.10.30 22:11:52.31",
"message":"Rendszerhiba: myexception (user): váratlan hibaüzenet at ../include/dok/szamla/szamla_api_felulet.pm line 346 captured by kernel"
}
],
"result":[
{
"info":{
"errormessage":null
},
"name":"error"
}
]
}
]
Egyéb eredmények lehetnek ezenkívül még:
Számla stornó gépi interface. A rendszerben kiállított számlákat a számlaszám ismeretében API híváson keresztül is lehet stornózni, nem csak a felületről. Ez a számla készítéshez nagyon hasonló módon történik:
http://....../cgi-bin/index.cgi?json={"dok":"szamla_storno_api_felvesz","sszlaszam":"SZ...","token":"..." ,"muvelet":"P1"}
a JSON adat egy hash, melynek kulcsai az alábbi jelentésekkel bírnak
token: a klienst azonosító evir felhasználó tokenje (evir felhasználó jelszavának módosításakor kiíródik) dok: "szamla_storno_api_felvesz" stringet tartalmazó kötelező elem. sszlaszam: a stornózandó számla számát tartalmazó kötelező elem. muvelet: "0","P1" hogyan jöjjön létre a számla (lásd fentebb a számla készítésnél)
A token, dok, sszlaszam, muvelet elemeket mindig kötelező megadni
A művelet hívására válaszul egy pdf dokumentum érkezik, ami a storno számlát tartalmazza. Hiba esetén a számla készítésnél megadott szerkezetű JSON hibaüzenet érkezik.
Termék esetében kizárólag a cikktörzsben szereplő, készleten levő elemet lehet a bizonylatra tenni, de szolgáltatás esetében megoldható a rugalmasabb kezelés. Lehetőség van arra, hogy olyan szolgáltatás kerüljön az API-n keresztül kiszámlázásra, amelynek az adatai még nem szerepelnek a cikktörzsben. Ekkor a számlázandó tétel adatai között meg kell adni azokat a kötelező adatokat is, amelyek egyébként a cikktörzsből érkeznének. Az adatokat a tétel adatai között kell megadni a normál adatokon túlmenően:
tetel_cikk_rogzites: "szolg_fix" vagy "szolg_gen" a rögzítés módja szerint tetel_cikk_megnevezes: A szolgáltatás megnevezése tetel_cikk_afa: A szolgáltatáshoz tartozó áfa tetel_cikk_megys: A szolgáltatás mennyiségi egysége (pl. darab, óra) tetel_cikk_unit: A legkisebb egység, aminek a többszöröse a mennyiség lehet. (általában pl 1)
A szolgáltatás rögzítéséhez ezenkívül felhasználja a tetel_cikkszam mezőt is, ami egyébként is kötelezően megadandó a számla készítéséhez.
Példa adat a tetel_mezok értékére.
...
"tetel_mezok":[
{
"tetel_netto":10000,
"tetel_megj":"Kiszállással együtt",
"tetel_tipusa":"szolgáltatás",
"tetel_cikkszam":"c5",
"tetel_menny":2,
"tetel_cikk_rogzites":"szolg_fix",
"tetel_cikk_megnevezes","Karbantartás
"tetel_cikk_afa":"27.00",
"tetel_cikk_megys":"óra",
"tetel_cikk_unit":1,
}
],
...