NAV Online Számla API a gyakorlatban: kulcsgenerálás és a leggyakoribb hibaüzenetek

Ez a cikk két dolgot ad. Egyrészt a technikai felhasználó és a két kulcs létrehozását lépésről lépésre, másrészt nyolc valós hibakódot azzal együtt, hogy mit jelentenek és mit kell velük kezdeni. Minden technikai állítás a NAV hivatalos interfész-specifikációjából származik (3.0 verzió, 2026. február 12-i kiadás) — 2026. szeptemberi állapot.

Mit csinál a NAV Online Számla API, és hol szakad el a lánc?

A NAV Online Számla API egy REST-interfész, amin keresztül a számlázó program emberi beavatkozás nélkül küldi be a számlaadatokat. A lánc három lépésből áll, és mindhárom külön el tud szakadni: token kérése, adatbeküldés, majd a feldolgozás eredményének lekérdezése.

A program először a /tokenExchange végponton kér egy egyszer használatos adatszolgáltatási tokent. A token az adózóra szól, és a kiadástól számítva jelenleg 5 percig érvényes. A NAV ezt a tokent a technikai felhasználó cserekulcsával kódolva adja ki — a kliensnek AES-128 ECB algoritmussal kell visszafejtenie, és a dekódolt értéket visszaküldenie.

A második lépés a /manageInvoice hívás. Egy kérésben és egy tokennel legfeljebb 100 számla adata küldhető be, a teljes HTTP POST body pedig egyik operációban sem lehet nagyobb 10 megabájtnál. Itt a szerver még csak a kérést ellenőrzi és hitelesít; a tényleges számlaadat-feldolgozás aszinkron módon fut le. Sikeres befogadásra tranzakcióazonosítót kap vissza.

A harmadik lépés a /queryTransactionStatus: ezzel derül ki, hogy az egyes számlák át is mentek-e az üzleti validáción. Aki itt megáll — mert a HTTP 200 jó jelnek tűnt —, az a bevallás összeállításánál fogja megtudni, hogy fél tucat számla adatszolgáltatása hiányzik. A NAV szervere jellemzően 200 ms alatt válaszol, a szinkron hívások blokkoló timeout-ja 5000 ms, az abszolút timeout 60 másodperc. Fontos részlet: a válasz nélkül maradt kérés önmagában nem jelenti a beküldés sikertelenségét, ezt utólag a /queryTransactionList operációval kell tisztázni.

A számok és a végpontok a NAV hivatalos fejlesztői dokumentációjából valók. Ha az automatizálás alapfogalmai újak, érdemes a KKV-útmutatónkkal kezdeni.

Kulcsgenerálás lépésről lépésre: technikai felhasználó, aláíró- és cserekulcs

Az API-t webes felhasználóval nem lehet használni: külön technikai felhasználót kell létrehozni, és ezt kizárólag az adózó elsődleges felhasználója teheti meg az Online Számla webfelületén. A technikai felhasználóhoz két kulcs tartozik, és mindkettőt ugyanaz az elsődleges felhasználó generálja.

1. Érvényes regisztráció. Az adózónak regisztrálva kell lennie az Online Számla rendszerben. A regisztráció a webfelületen kezdeményezhető.
2. Belépés elsődleges felhasználóval. Másodlagos vagy webes felhasználó nem hozhat létre technikai felhasználót, és kulcsot sem generálhat.
3. Technikai felhasználó létrehozása. A Felhasználók menüben, új felhasználó felvételénél a technikai felhasználó típust kell választani, és jelszót kell adni neki.
4. Jogosultságok kiosztása. Itt dől el, hogy a felhasználó küldhet-e be számlaadatot, és hogy a beküldött adatokat utólag lekérdezheti-e. A lekérdezési jogot az elsődleges felhasználónak külön kell megadnia.
5. Kulcsgenerálás. Mentés után a Részletek fülön indítható a kulcsgenerálás. Innen kerül elő az XML aláírókulcs és az XML cserekulcs.
6. Három érték kimásolása. Technikai felhasználónév, aláírókulcs, cserekulcs. Ez a három megy a szoftverbe. Kézzel gépelve garantált a hiba — másolja ki mindhármat.

Mire való a két kulcs?

