Technikai adatküldési útikalauz a Lictor interface-hez

A LICTOR rendszer elektronikusan, xml formátumban fogadja az adatokat a szerződött ügyfelektől, melyet levélben kell eljuttatni a megadott (ld. III.) címre. Ez a leírás az interface-szel, az abban lévő adatokkal és azoknak emailbe illesztésével foglalkozik, valamint az eddig felmerült kérdésekre adott válaszokat is tartalmazza.


I. Az XML file és tartalma

Az XML interface formátumát a lictor_minosites_interface.xsd séma rögzíti. A teszt.xml file egy, ennek az xsd-nek megfelelő példa. Minden tag-et az xml szabványnak megfelelően kell nyitni/zárni, a dátumokat 1975-08-14 formátumban írni, a sorrendiség szigorú betartásával, azaz például a nyilvántartó mező nem előzheti meg a cégjegyzékszám mezőt.

A következő két sor kell legyen az xml elején:

<?xml version="1.0" encoding="iso-8859-2"?> <lictorinterface xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation='lictor_minosites_interface.xsd'>

Adatmezők leírása:

<sajatlid> - a rendszerbe belépéskor kapott azonosító, pontosan egy előfordulás engedélyezett, kötelező
<kuldesdatum> - az adatok küldésének dátuma (nem feltétlenül az aznapi dátum), pontosan egy előfordulás engedélyezett, kötelező
<adat > - ez a mező fogja közre az egy partnerre vonatkozó partner és számla információkat. Legalább egy előfordulás kötelező.

Partner adatok:

<partner > - partnerinformációkat fog közre, adaton belül pontosan egy előfordulás kötelező
<partnerkod > - egyedi partner kódja az Önök rendszerében, kötelező
<cegjegyzekszam > - partner cégjegyzékszáma, nem kötelező
<nyilvantarto > - a cégjegyzéket gondozó hatóság, nem kötelező
<adoszam > - partner adószáma, nem kötelező
<nev > - a partner használatos, rövidebb neve, kötelező
<teljesnev > - a partner teljes neve, nem kötelező
<varos > - város, kötelező
<utca > - utca, kötelező
<irszam > - irányítószám, kötelező
<orszagkod > - ISO3166- os (két betus) országkód. Egy ; -vel elválasztott, betölthető iso3166 országadatokat mellékelünk (iso3166.txt), kötelező
<telefon > - partner telefonszáma, nem kötelező
<fax > - partner fax száma, nem kötelező
<ervtol > - partner érvényességének kezdete /dátum/, nem kötelező
<ervig > - partner érvényességének vége (megszűnés)/dátum/, nem kötelező
<vedett > - I vagy N lehet. Partner kintlevőségének statisztikában szerepeltetése. I -esetén az információ nem szerepel a grafikonon, kötelező
<iban > - partner IBAN kódja, nem kötelező

Számla adatok:

<szamla > - számla adatait fogja közre, számlánként kell nyitni zárni, elhagyható, ha csak a partner adatait kell átállítani (pl. védettre), egyébként tetszőleges számú előfordulás engedélyezett
<szamlaszam > - egyedi számla szám az Önök rendszerében, kötelező
<szamladatum > - a számla kiállításának dátuma, kötelező
<lejarat > - számla lejáratának dátuma, kötelező
<targynap > - az utolsó számlakiegyenlítés napja, amennyiben nem áll rendelkezésre, a küldés dátumát kell behelyettesíteni, kötelező
<nyitottosszeg > - a számla nyitott összege, kötelező

