NOSZA Segédprogram

dokumentum verzió : 1.0

Technikai dokumentáció

A segédprogram által feldolgozásra kerülő számla bizonylatok fájljait a programban monitorozásra felvett könyvtárakba szükséges menteni.
Az elfogadott formátumokról a formátumdokumentáció és adóhatósági XML konverzió oldalakon talál bővebb információt.

A segédprogram a monitorozott mappába illetve annak almappáiba menti a bizonylatok feldolgozásának eredményét.

FŐMAPPA

status_log.csv oszlopok (; „pontosvessző” elválasztással, utf-8 kódolással):
1. fájlnév
2. a fájl sha1 algoritmussal képzett ellenőrző kódja
3. jelentés azonosító (request_id) -> NOSZA rendszer képzi
4. tranzakció azonosítója (transaction_id) -> NAV rendszere képzi a jelentés azonosító alapján
5. státusz
  - PENDING - A fájl elküldés alatt van, feldolgozásra vár, esetleg feloldható hiba miatti újra küldésre várakozik, amelyet a NOSZA periodikusan megkísérel.
  - OK - A küldés sikeres, hiba és figyelmeztetés nem volt
  - WARN - A NAV befogadta a számlát, azonban lehetséges tartalmi hibákra figyelmeztet. A hibák ellenőrzését a felhasználó felelőssége elvégezni, és gondoskodni a számlák javításáról (sztornó / módosító számla).
  - ERROR - A NOSZA vagy a NAV elutasította a számlát, ennek általában formai hiba az oka. (XML séma validáció)
  - IGNORE - A számla adótartalma nem érte el a megadott korlátot (alapesetben 100,000 Ft), nem került beküldésre.
6. státusz üzenet, részletesebb magyarázat
7. utolsó státuszváltozás dátuma
8. NAV által generált hiba lista az adott számlához, json formátumban (ha még nincs, akkor üres sztring)
9. A NAV által visszaadott hiba listában szereplő hibakódok egyetlen sztringbe konkatenálva, függőleges vonal karakterekkel (|) elválasztva
A status_log.csv mindig a számlák legutolsó státuszát tartalmazza. (Az azonos névvel, de különböző tartalommal bekerült számlák külön soron szerepelnek, nem írják felül egymás státuszát.)
last_check.txt:
Tartalma egyetlen időbélyeg, amely az adott könyvtár utolsó teljes beolvasásának az ideje. (Formátum pl: 2018-06-28T07:38:46.687Z)
A program a normál fájlműveletek (bemásolás, módosítás, törlés) figyelésén túl percenként is ellenőrzi a mappák tartalmát és jelenlétét. Ekkor módosítja ezt az időbélyeget.
Ha az időbélyeg túl régi, akkor a program valószínűleg nem fut, vagy nincs az adott mappa figyelésére beállítva.
config.xml:
Itt vannak a beállítások. A fájl módosításakor a megfigyelt mappákból a program automatikusan újraolvassa a konfigurációt, így ez külső programból is szerkeszthető. Törlés esetén a NOSZA is elveszíti a beállításokat!
event.log:
A program saját belső folyamatainak naplója, elsősorban a NOSZA segédprogram fejlesztői számára van jelentősége.

ALMAPPÁK

Az almappákba az eredeti fájlok módosított fájlnévvel kerülnek be akkor, amikor végleges státuszt kapnak (kivétel a PENDING mappa, ahová sikeres elküldés után már bekerülnek). Pl. 'xxxxxxxx.xml' -> 'xxxxxxxx_[sha1 ellenőrző kód].xml' (az sha1 ellenőrző kód megtalálható a napló fájlokban)
/done < ide kerülnek az OK vagy WARN státusszal visszaérkezett számlák
/error < ide kerülnek a nem befogadott számlák
/pending < azok a számlák kerülnek ide, amelyek elküldésre kerültek, de a NAV még nem dolgozta fel, vagy arról nem érkezett válasz
/ignore < nem feldolgozott (IGNORE státuszú) számlák
A /done és /error almappákban található 'archive_[évszám].csv' naplófájlok struktúrája azonos a status_log.csv struktúrájával.
Ezek az almappákban található naplófájlok minden új számla mappába bekerülésekor új sorral bővülnek.

CONFIG.XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config>
  <account>
    <accountId>00000000</accountId> <!-- Nosza fiók azonosító, a szoftverfejlesztő fiókjának 8 jegyű azonosítója -->
    <softwareApiKey>00000000000000000000000000000000</softwareApiKey> <!-- NOSZA software API kulcs, a számlázóprogram API kulcsa, amivel a NOSZA segédprogram együttműködik -->
  </account>
  <client>
    <clientName>Codemakers Kft</clientName> <!-- Az ügyfél vállalkozásának neve, akinek a nevében az adatküldés történik -->
    <clientTaxNumber>23905504-2-06</clientTaxNumber> <!-- Az ügyfél adószáma, aki a számlát kiállítja -->
  </client>
  <folder>
    <sendCSV>1</sendCSV> <!-- Mappabeállítások / CSV fájlok figyelése -->
    <sendJSON>0</sendJSON> <!-- Mappabeállítások / JSON fájlok figyelése -->
    <sendTXT>0</sendTXT> <!-- Mappabeállítások / TXT fájlok figyelése -->
    <sendXML>1</sendXML> <!-- Mappabeállítások / XML fájlok figyelése -->
  </folder>
  <software>
    <softwareDevContact>info@codemakers.hu</softwareDevContact> <!-- Számlázó program adatai, kitöltése automatikusan megtörténik a NOSZA fiókban rögzített adatok alapján -->
    <softwareDevCountryCode></softwareDevCountryCode>
    <softwareDevName></softwareDevName>
    <softwareDevTaxNumber></softwareDevTaxNumber>
    <softwareId></softwareId>
    <softwareMainVersion/>
    <softwareName></softwareName>
    <softwareOperation></softwareOperation>
  </software>
  <user>
    <userLogin>string</userLogin> <!-- Technikai felhasználó Login neve -->
    <userPasswordHash>string128</userPasswordHash> <!-- 128 karakter hosszú hexadecimális string / a technikai felhasználó jelszavából sha512 kódolási algoritmussal képzett hash érték hexadecimális reprezentációja, nagybetűkkel -->
    <userTaxNumber>11111111-1-11</userTaxNumber> <!-- A technikai felhasználóhoz tartozó cég adószáma, aki a jelentést teszi -->
    <userXmlExchangeKey>string</userXmlExchangeKey> <!-- A technikai felhasználóhoz tartozó XML cserekulcs  -->
    <userXmlKey>string</userXmlKey> <!-- A technikai felhasználóhoz tartozó XML aláírókulcs -->
  </user>
</config>