Az aláírókulcs a kérés hitelesítéséhez kell: a requestSignature nevű hash alapjában szerepel, literálisan összefűzve. A cserekulcs ezzel szemben a tokent védi — ezzel kódolja a szerver az adatszolgáltatási tokent, és ezzel fejti vissza a kliens. Két különböző szerep, két különböző kulcs; felcserélve mindkettő hibát ad.

A technikai felhasználó jelszavából SHA-512 hash készül, a requestSignature viszont SHA3-512 (Keccak, FIPS 202). A két algoritmus neve hasonlít, a kimenetük nem: az XML-ben a cryptoType attribútum értéke a jelszónál kizárólag SHA-512, az aláírásnál kizárólag SHA3-512 lehet. Ha ezek felcserélődnek, a NAV külön hibakóddal jelez.

Teszt és éles: két külön világ

A specifikáció ezen a ponton nem hagy értelmezési teret. A tesztkörnyezetben elvégzett regisztráció nem helyettesíti az éles környezetben elvégzett regisztrációt, és a tesztkörnyezetben létrehozott technikai felhasználók, kulcsok nem használhatók élesben. A teszt webfelület az onlineszamla-test.nav.gov.hu, a teszt API az api-test.onlineszamla.nav.gov.hu címen érhető el; élesben ugyanez a „test” nélkül. Az endpoint URL-jét ezért környezetenként paraméterezhetővé kell tenni.

Egy figyelmeztetés, ami sok kiesést okoz: a kulcsgenerálás megismétlése új kulcsokat állít elő, a korábbiak pedig érvényüket vesztik. Aki „biztos, ami biztos” alapon újragenerál, azzal minden olyan rendszert leállít, amelyikbe a régi értékek be voltak írva. Erre több szoftvergyártó súgója is külön figyelmeztet, például a Kulcs-Soft technikai felhasználó leírása. Ugyanez igaz a törlésre: a technikai felhasználó törlése a kapcsolatot is megszünteti.

Nyolc hibaüzenet, ami a gyakorlatban tényleg előjön

A NAV kétféle hibát ad vissza: a technikai és authentikációs hibák szinkron módon, a HTTP-válaszban érkeznek, az üzleti validációs hibák viszont csak a tranzakció státuszának lekérdezésekor derülnek ki. Az alábbi nyolc adja a bejáratási időszak problémáinak túlnyomó részét.

Két további kód, amivel üzemszerűen találkozni fog. A FORBIDDEN azt jelenti, hogy a technikai felhasználó nem jogosult az adott endpoint hívására — ezt az elsődleges felhasználó tudja orvosolni. A MAINTENANCE_MODE pedig karbantartást jelez: ilyenkor nincs mit javítani, a kérést később kell megismételni. A teljes, magyar nyelvű hibakód-listát több szolgáltató is közzétette, például a HolaSzámla hibakód-gyűjteménye.

Miért bukik el a requestSignature, ha jónak tűnik a kulcs?

Mert az aláírás nem a kulcs, hanem egy karakterre pontos szöveg-összefűzés hash-e. Elég egy felesleges kettőspont vagy egy kisbetű, és a szerver más értéket kap, mint amit a kliens kiszámolt. Négy hiba viszi el az esetek nagy részét.

1. Az időbélyeg maszkja. A header timestamp tag tartalmazhat ezredmásodpercet (például 2017-12-30T18:25:45.000Z), az aláírás alapjába viszont ez a dátum szeparátorok, időzóna és ezredmásodperc nélkül, yyyyMMddHHmmss formában kerül: 20171230182545. Aki a tag értékét másolja be nyersen, biztosan mellétrafál.

2. A nagybetűsítés. Nemcsak a végeredményt kell nagybetűsíteni, hanem az indexenkénti rész-hash-eket is, még az összefűzés előtt.

3. A rész-hash-ek forrása. A /manageInvoice és a /manageAnnulment operációnál az aláírás alapja nem csak a requestId + időbélyeg + aláírókulcs hármas. Minden indexhez tartozik egy külön hash, amely a művelet nevének (például CREATE) és a base64 tartalomnak az összefűzéséből képződik. Gyakori tévedés, hogy valaki a nyers számla-XML-t hasheli a base64 sztring helyett.

4. Az újrapróbálkozás csapdája. Az aláírás-hibával elutasított kérés requestId-ja beleszámít az egyediség-vizsgálatba. Aki ugyanazzal az azonosítóval próbálkozik újra, az a következő körben már REQUEST_ID_NOT_UNIQUE hibát kap, és azt hiszi, új problémát talált.