Az előállított xml fájl helyességét a LiXMLValidate java program segítségével ellenőrizhetjük. A gépünkön telepítve kell lennie egy legalább 1.3 verziójú java futtatókörnyezetnek, de ajánlott a legfrissebb 1.4.1 verzió (http://java.sun.com/j2se/1.4.1/download.html). Amennyiben a mellékelt xercesimpl.jar és xmlparserapis.jar fájlok az aktuális könyvtárban vannak a következő paranccsal ellenőrizhetjük az xml fájlt:

java -cp xercesimpl.jar;xmlparserapis.jar;. LiXMLValidate teszt.xml

Ugyanazon könyvtárba másoljuk be az xsd és xml fájlt is, illetve ha máshová tesszük, figyelni kell a hivatkozási és elérési útvonalakra. A teszt.bat a fenti parancsot futtatja.

A program az xsd definíciói szerint végigolvassa az inputfájlt, minden megtalált taget és tartalmát kiírja. Ha az xsd definíciójával ellentétes adatot olvas, arról hibaüzenetet ad, illetve a program lefutásakor kiírja az összes előfordult hiba számát. Ha ez nulla, az xml megfelel a formai követelményeknek. Ha nullától különböző, akkor nem feltétlenül a jelzett számú hiba van az xml-ben, hiszen egy elírás, rossz tag, több megkötést is megszeghet.

Az xml filet iso-8859-2 típusú kódolással kérjük előállítani!

Az előbb említett állományokat a következő csomagolt file tartalmazza: lictor_interface.zip

Adattartalommal kapcsolatos információk, eddig felmerült problémák alapján:

- A Lictor rendszer forint alapon működik, így a devizás számlákat esetében ezek forint összegét kell szerepeltetni az interfaceban a nyitottság mértékének megfelelően (ld. következő pont). Feltételezzük, hogy az Önök rendszerében is tárolják minden számla forintosított összegét ill. a forintosításhoz szükséges adatokat, hisz pl. az ÁFA bevallás forint alapon kell történjen.

- A küldött XML fileban azon partnereknek ill. azoknak azon számláinak kell szerepelniük, melyeknek van legalább 1000 forint értékben, 23 napon túli ki nem fizetett tartozása. Tehát pl. ha GLAURUNG Kft. egy 100000 forintos számlája már lejárt legalább 23 napja és csak 10000 forintot fizetett ki belőle, akkor 90000 összeget kell a <nyitottosszeg> tagben küldeni ennél a számlánál. A <targynap> tag azt a dátumot tartalmazza, amikor az utolsó részletfizetés (jelen esetben a 10000 ft. kifizetése, ill. annak számlához rendelése) megtörtént. Ez a dátum az esetleges pontozási (bank-számla összerendelés) hibáinak korrigálására szolgál és csak akkor van jelentősége, ha a tárgynap a lejárati dátum után van, hisz a grafikonon csak a lejárat napjától jelennek meg az adatok. Ha a partner a lejárat után kifizet további 20000 ft-ot, akkor következő alkalommal már csak 70000 ft nyitott összeggel fog szerepelni az interfaceben az adott számla. Ha kifizet további 69500 forintot, akkor a következő küldésben már egyáltalán nem kell szerepeltetni ezt a partnert (feltéve persze, hogy nem volt másik nyitott számlája). Fontos hogy ne a számla összege, hanem csak a még ki nem fizetett (devizásnál a forintosított) összeg kerüljön a fileba!

- A küldés dátuma csak >= lehet az előző küldés dátumánál, a lekérdezések eredményeként kapott grafikon képzésénél ezt a sorrendet vesszük figyelembe.

- A partnerek adatainak átadásakor a tag legyen korrekt, azaz ugyanúgy, mint az Önök által küldött teljes névben. Igazából itt arra gondoltunk, hogy pl. a Masped esetében a név lehet MASPED RT., a teljes név pedig MASPED ELSŐ MAGYAR ÁLTALÁNOS SZÁLLÍTMÁNYOZÁSI RT. Ha a rendszerükben nem tárolnak ilyen értelemben vett rövidebb nevet, akkor kérjük a név tag helyén is a teljes névben küldött nevet elküldeni. Ha csak rövidebb nevet tárolnak, akkor a <teljesnev> tag üres maradhat.

- Az XML-ben nincs általános escape karakter. A speciális jeleket egyenként más-más külön karaktersorozattal kell kódolni. A speciális karakterek fordítótábláját mellékelem:

& - &amp;
< - &lt;
> - &gt;
' - '
" - &quot;

Ne felejtsük el a pontosvesszőt a végéről!

- Az interfaceban a dátum típusú mezőket nem szabad üresen hagyni (ez jelen esetben az <ervtol> és <ervig> tagaknél lehet probléma, hisz a többi dátum amúgy is kötelező), ezért kérjük, hogy amennyiben egyik vagy másik adat nem áll rendelkezésre, akkor ne írják magát a taget se (sem a kezdő sem a záró taget) az állományba, mert az üres adat "nem valós dátum" hibát okoz.

Tehát pl.

<ervtol>2001-01-01</ervtol>
<ervig></ervig>

helyett, csak
<ervtol>2001-01-01</ervtol>

szerepeljen a fájlban.

- Ahogy a fentiekből látható, egyes mezők (ilyen a város, utca, irányítószám is) kötelezően kitöltendőek. Amennyiben ténylegesen nem áll rendelkezésre kötelező adat (pl. cim, vagy irányítószám), akkor annak a helyére N/A -t kell írni, semmiképp sem szabad üresen hagyni az ilyen tag-et, mert a betöltés sikertelen lesz. Persze az lenne a legjobb, ha a kötelező adatok tényleges információt tartalmaznának...

II. A levél összeállítása

Az üzemszerű használat során majd az interface filet két módon küldhetik el. Amennyiben az xml file mérete nem túl nagy, azaz mondjuk 50kb alatt van, akkor küldhetik a levél törzsében, de akkor semmilyen más szöveget ne írjonak bele. Ha a méret ennél nagyobb, akkor kérjük zippelni a fájlt és csatolmányként küldeni. Mindkét esetben kérnénk, hogy a levél tárgyában tüntessék fel az Önök Lictor azonosítóját és a küldés dátumát (év-hónap-nap, annak ellenére, hogy az magában az xml file elején is szerepel). Példa a tárgyra:

10000000 2003-03-04

Amennyiben csatolmányként küldik az adtokat a csatolt file neve legyen a következő pl.: 10000000_2003-03-04.zip, tehát gyakorlatilag ugyanaz, mint a levél tárgya, _ -al összekapcsolva, zip kiterjesztéssel. Ekkor a levél törzsében lévő szöveget nem vesszük figyelembe.

III. Levél küldése

Mint láthatjuk az interface-nek elég sok formai és tartalmi követelménynek kell, hogy eleget tegyen. Addig, amíg mindezek hiánytalanuk teljesülnek, kérjük a próba interface-eket a szabo.szabolcs@ccsi.hu címre küldeni, hogy mi is le tudjuk azt ellenőrizni, ill. esetleges módosítási javaslatokat tenni. Jóváhagyás után a hetente küldött adatokat a interface@lictor.hu -ra kell majd küldeni.

IV. Hozzáférés a rendszerhez

Amennyiben megtörténik az első szemantikailag is megfelelő teljes interface elküldése éles adatokkal, a betöltés után lehetővé válik az Önök számára a rendszerhez való hozzáférés. Ehhez el kell küldeni azoknak a referenseknek az adatait, akik majd a rendszert használni fogják. A következő adatokra van szükségünk:

- [*] referens teljes neve
- [*] referens email címe
- telefon
- mobil
- fax

A *-al megjelölt adatok kötelezőek.

A kívánt referenseket beadminisztrálását referensenként egy-egy ellenőrzőlevéllel jelezzük. Ha ezt megkapja az adott felhasználó, akkor a webes lekérdezés eredménye is el fog jozzá jutni.



Bármilyen interfésszel ill. egyéb, a Lictor rendszerrel kapcsolatos kérdést a szabo.szabolcs@ccsi.hu címen tehetik fel.

Sikeres munkát kívánunk!