A leggyorsabb hibakeresési módszer nem a kód olvasása. A specifikáció tartalmaz egy teljesen kidolgozott, fiktív példát: adott requestId, időbélyeg és aláírókulcs mellett közli a rész-hash-eket és a végső aláírást is. Ha a saját kódja karakterre visszaadja ezt a dokumentált kimenetet, az algoritmus jó, és a hiba az adatokban van. A NAV külön önellenőrzési fejezetet is közöl online eszközökkel: aktuális UTC középidő, base64, SHA-512, SHA3-512, AES-128 ECB (PKCS5PADDING beállítással) és XML-séma-ellenőrzés.

Mikor elég a számlázóprogram beépített kapcsolata, és mikor kell egyedi integráció?

A legtöbb cégnek elég a beépített kapcsolat, és nem is éri meg mást építeni. Az egyedi integráció akkor kerül elő, ha a számla nem abban a programban keletkezik, amelyik be tudná küldeni — vagy ha a NAV-adatokra visszafelé is szükség van.

Elég a beépített kapcsolat, ha…

• minden kimenő számla egyetlen számlázóprogramban készül;
• a programnak van NAV-modulja, és a három érték beírása után a beépített tesztgomb sikeres kapcsolatot jelez;
• nem kell a NAV-ból adatot visszakérdezni, csak beküldeni;
• van, aki napi szinten átnézi a sikertelen tranzakciókat a NAV webfelületén.

Egyedi integráció kell, ha…

• a számla egy zárt, több évtizedes vállalatirányítási rendszerben keletkezik, amelyhez nincs NAV-modul, és a gyártó nem is fog írni;
• több rendszer állít ki párhuzamosan számlát, és az adatszolgáltatást egy helyen kell összefogni;
• a NAV-oldali adatokat le kell kérdezni egyeztetéshez — a saját számlázóprogram ezt nem tudja megtenni Ön helyett;
• a hibát nem hónap végén, hanem percekben kell észrevenni, tehát riasztás kell a sikertelen tranzakcióra;
• a technikai érvénytelenítés (/manageAnnulment) is a folyamat része.

Nálunk a második eset a tipikus. A meglévő rendszerekre építünk, alapból csak olvasunk, és írni csak kifejezett kérésre, ellenőrzötten írunk — egy 20+ éves, zárt vállalatirányítási rendszernél ez nem óvatoskodás, hanem az egyetlen felelős megközelítés. A bejövő oldalon ugyanez a logika fut: 470+ számlát dolgozott fel automatikusan az a rendszerünk, ahol a gép olvas, a kód ellenőriz, és csak az ellenőrzött adat megy tovább. Ha a beküldött és a visszakérdezett adatból rendszeres egyeztető kimutatás is kell, az már a riport-automatizálás terepe.

Mikor nem éri meg egyedi NAV-integrációt építeni?

Ha havi húsz-harminc számlát állít ki egyetlen programban, és annak a NAV-kapcsolata működik, akkor semmit nem nyer egy egyedi integrációval. A build-projektjeink 300 000 Ft-tól indulnak, és ezt az összeget kizárólag olyan probléma indokolja, amit a beépített úton nem lehet megoldani.

Három tipikus eset, amikor mi mondjuk, hogy ne csinálja:

• Egyszeri kulcshiba. Ha INVALID_SECURITY_USER vagy INVALID_REQUEST_SIGNATURE jön, de a szoftvere egyébként küldi a számlákat, ez húsz perc a NAV webfelületén. Nem projekt.
• Küszöbön álló szoftvercsere. Ha egy éven belül számlázóprogramot vált, várja meg. Az új program NAV-modulja könnyen feleslegessé teszi a most megírt integrációt.
• Nincs, aki üzemeltesse. Egy NAV-integráció nem kész, hanem karbantartott: a NAV verziót vált és új validációkat vezet be. Aki nem tervez üzemeltetést, annak jobb a gyártói modullal maradnia. Nálunk ez 30 000 Ft/hó-tól kezdődik, és felügyeletet, hibariasztást, havi 2 óra fejlesztési keretet és havi összefoglalót tartalmaz.

A saját kezű út

Az egészet meg lehet írni magának is, és ez nem szégyen. A specifikáció nyilvános, a tesztkörnyezet ingyenes, a NAV pedig nyilvános GitHub-tárat tart fenn a sémákkal és a fejlesztői kérdésekkel. Ha van XML-ben és hash-elésben járatos fejlesztője, egy működő beküldés és státuszlekérdezés reálisan pár nap.

Az idő nem itt megy el, hanem a hibaágakon. A specifikáció blokkoló üzleti validációs táblázata 80 hibakódot sorol fel — fordított adózás, gyűjtőszámla, devizás árfolyam, módosító okiratok sorszámozása —, és ezek nem beküldéskor, hanem a státuszlekérdezésben jönnek elő. Ehhez jön az újrapróbálkozás-logika, a token lejáratának kezelése, a karbantartási ablak és a naplózás. Becsléskor ezekkel érdemes számolni, nem a boldog úttal.

Gyakori kérdések

Kell-e külön regisztrálni a NAV teszt- és éles rendszerébe?

Igen. A NAV interfész-specifikációja szerint a tesztkörnyezetben elvégzett regisztráció nem helyettesíti az éles környezetben elvégzett regisztrációt, és a tesztkörnyezetben létrehozott technikai felhasználók, kulcsok sem használhatók élesben. Gyakorlatilag mindent kétszer kell végigcsinálni: regisztráció, technikai felhasználó, jogosultságok, kulcsgenerálás. A két környezet API-címe is eltér, ezért az endpoint URL-jét környezetenként kell paraméterezni.

Mennyi ideig érvényes az adatszolgáltatási token?

A specifikáció szerint jelenleg 5 percig, a kiadástól számítva, és a pontos lejárati időpontot a válasz is tartalmazza. A tokent minden adatszolgáltatás előtt újra meg kell kérni. Egy tokennel legfeljebb 100 számla adata küldhető be, a lejáratot pedig egzakt módon a szerveridő dönti el, ezért kötegelt beküldésnél érdemes számolni a kliensoldali óraeltéréssel.

Miért kapok INVALID_REQUEST_SIGNATURE hibát, ha jó a kulcs?

Az aláírás egy karakterre pontos összefűzés hash-e, ezért a kulcson kívül három dolog szokott elrontani. Az időbélyeg maszkja, amely yyyyMMddHHmmss formátumú, UTC-ben, szeparátorok, időzóna és ezredmásodperc nélkül. A nagybetűsítés hiánya. Végül a manageInvoice hívásnál az indexenkénti rész-hash-ek, amelyeket a művelet nevéből és a base64 tartalomból kell képezni, nem a nyers XML-ből.

Hány számlát küldhetek egy NAV-kérésben?

A sémaleíró szerint egy adatszolgáltatásban legfeljebb 100 számla adata küldhető be, tehát egy HTTP kérésben és egy adatszolgáltatási tokennel ennyi fér el. A teljes HTTP POST body mérete egyik operációban sem haladhatja meg a 10 megabájtot. Ha az XML ennél nagyobb, a számla-XML-t a base64 kódolás előtt GZIP-pel tömöríteni kell; a szerver tömörítetlenül legfeljebb 15 megabájtot enged meg.

Mennyibe kerül egy egyedi NAV Online Számla integráció?

Nálunk a build-projektek 300 000 Ft-tól indulnak, óradíj nincs, és az első működő automatizálás két héten belül elkészül. Az üzemeltetés 30 000 Ft/hó-tól kezdődik: felügyelet, hibariasztás, havi 2 óra fejlesztési keret és havi összefoglaló. Ha előbb a folyamatot kell tisztázni, a folyamat-audit 120 000 Ft fix díjú és egy hetes, 60 napon belüli megrendelésnél pedig beszámít a projektárba.

A következő lépés

Ha egyelőre csak azt szeretné látni, mennyi kézi munka áll a számlázás körül, kezdje a megtakarítás-kalkulátorral: pár perc, és kap egy számot, amiről érdemes beszélni. Ha viszont az adatszolgáltatás konkrétan elakadt, vagy a számla olyan rendszerben keletkezik, amelyikhez nincs NAV-modul, egy rövid konzultáción megmondjuk, kell-e ide egyáltalán fejlesztés. Ha a kép még nem tiszta, a folyamat-audit 120 000 Ft fix díjért, egy hét alatt világítja át a folyamatot: legalább öt megtérülő lehetőséget találunk, vagy visszajár az ár — 60 napon belüli megrendelésnél pedig beszámít a projektárba.